Модуль Apache mod_rewrite

Директива RewriteCond

RewriteCond TestString CondPattern [flags]

Директива RewriteCond определяет условие правила. Одна или несколько RewriteCond могут предшествовать директиве RewriteRule. Затем правило используется только в том случае, если текущее состояние URI соответствует его шаблону и если выполнены эти условия.

TestString — это строка, которая может содержать следующие расширенные конструкции помимо обычного текста:

• Обратная ссылка RewriteRule: Это обратные ссылки вида $N (0 <= N <= 9). $1 до $9 предоставляют доступ к сгруппированным частям (в скобках) шаблона из RewriteRule, которое соответствует текущему набору условий RewriteCond. $0 предоставляет доступ к всей строке, соответствующей шаблону.
• Обратная ссылка RewriteCond: Это обратные ссылки вида %N (0 <= N <= 9). %1 до %9 предоставляют доступ к сгруппированным частям (опять же, в скобках) шаблона из последней соответствующей RewriteCond в текущем наборе условий. %0 предоставляет доступ к всей строке, соответствующей шаблону.
• Расширения RewriteMap: Это расширения вида ${mapname:key|default}. См. документацию по RewriteMap для получения более подробной информации.
• Переменные сервера: Это переменные вида %{ ИМЯ_ПЕРЕМЕННОЙ }, где ИМЯ_ПЕРЕМЕННОЙ может быть строкой из следующего списка:

  HTTP-заголовки:	соединение и запрос:
  HTTP_ACCEPT HTTP_COOKIE HTTP_FORWARDED HTTP_HOST HTTP_PROXY_CONNECTION HTTP_REFERER HTTP_USER_AGENT	AUTH_TYPE CONN_REMOTE_ADDR CONTEXT_PREFIX CONTEXT_DOCUMENT_ROOT IPV6 PATH_INFO QUERY_STRING REMOTE_ADDR REMOTE_HOST REMOTE_IDENT REMOTE_PORT REMOTE_USER REQUEST_METHOD SCRIPT_FILENAME
  внутренние данные сервера:	дата и время:	специальные:
  DOCUMENT_ROOT SCRIPT_GROUP SCRIPT_USER SERVER_ADDR SERVER_ADMIN SERVER_NAME SERVER_PORT SERVER_PROTOCOL SERVER_SOFTWARE	TIME_YEAR TIME_MON TIME_DAY TIME_HOUR TIME_MIN TIME_SEC TIME_WDAY TIME	API_VERSION CONN_REMOTE_ADDR HTTPS IS_SUBREQ REMOTE_ADDR REQUEST_FILENAME REQUEST_SCHEME REQUEST_URI THE_REQUEST

  Эти переменные соответствуют одноимённым HTTP MIME-заголовкам, C-переменным сервера Apache HTTP или полям struct tm Unix-системы. Большинство из них документированы здесь или в другом месте руководства или в спецификации CGI.

  SERVER_NAME и SERVER_PORT зависят от значений UseCanonicalName и UseCanonicalPhysicalPort соответственно.

  Те, которые специфичны для mod_rewrite включают следующие.

  API_VERSION

  Это версия API модуля Apache httpd (внутренний интерфейс между сервером и модулем) в текущей сборке httpd, как определено в include/ap_mmn.h. Версия API модуля соответствует версии Apache httpd (например, в релизной версии Apache httpd 1.3.14 она составляет 19990320:10), но в основном интересует разработчиков модулей.

  CONN_REMOTE_ADDR

  С 2.4.8: IP-адрес узла-отправителя соединения (см. модуль mod_remoteip).

  HTTPS

  Будет содержать текст «on», если соединение использует SSL/TLS, или «off» в противном случае. (Эта переменная может безопасно использоваться независимо от того, загружен ли модуль mod_ssl).

  IS_SUBREQ

  Будет содержать «true», если обрабатываемый в данный момент запрос является подзапросом, и «false» в противном случае. Подзапросы могут генерироваться модулями, которым необходимо разрешить дополнительные файлы или URI для выполнения задач.

  REMOTE_ADDR

  IP-адрес удалённого узла (см. модуль mod_remoteip).

  REQUEST_FILENAME

  Полный локальный путь к файлу или скрипту, соответствующему запросу, если это уже определено сервером на момент обращения к REQUEST_FILENAME. В противном случае, например, в контексте виртуального хоста, это то же значение, что и REQUEST_URI. В зависимости от значения AcceptPathInfo, сервер мог использовать только некоторые ведущие компоненты REQUEST_URI для сопоставления запроса с файлом.

  REQUEST_SCHEME

  Будет содержать схему запроса (обычно «http» или «https»). Это значение может быть изменено с помощью ServerName.

  REQUEST_URI

  Компонент пути запрошенного URI, например, «/index.html». Это существенно исключает строку запроса, которая доступна как отдельная переменная QUERY_STRING.

  THE_REQUEST

  Полная строка HTTP-запроса, отправленная браузером на сервер (например, «GET /index.html HTTP/1.1»). Она не включает дополнительные заголовки, отправленные браузером. Это значение не было обработано (декодировано), в отличие от большинства других переменных ниже.

