Модуль Apache mod_include

<!--#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 байта будет выведен как «1K».

<!--#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. Помимо стандартного окружения CGI, сценарию будут доступны переменные include.

Пример

<!--#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. Помимо обычного набора переменных CGI, команде доступны переменные include.

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

Кроме того, на некоторых платформах, например Win32, а также в Unix при использовании suexec, нельзя передавать аргументы команде в директиве exec или иным образом включать в команду пробелы. Поэтому приведенный ниже пример будет работать в Unix при конфигурации без suexec, но не даст нужного результата в 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

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

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

file

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

virtual

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

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

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

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

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

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

onerror

Значение — путь URL (%-кодированный), который отображается в случае неудачной предыдущей попытки включить файл или виртуальный атрибут. Чтобы атрибут действовал, его необходимо указать после атрибутов file или virtual, к которым он применяется. Если попытка включить путь onerror завершится неудачей или атрибут 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

Дополнительная информация в конце пути. Дополнительные сведения о PATH_INFO см. в директиве AcceptPathInfo.

DOCUMENT_URI

Путь URL документа, запрошенного пользователем (%-декодированный). Обратите внимание: при вложенных включаемых файлах это не 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. Для краткости внутри mod_include также доступно имя функции v.

В приведенном ниже примере будет выведено «из локальной сети», если 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

истина, если string не пустая

-A string

истина, если доступ к 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

Сравнение string1 и string2. Если string2 имеет вид /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

Сравнение string1 и string2. Обратите внимание: строки сравниваются буквально (с использованием strcmp(3)). Поэтому строка «100» меньше строки «20».

( test_condition )

истина, если test_condition истинно

! test_condition

истина, если test_condition ложно

test_condition1 && test_condition2

истина, если оба условия test_condition1 и test_condition2 истинны

test_condition1 || test_condition2

истина, если истинно хотя бы одно из условий test_condition1 или test_condition2

«=» и «!=» имеют более высокий приоритет, чем «&&» и «||». Наивысший приоритет у «!». Таким образом, следующие выражения эквивалентны:

<!--#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