Apache: Флаги правил перезаписи

RU EN

Пункт 43. Флаги правил перезаписи

В этом документе обсуждаются флаги, доступные для RewriteRule директивы, с подробными пояснениями и примерами.

Введение

RewriteRule Поведение A может быть изменено одним или несколькими флагами. Флаги заключаются в квадратные скобки в конце правила, а несколько флагов разделяются запятыми.

 Цель шаблона RewriteRule [Flag1,Flag2,Flag3]

Каждый флаг (за некоторыми исключениями) имеет короткую форму, например CO , а также более длинную форму, например cookie . Хотя чаще всего используется короткая форма, рекомендуется ознакомиться с длинной формой, чтобы помнить, что должен делать каждый флаг. Некоторые флаги принимают один или несколько аргументов. Флаги не чувствительны к регистру.

Флаги, которые изменяют метаданные, связанные с запросом (T=, H=, E=), не влияют на каталог и контекст htaccess, когда замена (отличная от '-') выполняется во время одного и того же раунда обработки перезаписи.

Здесь представлены все доступные флаги, а также примеры их использования.

B (экранировать обратные ссылки)

Флаг [B] предписывает RewriteRule экранировать не буквенно-цифровые символы перед применением преобразования.

В версии 2.4.26 и более поздних можно ограничить экранирование определенными символами в обратных ссылках, перечислив их: [B=#?;] . Примечание. В списке символов для перехода можно использовать пробел, но он не может быть последним символом в списке.

mod_rewrite должен отменить экранирование URL-адресов перед их сопоставлением, поэтому обратные ссылки не экранируются во время их применения. При использовании флага B небуквенно-цифровые символы в обратных ссылках будут экранированы. Например, рассмотрим правило:

 RewriteRule "^search/(.*)$" "/search.php?term=$1"

При поиске «x & y/z» браузер закодирует его как «x%20%26%20y%2Fz», сделав запрос «search/x%20%26%20y%2Fz». Без флага B это правило перезаписи будет отображаться на «search.php?term=x & y/z», что не является допустимым URL-адресом, и поэтому будет закодировано как , что не предназначено search.php?term=x%20&y%2Fz= .

Если в этом же правиле установлен флаг B, параметры перекодируются перед передачей в выходной URL-адрес, что приводит к правильному сопоставлению с /search.php?term=x%20%26%20y%2Fz .

 RewriteRule "^search/(.*)$" "/search.php?term=$1" [B,PT]

Обратите внимание, что вам также может понадобиться установить, AllowEncodedSlashes чтобы On этот конкретный пример работал, поскольку httpd не разрешает закодированные косые черты в URL-адресах и возвращает 404, если он их видит.

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

Альтернативой этому флагу является использование RewriteCond для захвата %{THE_REQUEST}, который будет захватывать строки в закодированной форме.

BNP|backrefnoplus (не используйте пробел для +)

Флаг [BNP] предписывает RewriteRule экранировать символ пробела в обратной ссылке до %20, а не «+». Полезно, когда обратная ссылка будет использоваться в компоненте пути, а не в строке запроса.

Этот флаг доступен в версии 2.4.26 и выше.

С|цепь

Флаг [C] или [цепочка] указывает, что правило RewriteRule связано со следующим правилом. То есть, если правило совпадает, то оно обрабатывается как обычно и управление переходит к следующему правилу. Однако, если оно не совпадает, то следующее правило и любые другие правила, связанные вместе, пропускаются.

CO|куки

Флаг [CO] или [cookie] позволяет вам установить файл cookie при определенном RewriteRule совпадении. Аргумент состоит из трех обязательных полей и четырех необязательных полей.

Полный синтаксис флага, включая все атрибуты, выглядит следующим образом:

[CO=NAME:VALUE:DOMAIN:lifetime:path:secure:httponly]

Если в любом из полей cookie требуется буквальный символ ':', доступен альтернативный синтаксис. Чтобы согласиться на альтернативный синтаксис, перед «Именем» файла cookie должен стоять «;». символ, а разделители полей должны быть указаны как ';'.

[CO=;NAME;VALUE:MOREVALUE;DOMAIN;lifetime;path;secure;httponly]

Вы должны объявить имя, значение и домен для установки файла cookie.

Домен: Домен, для которого вы хотите, чтобы файл cookie был действительным. Это может быть имя хоста, например www.example.com , или домен, например .example.com . Он должен состоять как минимум из двух частей, разделенных точкой. То есть это может быть не просто .com или .net . Файлы cookie такого типа запрещены моделью безопасности файлов cookie.

При желании вы также можете установить следующие значения:

Продолжительность жизни: Время, в течение которого файл cookie будет сохраняться, в минутах.; Значение 0 указывает, что файл cookie будет сохраняться только в течение текущего сеанса браузера. Это значение по умолчанию, если оно не указано.
Путь: Путь на текущем веб-сайте, для которого действителен файл cookie, например, /customers/ или /files/download/ .; По умолчанию установлено значение / — то есть весь веб-сайт.
Безопасный: Если установлено значение secure , true , или 1 , куки будет разрешено переводить только через безопасные (https) соединения.
только http: Если установлено значение HttpOnly , true , или 1 , файл cookie будет иметь HttpOnly установленный флаг, что означает, что файл cookie недоступен для кода JavaScript в браузерах, поддерживающих эту функцию.

Рассмотрим этот пример:

 RewriteEngine включен
RewriteRule "^/index\.html" "-" [CO=frontdoor:yes:.example.com:1440:/]

В приведенном примере правило не перезаписывает запрос. Цель перезаписи "-" указывает mod_rewrite передать запрос без изменений. Вместо этого он устанавливает для файла cookie с именем «frontdoor» значение «да». Файл cookie действителен для любого хоста в .example.com домене. Срок действия истекает через 1440 минут (24 часа) и возвращается для всех URI.

DPI|путь сброса

Флаг DPI вызывает отбрасывание части PATH_INFO переписанного URI.

Этот флаг доступен в версии 2.2.12 и выше.

В контексте каждого каталога URI, RewriteRule с которым сравнивается каждый, представляет собой конкатенацию текущих значений URI и PATH_INFO.

Текущий URI может быть начальным URI, запрошенным клиентом, результатом предыдущего раунда обработки mod_rewrite или результатом предшествующего правила в текущем раунде обработки mod_rewrite.

Напротив, PATH_INFO, который добавляется к URI перед каждым правилом, отражает только значение PATH_INFO до этого раунда обработки mod_rewrite. Как следствие, если большие части URI сопоставляются и копируются в замену в нескольких RewriteRule директивах, независимо от того, какие части URI получены из текущего PATH_INFO, к конечному URI может быть добавлено несколько копий PATH_INFO.

Используйте этот флаг при любой подстановке, где PATH_INFO, полученная в результате предыдущего сопоставления этого запроса с файловой системой, не представляет интереса. Этот флаг навсегда забывает PATH_INFO, установленный до начала этого раунда обработки mod_rewrite. PATH_INFO не будет пересчитываться, пока не завершится текущий раунд обработки mod_rewrite. Последующие правила во время этого раунда обработки будут видеть только непосредственный результат подстановки без добавления PATH_INFO.

E|окружение

С помощью флага [E] или [env] вы можете установить значение переменной среды. Обратите внимание, что некоторые переменные среды могут быть установлены после запуска правила, что приведет к удалению того, что вы установили. Дополнительные сведения о том, как работают переменные среды, см. в документе «Переменные среды».

Полный синтаксис этого флага:

 [Э=ПЕР.:ВАЛ]
[Э=!ВАР]

VAL может содержать обратные ссылки ( $N или %N ), которые раскрываются.

Использование краткой формы

[E=VAR]

вы можете установить переменную среды с именем VAR на пустое значение.

Форма

[E=!VAR]

позволяет сбросить ранее установленную переменную среды с именем VAR .

Затем переменные среды можно использовать в различных контекстах, включая программы CGI, другие директивы RewriteRule или директивы CustomLog.

В следующем примере переменной среды с именем «image» присваивается значение «1», если запрошенный URI является файлом изображения. Затем эта переменная среды используется для исключения этих запросов из журнала доступа.

 RewriteRule "\.(png|gif|jpg)$" "-" [E=image:1]
CustomLog "logs/access_log" в сочетании env=!image

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

КОНЕЦ

Использование флага [END] не только завершает текущий раунд обработки перезаписи (например, [L]), но также предотвращает любую последующую обработку перезаписи в контексте для каждого каталога (htaccess).

Это не относится к новым запросам, полученным в результате внешних перенаправлений.

F|запрещено

Использование флага [F] заставляет сервер возвращать клиенту код состояния 403 Forbidden. Хотя то же самое поведение может быть выполнено с помощью Deny директивы, это обеспечивает большую гибкость при назначении статуса «Запрещено».

Следующее правило запрещает .exe загрузку файлов с вашего сервера.

 RewriteRule "\.exe" "-" [F]

В этом примере используется синтаксис "-" для цели перезаписи, что означает, что запрошенный URI не изменяется. Нет причин переписывать на другой URI, если вы собираетесь запретить запрос.

При использовании [F] подразумевается [L], то есть ответ возвращается немедленно, и дальнейшие правила не оцениваются.

G|ушел

Флаг [G] заставляет сервер возвращать статус 410 Gone вместе с ответом. Это указывает на то, что ресурс раньше был доступен, но больше недоступен.

Как и в случае с флагом [F], вы обычно будете использовать синтаксис "-" для цели перезаписи при использовании флага [G]:

 RewriteRule "oldproduct" "-" [G,NC]

При использовании [G] подразумевается [L], то есть ответ возвращается немедленно, и дальнейшие правила не оцениваются.

H|обработчик

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

 Правило перезаписи "!\." "-" [H=приложение/x-httpd-php]

Приведенное выше регулярное выражение - !\. - будет соответствовать любому запросу, не содержащему буквенный . символ.

Это также можно использовать для форсирования обработчика на основе некоторых условий. Например, следующий фрагмент, используемый в контексте для каждого сервера, позволяет отображать .php файлы , если они запрашиваются с расширением: mod_php .phps

 RewriteRule "^(/source/.+\.php)s$" "$1" [H=application/x-httpd-php-source]

Приведенное выше регулярное выражение -- ^(/source/.+\.php)s$ будет соответствовать любому запросу, который начинается с, /source/ за которым следует 1 или n символов, за которыми следует .phps буквально. Обратная ссылка $1 ссылается на захваченное совпадение в скобках регулярного выражения.

L|последний

Флаг [L] приводит mod_rewrite к остановке обработки набора правил. В большинстве случаев это означает, что если правило совпадает, дальнейшие правила обрабатываться не будут. Это соответствует команде last в Perl или break команде в C. Используйте этот флаг, чтобы указать, что текущее правило должно быть применено немедленно, без учета дополнительных правил.

Если вы используете RewriteRule в .htaccess файлах или в <Directory> разделах, важно иметь некоторое представление о том, как обрабатываются правила. Упрощенная форма этого заключается в том, что после обработки правил переписанный запрос возвращается механизму анализа URL-адресов, чтобы сделать с ним то, что он может. Возможно, что при обработке переписанного запроса .htaccess файл или <Directory> раздел могут быть обнаружены снова, и, таким образом, набор правил может быть запущен снова с самого начала. Чаще всего это происходит, если одно из правил вызывает перенаправление (внутреннее или внешнее), в результате чего процесс запроса начинается заново.

Поэтому важно, если вы используете RewriteRule директивы в одном из этих контекстов, чтобы вы предприняли явные шаги, чтобы избежать зацикливания правил, и не рассчитывали исключительно на флаг [L] для прекращения выполнения ряда правил, как показано ниже.

Альтернативный флаг [END] может использоваться не только для завершения текущего раунда обработки перезаписи, но и для предотвращения любой последующей обработки перезаписи в контексте для каждого каталога (htaccess). Это не относится к новым запросам, полученным в результате внешних перенаправлений.

Приведенный здесь пример переписывает любой запрос на index.php , передавая исходный запрос в качестве аргумента строки запроса на index.php , однако RewriteCond гарантирует, что, если запрос уже для index.php , он RewriteRule будет пропущен.

 Переписать базу "/"
RewriteCond "%{REQUEST_URI}" "!=/index.php"
RewriteRule "^(.*)" "/index.php?req=$1" [L,PT]

N|следующий

Флаг [N] заставляет набор правил начинать заново с самого начала, используя результат набора правил до сих пор в качестве отправной точки. Используйте с особой осторожностью, так как это может привести к зацикливанию.

Флаг [Next] можно использовать, например, если вы хотите повторно заменить определенную строку или букву в запросе. Показанный здесь пример заменяет A на B везде в запросе и будет продолжать делать это до тех пор, пока не останется A, подлежащих замене.

 Правило перезаписи "(.*)A(.*)" "$1B$2" [N]

Вы можете думать об этом как о while цикле: пока этот шаблон все еще соответствует (т. е. пока URI все еще содержит A ), выполните эту замену (т. е. замените A на B ).

В версии 2.4.8 и более поздних версиях этот модуль возвращает ошибку после 32 000 итераций для защиты от непреднамеренного зацикливания. Альтернативное максимальное количество итераций можно указать, добавив к флагу N.

 # Будьте готовы заменить 1 символ в каждом проходе цикла
RewriteRule "(.+)[><;]$" "$1" [N=64000]
# ... или отказаться, если после 10 циклов
RewriteRule "(.+)[><;]$" "$1" [N=10]

NC|без дела

Использование флага [NC] приводит к RewriteRule совпадению без учета регистра. То есть ему все равно, отображаются ли буквы в совпадающем URI в верхнем или нижнем регистре.

В приведенном ниже примере любой запрос файла изображения будет проксироваться на ваш выделенный сервер изображений. Совпадение не чувствительно к регистру, поэтому допустимы, например, .jpg и файлы . .JPG

 RewriteRule "(.*\.(jpg|gif|png))$" "http://images.example.com$1" [P,NC]

NE|без побега

По умолчанию специальные символы, такие как & и ? , например, будут преобразованы в их шестнадцатеричный эквивалент. Использование флага [NE] предотвращает это.

 RewriteRule "^/anchor/(.+)" "/bigpage.html#$1" [NE,R]

Приведенный выше пример будет перенаправлен /anchor/xyz на /bigpage.html#xyz . Отсутствие [NE] приведет к преобразованию # в его эквивалент в шестнадцатеричном коде, %23 что приведет к ошибке 404 Not Found.

NS|nosubreq

Использование флага [NS] запрещает использование правила в подзапросах. Например, страница, включенная с помощью SSI (включение на стороне сервера), является подзапросом, и вы можете избежать перезаписи этих подзапросов. Кроме того, когда mod_dir вы пытаетесь получить информацию о возможных файлах каталога по умолчанию (например, index.html файлах), это внутренний подзапрос, и вы часто хотите избежать перезаписи таких подзапросов. На подзапросах это не всегда полезно и даже может привести к ошибкам, если применяется полный набор правил. Используйте этот флаг, чтобы исключить проблемные правила.

Чтобы решить, использовать это правило или нет: если вы добавляете к URL-адресам префикс CGI-скриптов, чтобы заставить их обрабатываться CGI-скриптом, вполне вероятно, что вы столкнетесь с проблемами (или значительными накладными расходами) при подзапросах. В этих случаях используйте этот флаг.

Изображения, файлы javascript или файлы css, загружаемые как часть HTML-страницы, не являются подзапросами — браузер запрашивает их как отдельные HTTP-запросы.

P|прокси

Использование флага [P] приводит к тому, что запрос обрабатывается mod_proxy через прокси-запрос. Например, если вы хотите, чтобы все запросы изображений обрабатывались внутренним сервером изображений, вы можете сделать что-то вроде следующего:

 RewriteRule "/(.*)\.(jpg|gif|png)$" "http://images.example.com/$1.$2" [P]

Использование флага [P] подразумевает [L] — то есть запрос немедленно проталкивается через прокси, и любые последующие правила не будут учитываться.

Вы должны убедиться, что строка подстановки является допустимым URI (обычно начинающимся с http:// имени хоста ), который может быть обработан mod_proxy . Если нет, вы получите сообщение об ошибке от прокси-модуля. Используйте этот флаг, чтобы добиться более мощной реализации директивы ProxyPass , чтобы сопоставить удаленный контент с пространством имен локального сервера.

Предупреждение безопасности

Будьте осторожны при создании целевого URL-адреса правила, учитывая влияние на безопасность, если разрешить клиенту влиять на набор URL-адресов, для которых ваш сервер будет выступать в качестве прокси. Убедитесь, что часть схемы и имени хоста в URL-адресе фиксирована или не допускает чрезмерного влияния клиента.

Предупреждение о производительности

Использование этого флага запускает использование mod_proxy без обработки постоянных соединений. Это означает, что производительность вашего прокси будет лучше, если вы настроите его с помощью ProxyPass или ProxyPassMatch

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

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

Примечание: mod_proxy должен быть включен, чтобы использовать этот флаг.

PT|проходной

Целью (или строкой подстановки) в RewriteRule по умолчанию считается путь к файлу. Использование флага [PT] приводит к тому, что он рассматривается как URI. Другими словами, использование флага [PT] вызывает передачу результата RewriteRule обратно через сопоставление URL-адресов, так что сопоставления на основе местоположения, такие как Alias , Redirect или ScriptAlias , например, могут иметь шанс вступить в силу.

Если, например, у вас есть Alias for /icons и есть RewriteRule указатель туда, вы должны использовать флаг [PT], чтобы убедиться, что он Alias оценивается.

 Псевдоним "/icons" "/usr/local/apache/icons"
RewriteRule "/pics/(.+)\.jpg$" "/icons/$1.gif" [PT]

Отсутствие флага [PT] в этом случае приведет к игнорированию псевдонима, что приведет к возврату ошибки «Файл не найден».

Флаг PT подразумевает L флаг: перезапись будет остановлена, чтобы передать запрос на следующую фазу обработки.

Обратите внимание, что PT флаг подразумевается в контекстах каталогов, таких как <Directory> разделы или .htaccess файлы. Единственный способ обойти это — переписать в - .

QSA|qsдобавлять

Когда замещающий URI содержит строку запроса, по умолчанию RewriteRule существующая строка запроса отбрасывается и заменяется вновь созданной. Использование флага [QSA] приводит к объединению строк запроса.

Рассмотрим следующее правило:

 RewriteRule "/pages/(.+)" "/page.php?page=$1" [QSA]

С флагом [QSA] запрос /pages/123?one=two будет сопоставлен с /page.php?page=123&one=two . Без флага [QSA] тот же запрос будет сопоставлен /page.php?page=123 , то есть существующая строка запроса будет отброшена.

QSD|qsотменить

Если запрошенный URI содержит строку запроса, а целевой URI — нет, по умолчанию RewriteRule эта строка запроса копируется в целевой URI. Использование флага [QSD] приводит к отбрасыванию строки запроса.

Этот флаг доступен в версии 2.4.0 и выше.

Совместное использование [QSD] и [QSA] приведет к тому, что [QSD] будет иметь приоритет.

Если у целевого URI есть строка запроса, будет наблюдаться поведение по умолчанию, то есть исходная строка запроса будет отброшена и заменена строкой запроса в целевом RewriteRule URI.

QSL|qsпоследняя

По умолчанию первый (самый левый) вопросительный знак в подстановке отделяет путь от строки запроса. Использование флага [QSL] указывает RewriteRule вместо этого разделить два компонента, используя последний (самый правый) вопросительный знак.

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

Этот флаг доступен в версии 2.4.19 и выше.

R|перенаправить

Использование флага [R] вызывает перенаправление HTTP в браузер. Если указан полный URL-адрес (то есть включая http://servername/ ), то будет выполнено перенаправление на это место. В противном случае текущий протокол, имя сервера и номер порта будут использоваться для создания URL-адреса, отправляемого с перенаправлением.

Любой действительный код состояния ответа HTTP может быть указан с использованием синтаксиса [R=305], при этом по умолчанию используется код состояния 302, если он не указан. Указанный код состояния не обязательно должен быть кодом состояния перенаправления (3xx). Однако если код состояния выходит за пределы диапазона перенаправления (300-399), то строка замены полностью отбрасывается, а перезапись останавливается, как если бы они L использовались.

В дополнение к кодам состояния ответа вы также можете указать статус перенаправления, используя их символические имена: temp (по умолчанию), permanent , или seeother .

Вы почти всегда будете использовать [R] в сочетании с [L] (то есть использовать [R,L]), потому что сам по себе флаг [R] предшествует URI, но затем передает его http://thishost[:thisport] следующему правило в наборе правил, что часто может приводить к появлению предупреждений «Недопустимый URI в запросе».

S|пропустить

Флаг [S] используется для пропуска правил, которые вы не хотите запускать. Синтаксис флага пропуска следующий: [S= N ], где N означает количество пропускаемых правил (при наличии RewriteRule совпадений). Это можно рассматривать как goto утверждение в вашем наборе правил перезаписи. В следующем примере мы хотим запускать только в том RewriteRule случае, если запрошенный URI не соответствует фактическому файлу.

 # Является ли запрос несуществующим файлом?
RewriteCond "%{REQUEST_FILENAME}" "!-f"
RewriteCond "%{REQUEST_FILENAME}" "!-d"
# Если это так, пропустите эти два RewriteRules
Правило перезаписи ".?" "-" [С=2]
RewriteRule "(.*\.gif)" "images.php?$1"
RewriteRule "(.*\.html)" "docs.php?$1"

Этот метод полезен, потому что a RewriteCond применяется только к тому, что RewriteRule непосредственно следует за ним. Таким образом, если вы хотите применить RewriteCond apply к нескольким RewriteRule s, одним из возможных способов является отрицание этих условий и добавление a RewriteRule с флагом [Skip]. Вы можете использовать это для создания псевдоконструкций if-then-else: последнее правило предложения then становится skip=N , где N — количество правил в предложении else:

 # Существует ли файл?
RewriteCond "%{REQUEST_FILENAME}" "!-f"
RewriteCond "%{REQUEST_FILENAME}" "!-d"
# Создайте конструкцию if-then-else, пропустив 3 строки, если мы хотели перейти к строфе else.
Правило перезаписи ".?" "-" [С=3]
# ЕСЛИ файл существует, то:
 RewriteRule "(.*\.gif)" "images.php?$1"
 RewriteRule "(.*\.html)" "docs.php?$1"
 # Пропустить строфу else.
 Правило перезаписи ".?" "-" [С=1]
# ЕЩЕ...
 RewriteRule "(.*)" "404.php?file=$1"
# КОНЕЦ

Вероятно, проще выполнить такую настройку, используя вместо этого директивы <If> , <ElseIf> , и <Else> .

Т|тип

Устанавливает тип MIME, с которым будет отправлен результирующий ответ. Это имеет тот же эффект, что и AddType директива.

Например, вы можете использовать следующую технику для предоставления исходного кода Perl в виде обычного текста, если он запрошен определенным образом:

 # Подавать файлы .pl как обычный текст
Правило перезаписи "\.pl$" "-" [T=текст/обычный]

Или, возможно, если у вас есть камера, которая создает изображения в формате jpeg без расширений файлов, вы можете заставить эти изображения обслуживаться с правильным типом MIME на основании их имен файлов:

 # Файлы с 'IMG' в названии являются изображениями в формате jpg.
RewriteRule "IMG" "-" [T=image/jpg]

Обратите внимание, что это тривиальный пример, и его лучше использовать <FilesMatch> вместо этого. Всегда рассматривайте альтернативные решения проблемы, прежде чем прибегать к переписыванию, которое неизменно будет менее эффективным решением, чем альтернативы.

Если используется в контексте каталога, используйте только - (тире) в качестве замены для всего цикла обработки mod_rewrite , в противном случае набор MIME-типа с этим флагом будет потерян из-за внутренней повторной обработки (включая последующие раунды обработки mod_rewrite) . В этом контексте флаг L может быть полезен для завершения текущего раунда обработки mod_rewrite.