Если TestString имеет специальное значение expr, CondPattern будет обрабатываться как ap_expr. HTTP-заголовки, упомянутые в выражении, будут добавлены в заголовок Vary, если флаг novary не указан.

Другие моменты, которые следует учитывать:

1. Переменные SCRIPT_FILENAME и REQUEST_FILENAME содержат одинаковое значение — значение поля filename внутренней структуры Apache HTTP Server. Первое имя — это общеизвестное имя CGI-переменной, а второе — соответствующий аналог REQUEST_URI (который содержит значение поля uri структуры request_rec).

   Если произошла подстановка и перенаправление продолжается, значение обеих переменных будет обновлено соответственно.

   Если используется контекст сервера (т.е., до сопоставления запроса с файловой системой), SCRIPT_FILENAME и REQUEST_FILENAME не могут содержать полный локальный путь, поскольку путь неизвестен на этой стадии обработки. В этом случае обе переменные будут изначально содержать значение REQUEST_URI. Чтобы получить полный локальный путь к запросу в контексте сервера, используйте URL-просмотр вперёд %{LA-U:REQUEST_FILENAME} для определения окончательного значения REQUEST_FILENAME.

2. %{ENV:variable}, где переменная может быть любой переменной окружения, также доступна. Она ищется во внутренних структурах Apache httpd и (если не найдена там) через getenv() из процесса Apache httpd.
3. %{SSL:variable}, где переменная — имя переменной окружения SSL, может быть использована с загрузкой или без модуля mod_ssl, но всегда будет расширяться до пустой строки, если модуль не загружен. Например, %{SSL:SSL_CIPHER_USEKEYSIZE} может расширяться до 128. Эти переменные доступны даже без установки параметра StdEnvVars директивы SSLOptions.
4. %{HTTP:header}, где заголовок может быть любым именем HTTP MIME-заголовка, всегда может быть использован для получения значения заголовка, отправленного в HTTP-запросе. Например, %{HTTP:Proxy-Connection} — это значение HTTP-заголовка ``Proxy-Connection:''.

   Если HTTP-заголовок используется в условии, этот заголовок добавляется в заголовок Vary ответа в случае, если условие истинно для запроса. Он не добавляется, если условие ложно для запроса. Добавление HTTP-заголовка в заголовок Vary ответа необходимо для правильного кэширования.

   Следует учитывать, что условия следуют логике короткого замыкания в случае флага «ornext|OR», поэтому некоторые условия могут вообще не оцениваться.

5. %{LA-U:variable} может использоваться для предварительного просмотра, который выполняет внутренний (основанный на URL) подзапрос для определения окончательного значения переменной. Это может быть использовано для доступа к переменной для перенаправления, которая недоступна на текущем этапе, но будет установлена на более поздней фазе.

   Например, для перенаправления в соответствии с переменной REMOTE_USER из контекста сервера (файл httpd.conf) необходимо использовать %{LA-U:REMOTE_USER} — эта переменная устанавливается фазами авторизации, которые выполняются после фазы преобразования URL (во время которой работает mod_rewrite).

   С другой стороны, поскольку mod_rewrite реализует свой контекст по каталогам (файл .htaccess ) через фазу Fixup API и поскольку фазы авторизации выполняются перед этой фазой, в этом контексте можно использовать просто %{REMOTE_USER}.

