Выражения в 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-ответа, за исключением случаев, когда для директивы, принимающей выражение, указано иное. Функция req_novary может использоваться для предотвращения добавления имен в заголовок Vary.

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