Выражения в Apache HTTP Server

Исторически существует несколько вариантов синтаксиса выражений, используемых для задания условий в различных модулях Apache HTTP Server. В настоящее время ведётся работа над тем, чтобы использовать во всех директивах конфигурации только один вариант, называемый ap_expr. В этом документе описан анализатор выражений ap_expr.

Выражение ap_expr предназначено для замены большинства других вариантов выражений в HTTPD. Например, устаревшие выражения SSLRequire можно заменить на Require expr.

Грамматика в нотации Бэкуса — Наура

Форма Бэкуса — Наура (BNF) — это способ записи контекстно-свободных грамматик, часто используемый для описания синтаксиса языков программирования. В большинстве случаев выражения используются для задания логических значений. В этом случае начальным символом в BNF является expr. Однако некоторые директивы, например LogMessage, принимают выражения, результатом которых является строковое значение. Для них начальным символом в BNF является string.

expr        ::= "true" | "false"
              | "!" expr
              | expr "&&" expr
              | expr "||" expr
              | "(" expr ")"
              | comp

comp        ::= stringcomp
              | integercomp
              | unaryop word
              | word binaryop word
              | word "in" "{" wordlist "}"
              | word "in" listfunction
              | word "=~" regex
              | word "!~" regex


stringcomp  ::= word "==" word
              | word "!=" word
              | word "<"  word
              | word "<=" word
              | word ">"  word
              | word ">=" word

integercomp ::= word "-eq" word | word "eq" word
              | word "-ne" word | word "ne" word
              | word "-lt" word | word "lt" word
              | word "-le" word | word "le" word
              | word "-gt" word | word "gt" word
              | word "-ge" word | word "ge" word

wordlist    ::= word
              | wordlist "," word

word        ::= word "." word
              | digit
              | "'" string "'"
              | """ string """
              | variable
              | rebackref
              | function

string      ::= stringpart
              | string stringpart

stringpart  ::= cstring
              | variable
              | rebackref

cstring     ::= ...
digit       ::= [0-9]+

variable    ::= "%{" varname "}"
              | "%{" funcname ":" funcargs "}"

rebackref   ::= "$" [0-9]

function     ::= funcname "(" word ")"

listfunction ::= listfuncname "(" word ")"

Переменные

Анализатор выражений предоставляет ряд переменных вида %{HTTP_HOST}. Обратите внимание, что значение переменной может зависеть от этапа обработки запроса, на котором она вычисляется. Например, выражение, используемое в директиве <If >, вычисляется до выполнения аутентификации. Поэтому в этом случае значение %{REMOTE_USER} не будет задано.

Следующие переменные предоставляют значения указанных заголовков HTTP-запроса. Значения других заголовков можно получить с помощью функции req. Использование этих переменных может привести к добавлению имени заголовка в заголовок Vary ответа HTTP, за исключением случаев, отдельно отмеченных для директивы, принимающей выражение. Чтобы избежать такого поведения, можно использовать функцию req_novary.

Другие переменные, связанные с запросом

Прочие переменные

Некоторые модули регистрируют дополнительные переменные; см., например, mod_ssl.

Бинарные операторы

За исключением некоторых встроенных операторов сравнения, бинарные операторы имеют вид "-[a-zA-Z][a-zA-Z0-9_]+", то есть состоят из дефиса и как минимум двух символов. Регистр букв в имени не учитывается. Модули могут регистрировать дополнительные бинарные операторы.

Операторы сравнения

Другие бинарные операторы

Унарные операторы

Унарные операторы принимают один аргумент и имеют вид "-[a-zA-Z]", то есть состоят из дефиса и одного символа. Регистр букв в имени имеет значение. Модули могут регистрировать дополнительные унарные операторы.

Операторы, отмеченные как «ограниченные», недоступны в некоторых модулях, например mod_include.

Функции

Обычные функции, возвращающие строковое значение, принимают одну строку в качестве аргумента и возвращают строку. Регистр букв в именах функций не учитывается. Модули могут регистрировать дополнительные функции.

Функции, отмеченные как «ограниченные» в последнем столбце, недоступны в некоторых модулях, например mod_include.

При использовании функций, отмеченных как «порядок выполнения» в последнем столбце, следует учитывать порядок выполнения различных компонентов сервера, особенно если функция используется в директиве <If>, которая выполняется на относительно раннем этапе.

При использовании функций req или http имя заголовка автоматически добавляется в заголовок Vary ответа HTTP, за исключением случаев, отдельно отмеченных для директивы, принимающей выражение. Чтобы предотвратить добавление имён в заголовок Vary, можно использовать функцию req_novary.

Помимо функций, возвращающих строковое значение, существуют функции, возвращающие списки: они принимают одну строку в качестве аргумента и возвращают список слов, то есть список строк. Список слов можно использовать со специальным оператором -in. Регистр букв в именах функций не учитывается. Модули могут регистрировать дополнительные функции.

Встроенных функций, возвращающих списки, нет. mod_ssl предоставляет PeerExtList. Подробности см. в описании SSLRequire (однако PeerExtList также можно использовать вне SSLRequire).

Примеры выражений

В следующих примерах показано, как можно использовать выражения для проверки запросов:

# Compare the host name to example.com and redirect to www.example.com if it matches
<If "%{HTTP_HOST} == 'example.com'">
    Redirect permanent "/" "http://www.example.com/"
</If>

# Force text/plain if requesting a file with the query string contains 'forcetext'
<If "%{QUERY_STRING} =~ /forcetext/">
    ForceType text/plain
</If>

# Only allow access to this content during business hours
<Directory "/foo/bar/business">
    Require expr %{TIME_HOUR} -gt 9 && %{TIME_HOUR} -lt 17
</Directory>

# Check a HTTP header for a list of values
<If "%{HTTP:X-example-header} in { 'foo', 'bar', 'baz' }">
    Header set matched true
</If>

# Check an environment variable for a regular expression, negated.
<If "! reqenv('REDIRECT_FOO') =~ /bar/">
    Header set matched true
</If>

# Check result of URI mapping by running in Directory context with -f
<Directory "/var/www">
    AddEncoding x-gzip gz
<If "-f '%{REQUEST_FILENAME}.unzipme' && ! %{HTTP:Accept-Encoding} =~ /gzip/">
      SetOutputFilter INFLATE
</If>
</Directory>

# Check against the client IP
<If "-R '192.168.1.0/24'">
    Header set matched true
</If>

# Function example in boolean context
<If "md5('foo') == 'acbd18db4cc2f85cedef654fccc4a4d8'">
  Header set checksum-matched true
</If>

# Function example in string context
Header set foo-checksum "expr=%{md5:foo}"

# This delays the evaluation of the condition clause compared to <If>
Header always set CustomHeader my-value "expr=%{REQUEST_URI} =~ m#^/special_path\.php$#"

# Conditional logging
CustomLog logs/access-errors.log common "expr=%{REQUEST_STATUS} >= 400"
CustomLog logs/access-errors-specific.log common "expr=%{REQUEST_STATUS} -in {'405','410'}"

Прочее

$0 ... $9

Обратные ссылки регулярных выражений

Строки $0 ... $9 позволяют ссылаться на группы захвата из ранее выполненных регулярных выражений, успешно нашедших совпадение. Обычно их можно использовать только в том же выражении, что и соответствующее регулярное выражение, однако некоторые модули допускают особые варианты использования.

Сравнение с SSLRequire

Синтаксис ap_expr в основном является расширением синтаксиса устаревшей директивы SSLRequire. Различия описаны в документации SSLRequire.

История версий

Функция req_novary доступна в версии 2.4.4 и новее.