6. %{LA-F:variable} может использоваться для выполнения внутреннего (основанного на имени файла) подзапроса для определения окончательного значения переменной. В большинстве случаев это то же самое, что и LA-U выше.

CondPattern — это шаблон условия, регулярное выражение, которое применяется к текущей TestString. TestString оценивается первым, прежде чем сопоставляться с CondPattern.

CondPattern обычно является регулярным выражением, совместимым с Perl, но доступен дополнительный синтаксис для выполнения других полезных проверок TestString:

1. Вы можете добавить к строке шаблона символ '!' (восклицательный знак), чтобы инвертировать результат условия, независимо от типа используемого CondPattern.
2. Вы можете выполнить лексикографическое сравнение строк:

   <CondPattern

   Лексикографически предшествует
   CondPattern обрабатывается как обычная строка и сравнивается лексикографически с TestString. Верно, если TestString лексикографически предшествует CondPattern.

   >CondPattern

   Лексикографически следует за
   CondPattern обрабатывается как обычная строка и сравнивается лексикографически с TestString. Верно, если TestString лексикографически следует за CondPattern.

   =CondPattern

   Лексикографически равно
   CondPattern обрабатывается как обычная строка и сравнивается лексикографически с TestString. Верно, если TestString лексикографически равно CondPattern (две строки точно равны, символ за символом). Если CondPattern равно "" (две кавычки), это сравнивает TestString с пустой строкой.

   <=CondPattern

   Лексикографически меньше или равно
   CondPattern обрабатывается как обычная строка и сравнивается лексикографически с TestString. Верно, если TestString лексикографически предшествует CondPattern или равно ему (две строки равны, символ за символом).

   >=CondPattern

   Лексикографически больше или равно
   CondPattern обрабатывается как обычная строка и сравнивается лексикографически с TestString. Верно, если TestString лексикографически следует за CondPattern или равно ему (две строки равны, символ за символом).

   Примечание

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

   RewriteCond %{HTTP_USER_AGENT} "=This Robot/1.0"

3. Вы можете выполнить сравнение целых чисел:

   -eq

   Числово равно
   TestString обрабатывается как целое число и сравнивается численно с CondPattern. Верно, если два значения численно равны.

   -ge

   Числово больше или равно
   TestString обрабатывается как целое число и сравнивается численно с CondPattern. Верно, если TestString численно больше или равно CondPattern.

   -gt

   Числово больше
   TestString обрабатывается как целое число и сравнивается численно с CondPattern. Верно, если TestString численно больше CondPattern.

   -le

   Числово меньше или равно
   TestString обрабатывается как целое число и сравнивается численно с CondPattern. Верно, если TestString численно меньше или равно CondPattern. Избегайте путаницы с -l, используя варианты -L или -h.

   -lt

   Числово меньше
   TestString обрабатывается как целое число и сравнивается численно с CondPattern. Верно, если TestString численно меньше CondPattern. Избегайте путаницы с -l, используя варианты -L или -h.

   -ne

   Числово не равно
   TestString обрабатывается как целое число и сравнивается численно с CondPattern. Верно, если два значения численно отличаются. Это эквивалентно !-eq.

