Модуль Apache mod_include

Резюме

Этот модуль предоставляет фильтр, который будет обрабатывать файлы перед отправкой клиенту. Обработка контролируется специальными SGML-комментариями, называемыми элементами. Эти элементы позволяют условный текст, включение других файлов или программ, а также установку и вывод переменных окружения.

Включение Server-Side Includes

Server Side Includes реализуются с помощью INCLUDES фильтра. Если документам, содержащим директивы server-side include, присвоено расширение .shtml, следующие директивы заставят Apache их обработать и назначить результативному документу MIME-тип text/html:

AddType text/html .shtml
AddOutputFilter INCLUDES .shtml

Для каталогов, содержащих файлы shtml (обычно в разделе <Directory>, но эта директива также допустима в файлах .htaccess, если AllowOverride Options установлено), необходимо указать следующую директиву:

Options +Includes

Для обратной совместимости, server-parsed обработчик также активирует фильтр INCLUDES. Кроме того, Apache активирует фильтр INCLUDES для любого документа с MIME-типом text/x-server-parsed-html или text/x-server-parsed-html3 (и результат вывода будет иметь MIME-тип text/html).

Дополнительную информацию см. в нашем учебнике по Server Side Includes.

PATH_INFO с Server Side Includes

Файлы, обрабатываемые для server-side includes, по умолчанию больше не принимают запросы с PATH_INFO (информацией о конечном пути имени файла). Вы можете использовать директиву AcceptPathInfo для настройки сервера на прием запросов с PATH_INFO.

Доступные элементы

Документ анализируется как документ HTML со специальными командами, вставленными в виде SGML-комментариев. Команда имеет синтаксис:

<!--#element attribute=value attribute=value ... -->