4. Вы можете выполнить различные проверки атрибутов файлов:

   -d

   Является каталогом.
   TestString обрабатывается как путь и проверяется, существует ли он и является ли каталогом.

   -f

   Является обычным файлом.
   TestString обрабатывается как путь и проверяется, существует ли он и является ли обычным файлом.

   -F

   Существующий файл, через подзапрос.
   Проверяет, является ли TestString действительным файлом, доступным через все текущие средства контроля доступа сервера для этого пути. Это использует внутренний подзапрос, поэтому используйте с осторожностью — это может повлиять на производительность сервера!

   -h

   Символическая ссылка, соглашение bash.
   См. -l.

   -l

   Является символической ссылкой.
   TestString обрабатывается как путь и проверяется, существует ли он и является ли символической ссылкой. Также можно использовать соглашение bash -L или -h, если есть вероятность путаницы, например, при использовании тестов -lt или -le.

   -L

   Символическая ссылка, соглашение bash.
   См. -l.

   -s

   Является обычным файлом с размером.
   TestString обрабатывается как путь и проверяется, существует ли он и является ли обычным файлом с размером больше нуля.

   -U

   Существующий URL, через подзапрос.
   Проверяет, является ли TestString действительным URL-адресом, доступным через все текущие средства контроля доступа сервера для этого пути. Это использует внутренний подзапрос, поэтому используйте с осторожностью — это может повлиять на производительность сервера!

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

   -x

   Имеет разрешения на выполнение.
   TestString обрабатывается как путь и проверяется, существует ли он и имеет ли разрешения на выполнение. Эти разрешения определяются в соответствии с ОС.

   Например:

   RewriteCond /var/www/%{REQUEST_URI} !-f
   RewriteRule ^(.+) /other/archive/$1 [R]

5. Если TestString имеет специальное значение expr, CondPattern будет обрабатываться как ap_expr.

   В примере ниже -strmatch используется для сравнения REFERER с именем хоста сайта, чтобы заблокировать нежелательные ссылки на другие сайты.

   RewriteCond expr "! %{HTTP_REFERER} -strmatch '*://%{HTTP_HOST}/*'"
   RewriteRule "^/images" "-" [F]

Вы также можете установить специальные флаги для CondPattern, добавив [flags] в качестве третьего аргумента к директиве RewriteCond, где flags — это список флагов, разделённых запятыми:

• 'nocase|NC' (без учета регистра)
  Это делает тест нечувствительным к регистру — различия между 'A-Z' и 'a-z' игнорируются, как в расширенном TestString, так и в CondPattern. Этот флаг эффективен только для сравнений между TestString и CondPattern. Он не влияет на проверки файловой системы и подзапросов.
• 'ornext|OR' (или следующее условие)
  Используйте это для объединения условий правил с локальным ИЛИ вместо неявного И. Типичный пример:

  RewriteCond "%{REMOTE_HOST}"  "^host1"  [OR]
  RewriteCond "%{REMOTE_HOST}"  "^host2"  [OR]
  RewriteCond "%{REMOTE_HOST}"  "^host3"
  RewriteRule ...some special stuff for any of these hosts...

  Без этого флага вам пришлось бы писать пару условие/правило три раза.
• 'novary|NV' (без изменения)
  Если в условии используется заголовок HTTP, этот флаг предотвращает добавление этого заголовка в заголовок Vary ответа.
  Использование этого флага может нарушить правильное кэширование ответа, если представление этого ответа зависит от значения этого заголовка. Поэтому этот флаг следует использовать только если смысл заголовка Vary хорошо понятен.

Пример:

Чтобы переписать домашнюю страницу сайта в соответствии с заголовком «User-Agent:» запроса, можно использовать следующее:

RewriteCond  "%{HTTP_USER_AGENT}"  "(iPhone|Blackberry|Android)"
RewriteRule  "^/$"                 "/homepage.mobile.html"  [L]

RewriteRule  "^/$"                 "/homepage.std.html"     [L]

Объяснение: Если вы используете браузер, который идентифицирует себя как мобильный браузер (обратите внимание, что пример неполный, так как существует много других мобильных платформ), отображается мобильная версия домашней страницы. В противном случае отображается стандартная страница.

Директива RewriteRule

RewriteRule Pattern Substitution [flags]

Директива RewriteRule является основным инструментом для переписывания. Директива может встречаться более одного раза, при этом каждый экземпляр определяет одно правило переписывания. Порядок определения этих правил важен — в этом порядке они будут применяться во время выполнения.

Шаблон — это совместимый с Perl регулярное выражение. То, с чем сравнивается этот шаблон, зависит от места определения директивы RewriteRule.

<If "true">
  # Without RewriteOptions Inherit, this rule is overridden by the next
  # section and no redirect will happen for URIs containing 'foo'
  RewriteRule foo http://example.com/foo [R]
</If>
<If "true">
  RewriteRule bar http://example.com/bar [R]
</If>

Дополнительную информацию о регулярных выражениях см. в введении к mod_rewrite.

В mod_rewrite, символ НЕ ('!') также доступен в качестве возможного префикса шаблона. Это позволяет вам инвертировать шаблон; например, сказать: «если текущий URL не соответствует этому шаблону». Это может использоваться для исключительных случаев, когда легче сопоставить обратный шаблон, или как последнее правило по умолчанию.

Подстановка правила переписывания — это строка, которая заменяет исходный путь URL, соответствующий Pattern. Подстановка может быть:

путь к файловой системе

Указывает расположение ресурса в файловой системе, которое будет передано клиенту. Подстановки рассматриваются как путь к файловой системе только в том случае, если правило настроено в контексте сервера (виртуального хоста), а первая часть пути в подстановке существует в файловой системе

путь URL

Относительный к DocumentRoot путь к ресурсу, который нужно предоставить. Обратите внимание, что mod_rewrite пытается угадать, указали ли вы путь к файловой системе или путь URL, проверяя, существует ли первый сегмент пути в корне файловой системы. Например, если вы указываете строку Substitution /www/file.html, то она будет рассматриваться как путь URL, за исключением случаев, когда каталог под названием www существует в корне файловой системы (или, в случае использования переписываний в файле .htaccess, относительно корня документа), в этом случае она будет рассматриваться как путь к файловой системе. Если вы хотите, чтобы другие директивы сопоставления URL (например, Alias) применялись к полученному пути URL, используйте флаг [PT] как описано ниже.

абсолютный URL

Если указан абсолютный URL, mod_rewrite проверяет, совпадает ли имя хоста с текущим хостом. Если совпадает, схема и имя хоста удаляются, и полученный путь рассматривается как путь URL. В противном случае выполняется внешний редирект на указанный URL. Чтобы принудительно выполнить внешний редирект на текущий хост, см. флаг [R] ниже.

- (тире)

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

В дополнение к простому тексту строка Substitution может включать

1. обратные ссылки ($N) на шаблон RewriteRule
2. обратные ссылки (%N) на последний сопоставленный шаблон RewriteCond
3. переменные сервера, как в строках условия проверки (%{VARNAME})
4. вызовы функций сопоставления (${mapname:key|default})

Обратные ссылки — это идентификаторы вида $N (N=0..9), которые будут заменены содержимым N-й группы сопоставленного шаблона Pattern. Переменные сервера такие же, как для строки TestString директивы RewriteCond. Функции сопоставления взяты из директивы RewriteMap и объяснены там. Эти три типа переменных расширяются в указанном порядке.

Правила переписывания применяются к результатам предыдущих правил переписывания в том порядке, в котором они определены в файле конфигурации. Путь URL или путь к файловой системе (см. "Что сопоставляется?", выше) полностью заменяется Substitution, и процесс переписывания продолжается до тех пор, пока не будут применены все правила, или он не будет явно завершён флагом L, или другим флагом, подразумевающим немедленное завершение, таким как END или F.

Кроме того, вы можете установить специальные действия, которые должны выполняться путём добавления [флагов] в качестве третьего аргумента директивы RewriteRule. Флаги — это список флагов, разделённых запятыми, в квадратных скобках, из любой таблицы ниже. Дополнительные сведения и примеры для каждого флага доступны в документе Флаги переписывания.

Ниже приведены все возможные комбинации подстановок и их значения:

Внутри конфигурации сервера (httpd.conf)
для запроса ``GET /somepath/pathinfo'':

Внутри конфигурации директории для /somepath
(/physical/path/to/somepath/.htaccess, с RewriteBase "/somepath")
для запроса ``GET /somepath/localpath/pathinfo'':