Значение часто заключается в двойные кавычки, но также возможны одинарные кавычки (') и обратные кавычки (`). Многие команды допускают только одну пару атрибут-значение. Обратите внимание, что терминатор комментария (-->) должен предшествовать пробелу, чтобы убедиться, что он не рассматривается как часть маркера SSI. Обратите внимание, что ведущий <!--# является одним маркером и не может содержать пробелы.

Допустимые элементы перечислены в следующей таблице:

Элементы SSI могут быть определены модулями, отличными от mod_include. Фактически, элемент exec предоставляется модулем mod_cgi, и он будет доступен только в том случае, если этот модуль загружен.

Элемент комментария

Эта команда ничего не выводит. Ее единственная цель — добавление комментариев в файл. Эти комментарии не выводятся.

Этот синтаксис доступен в версии 2.4.21 и более поздних.

<!--#comment Blah Blah Blah -->
or
<!--#comment text="Blah Blah Blah" -->

Элемент config

Эта команда контролирует различные аспекты анализа. Допустимые атрибуты:

echomsg (Apache 2.1 и более поздние версии)

Значение — сообщение, которое отправляется обратно клиенту, если элемент echo пытается вывести неопределенную переменную. Это переопределяет любые директивы SSIUndefinedEcho.

<!--#config echomsg="[Value Undefined]" -->

errmsg

Значение — сообщение, которое отправляется обратно клиенту, если при анализе документа возникла ошибка. Это переопределяет любые директивы SSIErrorMsg.

<!--#config errmsg="[Oops, something broke.]" -->

sizefmt

Значение устанавливает формат, используемый при отображении размера файла. Допустимые значения — bytes для количества в байтах или abbrev для количества в Кб или Мб соответственно, например, размер 1024 байта будет напечатан как «1К».

<!--#config sizefmt="abbrev" -->

timefmt

Значение — строка, используемая библиотекой strftime(3) для вывода дат.

<!--#config timefmt=""%R, %B %d, %Y"" -->

Элемент echo

Эта команда выводит одну из переменных include, определенных ниже. Если переменная не задана, результат определяется директивой SSIUndefinedEcho. Любые выводимые даты зависят от текущей конфигурации timefmt.

Атрибуты:

var

Значение — имя переменной для вывода.

decoding

Указывает, должен ли Apache удалить кодировку из переменной перед дальнейшей обработкой. По умолчанию — none, где декодирование не будет выполнено. Если установлено значение url, будет выполнено URL-декодирование (также известное как %-кодирование; это подходит для использования в URL-адресах, ссылках и т. д.). Если установлено значение urlencoded, будет удалена кодировка, совместимая с application/x-www-form-urlencoded (находится в строке запроса). Если установлено значение base64, будет выполнено декодирование base64, а если установлено значение entity, будет удалена кодировка HTML-сущностей. Декодирование выполняется до любого дальнейшего кодирования переменной. Несколько кодировок можно удалить, указав несколько кодировок через запятую. Настройка декодирования останется в силе до следующего атрибута декодирования или окончания элемента.

Атрибут decoding должен предшествовать соответствующему атрибуту var для его эффективной работы.

encoding

Указывает, как Apache должен закодировать специальные символы, содержащиеся в переменной, перед выводом. Если установлено значение none, кодирование не будет выполнено. Если установлено значение url, будет выполнено URL-кодирование (также известное как %-кодирование; это подходит для использования в URL-адресах, ссылках и т. д.). Если установлено значение urlencoded, вместо этого будет выполнено кодирование, совместимое с application/x-www-form-urlencoded, и оно должно использоваться со строками запроса. Если установлено значение base64, будет выполнено кодирование base64. В начале элемента echo значение по умолчанию устанавливается в entity, что приводит к кодировке сущностей (что подходит в контексте элемента HTML уровня блока, например, абзаца текста). Это можно изменить, добавив атрибут encoding, который останется в силе до следующего атрибута encoding или окончания элемента, в зависимости от того, что произойдет раньше.

Атрибут encoding должен предшествовать соответствующему атрибуту var для его эффективной работы.

Для предотвращения проблем с межсайтовым скриптингом, вы всегда должны кодировать данные, предоставленные пользователем.

Пример

<!--#echo encoding="entity" var="QUERY_STRING" -->

Элемент exec

Команда exec выполняет заданную командную строку или скрипт CGI. Она требует наличия mod_cgi на сервере. Если Options IncludesNOEXEC установлено, эта команда полностью отключена. Допустимые атрибуты:

cgi

Значение определяет (%-кодированный) URL-путь к скрипту CGI. Если путь не начинается с косой черты (/), то он считается относительным к текущему документу. Документ, на который ссылается этот путь, вызывается как скрипт CGI, даже если сервер обычно не распознает его как таковой. Однако каталог, содержащий скрипт, должен быть разрешен для скриптов CGI (с помощью ScriptAlias или Options ExecCGI).

Скрипт CGI получает PATH_INFO и строку запроса (QUERY_STRING) исходного запроса от клиента; они не могут быть указаны в пути URL. Переменные include будут доступны скрипту дополнительно к стандартной среде CGI.

Пример

<!--#exec cgi="/cgi-bin/example.cgi" -->

Если скрипт возвращает заголовок Location: вместо вывода, то он будет преобразован в HTML-якорь.

Элемент include virtual следует использовать вместо exec cgi. В частности, если вам нужно передать дополнительные аргументы в CGI-программу, используя строку запроса, это нельзя сделать с помощью exec cgi, но можно сделать с помощью include virtual, как показано здесь:

<!--#include virtual="/cgi-bin/example.cgi?argument=value" -->

cmd

Сервер выполнит заданную строку с помощью /bin/sh. Переменные include доступны для команды в дополнение к обычному набору переменных CGI.

Использование #include virtual почти всегда предпочтительнее использования #exec cgi или #exec cmd. Первый метод (#include virtual) использует стандартный механизм подзапросов Apache для включения файлов или скриптов. Он намного лучше протестирован и поддерживается.

Кроме того, на некоторых платформах, таких как Win32, и на Unix при использовании suexec, вы не можете передавать аргументы в команду в директиве exec или по-другому включать пробелы в команде. Таким образом, хотя следующее будет работать под конфигурацией без suexec на Unix, оно не даст желаемого результата под Win32 или при запуске suexec:

<!--#exec cmd="perl /path/to/perlscript arg1 arg2" -->

Элемент fsize

Эта команда выводит размер указанного файла, согласно спецификации формата sizefmt.

file

Значение — путь, относительный к каталогу, содержащему текущий обрабатываемый документ.

This file is <!--#fsize file="mod_include.html" --> bytes.

Значение file не может начинаться с косой черты (/) и не может содержать ../, чтобы не ссылаться на файл выше текущего каталога или вне корневого каталога документа. Попытка сделать это приведёт к сообщению об ошибке: The given path was above the root path.

virtual

Значение — (%-кодированный) URL-путь. Если он не начинается с косой черты (/), то считается относительным к текущему документу. Обратите внимание, что это не выводит размер любого CGI-вывода, а размер самого CGI-скрипта.

This file is <!--#fsize virtual="/docs/mod/mod_include.html" --> bytes.

Обратите внимание, что во многих случаях эти два значения идентичны. Однако атрибут file не учитывает псевдонимы URL-пространства.

Элемент flastmod

Эта команда выводит последнюю дату изменения указанного файла, с учётом спецификации формата timefmt. Атрибуты такие же, как у команды fsize.

Элемент include

Эта команда вставляет текст другого документа или файла в обрабатываемый файл. Любой включаемый файл подчиняется обычным правилам контроля доступа. Если каталог, содержащий обрабатываемый файл, имеет Параметры IncludesNOEXEC установленные, то включаться будут только документы с текстовым MIME-типом (text/plain, text/html и т.д.). В противном случае CGI-скрипты вызываются как обычно с использованием полного URL, указанного в команде, включая любые параметры запроса.

Атрибут определяет расположение документа и может встречаться более одного раза в элементе include; включение выполняется для каждого атрибута, указанного в команде include по очереди. Допустимые атрибуты:

file

Значение — путь, относительный к каталогу, содержащему текущий обрабатываемый документ. Он не может содержать ../, а также не может быть абсолютным путем. Таким образом, вы не можете включать файлы, которые находятся вне корневого каталога документа или выше текущего документа в структуре каталогов. Следует всегда использовать атрибут virtual вместо этого.

virtual

Значение — (%-кодированный) URL-путь. URL не может содержать схему или имя хоста, только путь и необязательные параметры запроса. Если он не начинается с косой черты (/), то считается относительным к текущему документу.

URL строится из атрибута, и вывод, который сервер вернул бы, если бы клиент обратился по URL, включается в обработанный вывод. Таким образом, файлы могут включаться вложенно.

Если указанный URL — CGI-программа, программа будет выполнена, и её вывод будет вставлен вместо директивы в обрабатываемом файле. Вы можете включить параметры запроса в CGI-URL:

<!--#include virtual="/cgi-bin/example.cgi?argument=value" -->

Следует использовать include virtual вместо exec cgi, чтобы включить вывод CGI-программ в HTML-документ.

Если директива KeptBodySize корректно настроена и допустима для данного включаемого файла, попытки отправки POST-запросов в окружающий HTML-документ будут переданы в подзапросы как POST-запросы. Без этой директивы все подзапросы обрабатываются как GET-запросы.

onerror

Значение — (%-кодированный) URL-путь, который отображается в случае неудачной предыдущей попытки включить файл или виртуальный атрибут. Для эффективности этот атрибут должен быть указан после атрибутов файла или виртуального атрибута, к которым он относится. Если попытка включить путь onerror терпит неудачу или если он не указан, будет включено стандартное сообщение об ошибке.

# Simple example
<!--#include virtual="/not-exist.html" onerror="/error.html" -->

# Dedicated onerror paths
<!--#include virtual="/path-a.html" onerror="/error-a.html" virtual="/path-b.html" onerror="/error-b.html" -->

Элемент printenv

Выводит текстовый список всех существующих переменных и их значений. Специальные символы кодируются сущностями (см. элемент echo для подробностей) перед выводом. Атрибуты отсутствуют.

<pre> <!--#printenv --> </pre>

Элемент set

Устанавливает значение переменной. Атрибуты:

var

Имя переменной, которую нужно установить.

value

Значение, которое нужно присвоить переменной.

decoding

Указывает, должен ли Apache удалить кодировку из переменной перед дальнейшей обработкой. По умолчанию none, где декодирование не выполняется. Если установлено url, urlencoded, base64 или entity, соответственно, будет выполнено декодирование URL, декодирование application/x-www-form-urlencoded, декодирование base64 или декодирование HTML-сущностей. Несколько декодирований можно указать, разделив их запятыми. Настройка декодирования останется в силе до тех пор, пока не встретится следующий атрибут декодирования или не завершится элемент. Атрибут decoding должен предшествовать соответствующему атрибуту var для его действия.

encoding

Указывает, как Apache должен кодировать специальные символы, содержащиеся в переменной, перед установкой их значений. По умолчанию none, где кодирование не выполняется. Если установлено url, urlencoding, base64 или entity, соответственно, будет выполнено кодирование URL, кодирование application/x-www-form-urlencoded, кодирование base64 или кодирование HTML-сущностей. Несколько кодирований можно указать, разделив их запятыми. Настройка кодирования останется в силе до тех пор, пока не встретится следующий атрибут кодирования или не завершится элемент. Атрибут encoding должен предшествовать соответствующему атрибуту var для его действия. Кодирования применяются после того, как все декодирования были удалены.

<!--#set var="category" value="help" -->

Переменные include

В дополнение к переменным стандартной среды CGI, они доступны для команды echo, для if и elif, а также для любой программы, вызываемой документом.

DATE_GMT

Текущая дата в Гринвичском среднем времени.

DATE_LOCAL

Текущая дата в местном часовом поясе.

DOCUMENT_ARGS

Эта переменная содержит строку параметров запроса активного SSI-документа или пустую строку, если параметры запроса не включены. Для подзапросов, вызванных через директиву SSI include, QUERY_STRING будет представлять параметры запроса подзапроса, а DOCUMENT_ARGS — параметры запроса SSI-документа. (Доступно в Apache HTTP Server 2.4.19 и более поздних версиях.)

DOCUMENT_NAME

Имя файла (без каталогов) документа, запрошенного пользователем.

DOCUMENT_PATH_INFO

Информация о хвостовом пути. См. директиву AcceptPathInfo для получения дополнительной информации о PATH_INFO.

DOCUMENT_URI

(Декодированный) URL-путь документа, запрошенного пользователем. Обратите внимание, что в случае вложенных файлов include это не URL текущего документа. Также обратите внимание, что если URL изменён внутренне (например, с помощью alias или directoryindex), отображается изменённый URL.

LAST_MODIFIED

Последняя дата изменения документа, запрошенного пользователем.

QUERY_STRING_UNESCAPED

Если в запросе активного SSI-документа присутствуют параметры запроса, эта переменная содержит (декодированные) параметры запроса, которые экранированы для использования в оболочке (специальные символы, такие как & и т.д., предваряются обратными слешами). Она не устанавливается, если параметры запроса отсутствуют. Используйте DOCUMENT_ARGS если экранирование оболочки не требуется.

USER_NAME

Имя пользователя владельца файла.

Подстановка переменных

Подстановка переменных выполняется внутри строковых литералов во многих случаях, где они могут быть разумно использованы в качестве аргументов для директивы SSI. Сюда входят директивы config, exec, flastmod, fsize, include, echo и set. Если SSILegacyExprParser установлено в on, подстановка также происходит в аргументах условных операторов. Вы можете вставить буквенный знак доллара в строку, используя обратный слэш:

<!--#set var="cur" value="\$test" -->

Если ссылка на переменную должна быть заменена в середине последовательности символов, которая может считаться допустимым идентификатором сама по себе, её можно разобрать, заключив ссылку в фигурные скобки, подобно подстановке в оболочке:

<!--#set var="Zed" value="${REMOTE_HOST}_${REQUEST_METHOD}" -->

Это приведёт к тому, что переменная Zed будет установлена в "X_Y", если REMOTE_HOST — "X" и REQUEST_METHOD — "Y".

Элементы управления потоком

Основные элементы управления потоком:

<!--#if expr="test_condition" -->
<!--#elif expr="test_condition" -->
<!--#else -->
<!--#endif -->

Элемент if работает как оператор if в языке программирования. Условие проверяется, и если результат истинный, то текст до следующего элемента elif, else или endif включается в поток вывода.

Операторы elif или else используются для вставки текста в поток вывода, если исходное test_condition ложно. Эти элементы являются необязательными.

Элемент endif завершает элемент if и является обязательным.

test_condition — булево выражение, которое следует синтаксису ap_expr. Синтаксис можно изменить, чтобы он соответствовал синтаксису Apache HTTPD 2.2.x, используя SSILegacyExprParser.

Переменные SSI, установленные с элементом var, экспортируются в среду запроса и могут быть доступны с помощью функции reqenv. В качестве сокращения также доступно имя функции v внутри mod_include.

В следующем примере будет выведено "из локальной сети", если IP-адрес клиента принадлежит подсети 10.0.0.0/8.

<!--#if expr='-R "10.0.0.0/8"' -->
 from local net
 <!--#else -->
 from somewhere else
 <!--#endif -->

В следующем примере будет выведено "foo is bar", если переменная foo установлена в значение "bar".

<!--#if expr='v("foo") = "bar"' -->
 foo is bar
 <!--#endif -->

Синтаксис выражений старого образца

В этом разделе описан синтаксис элемента #if expr если SSILegacyExprParser установлено в on.

string

true, если строка не пустая

-A string

true, если URL, представленный строкой, доступен по конфигурации, в противном случае false. Это полезно, когда контент на странице должен быть скрыт от пользователей, у которых нет разрешения на просмотр URL, например, ссылка на этот URL. Обратите внимание, что URL проверяется только на предоставление доступа, а не на существование URL.

Пример

<!--#if expr="-A /private" -->
 Click <a href="/private">here</a> to access private information.
 <!--#endif -->

string1 = string2
string1 == string2
string1 != string2

Сравнение строки1 со строкой2. Если строка2 имеет вид /string2/, она обрабатывается как регулярное выражение. Регулярные выражения реализуются движком PCRE и имеют тот же синтаксис, что и в perl 5. Обратите внимание, что == — это всего лишь псевдоним для = и ведет себя точно так же.

Если вы производите сопоставление с учетом положительных результатов (= или ==), вы можете захватить группированные части регулярного выражения. Захваченные части хранятся в специальных переменных $1 .. $9. Вся строка, сопоставленная с регулярным выражением, хранится в специальной переменной $0

Пример

<!--#if expr="$QUERY_STRING = /^sid=([a-zA-Z0-9]+)/" -->
 <!--#set var="session" value="$1" -->
 <!--#endif -->

string1 < string2
string1 <= string2
string1 > string2
string1 >= string2

Сравнение строки1 со строкой2. Обратите внимание, что строки сравниваются буквально (используя strcmp(3)). Поэтому строка "100" меньше, чем "20".

( test_condition )

true, если условие_теста истинно

! test_condition

true, если условие_теста ложно

test_condition1 && test_condition2

true, если оба условие_теста1 и условие_теста2 истинны

test_condition1 || test_condition2

true, если либо условие_теста1, либо условие_теста2 истинно

"=" и "!=" связываются сильнее, чем "&&" и "||". "!" связывается сильнее всего. Таким образом, следующие выражения эквивалентны:

<!--#if expr="$a = test1 && $b = test2" -->
<!--#if expr="($a = test1) && ($b = test2)" -->

Логические операторы && и || имеют одинаковый приоритет. Поэтому, если вы хотите связать такой оператор сильнее, используйте скобки.

Все, что не распознается как переменная или оператор, обрабатывается как строка. Строки также могут быть заключены в кавычки: 'string'. Незаключённые строки не могут содержать пробелы (пробелы и табуляции), поскольку они используются для разделения токенов, таких как переменные. Если несколько строк встречаются подряд, они конкатенируются с использованием пробелов. Например,

SSIEndTag tag

SSIEndTag "-->"

SSIEndTag "%>"

SSIErrorMsg message

SSIErrorMsg "[an error occurred while processing this directive]"

SSIErrorMsg "<!-- Error -->"

SSIETag on|off

SSIETag off

SSILastModified on|off

SSILastModified off

SSILegacyExprParser on|off

SSILegacyExprParser off

SSIStartTag tag

SSIStartTag "<!--#"

SSIStartTag "<%"
SSIEndTag   "%>"

<%printenv %>

SSITimeFormat formatstring

SSITimeFormat "%A, %d-%b-%Y %H:%M:%S %Z"

SSITimeFormat "%R, %B %d, %Y"

SSIUndefinedEcho string

SSIUndefinedEcho "(none)"

SSIUndefinedEcho "<!-- undef -->"

XBitHack on|off|full

XBitHack off