Кастомные ответы ошибок

Хотя Apache HTTP Server предоставляет общие ответы ошибок при возникновении кодов состояния HTTP 4xx или 5xx, эти ответы довольно скупы, неинформативны и могут быть пугающими для пользователей сайта. Возможно, вы захотите предоставить кастомные ответы на ошибки, которые будут более дружелюбными, или на другом языке, или, возможно, оформлены в соответствии с макетом вашего сайта.

Настраиваемые ответы ошибок могут быть определены для любого кода состояния HTTP, обозначенного как ошибка — то есть, любого кода состояния 4xx или 5xx.

Кроме того, предоставляется набор значений, чтобы документ об ошибке можно было дополнительно настроить на основе значений этих переменных, используя Вставки на стороне сервера. Или вы можете обрабатывать ситуации с ошибками с помощью программы cgi или другого динамического обработчика (PHP, mod_perl и т. д.), который использует эти переменные.

Настройка

Кастомные документы об ошибках настраиваются с помощью директивы ErrorDocument, которая может использоваться в глобальном, виртуальном или каталожном контексте. Она может быть использована в файлах .htaccess, если AllowOverride установлено в FileInfo.

ErrorDocument 500 "Sorry, our script crashed. Oh dear"
ErrorDocument 500 /cgi-bin/crash-recover
ErrorDocument 500 http://error.example.com/server_error.html
ErrorDocument 404 /errors/not_found.html
ErrorDocument 401 /subscription/how_to_subscribe.html

Синтаксис директивы ErrorDocument:

ErrorDocument <3-digit-code> <action>

где действие будет рассматриваться как:

1. Локальный URL для перенаправления (если действие начинается с "/").
2. Внешний URL для перенаправления (если действие является допустимым URL).
3. Текст для отображения (если ни один из вышеперечисленных вариантов не подходит). Текст должен быть заключен в кавычки (") если он состоит более чем из одного слова.

При перенаправлении на локальный URL дополнительные переменные среды устанавливаются таким образом, чтобы ответ можно было дополнительно настроить. Они не отправляются во внешние URL.

Доступные переменные

Перенаправление на другой URL может быть полезным, но только если можно передать некоторую информацию, которая может быть использована для более четкого объяснения или протоколирования ситуации с ошибкой.

Для достижения этого, когда отправляется перенаправление ошибки, будут установлены дополнительные переменные среды, которые будут сгенерированы из заголовков, предоставленных исходному запросу, путем добавления префикса «REDIRECT_» к исходному имени заголовка. Это предоставляет документу об ошибке контекст исходного запроса.

Например, вы можете получить, помимо более обычных переменных среды, следующие.

REDIRECT_HTTP_ACCEPT=*/*, image/gif, image/jpeg, image/png
REDIRECT_HTTP_USER_AGENT=Mozilla/5.0 Fedora/3.5.8-1.fc12 Firefox/3.5.8
REDIRECT_PATH=.:/bin:/usr/local/bin:/sbin
REDIRECT_QUERY_STRING=
REDIRECT_REMOTE_ADDR=121.345.78.123
REDIRECT_REMOTE_HOST=client.example.com
REDIRECT_SERVER_NAME=www.example.edu
REDIRECT_SERVER_PORT=80
REDIRECT_SERVER_SOFTWARE=Apache/2.2.15
REDIRECT_URL=/cgi-bin/buggy.pl

REDIRECT_ переменные среды создаются из переменных среды, существовавших до перенаправления. Они переименовываются с префиксом REDIRECT_, т. е., HTTP_USER_AGENT становится REDIRECT_HTTP_USER_AGENT.

REDIRECT_URL, REDIRECT_STATUS, и REDIRECT_QUERY_STRING гарантированно будут установлены, а остальные заголовки будут установлены только в том случае, если они существовали до возникновения ситуации с ошибкой.

Ни одна из этих переменных не будет установлена, если целевой ErrorDocument представляет собой внешнее перенаправление (любое, начинающееся с имени схемы, например http:, даже если оно относится к тому же хосту, что и сервер).

Настройка ответов ошибок

Если вы укажете вашу ErrorDocument на какой-либо вид динамического обработчика, такого как документ вставки на стороне сервера, сценарий CGI или какой-либо другой обработчик, вы можете использовать доступные пользовательские переменные среды для настройки этого ответа.

Если ErrorDocument указывает локальное перенаправление на скрипт CGI, скрипт должен включить поле заголовка «Status:» в свой вывод, чтобы обеспечить распространение всей информации об ошибке, которая вызвала его вызов, до клиента. Например, скрипт Perl ErrorDocument может включать следующее:

...
print  "Content-type: text/html\n";
printf "Status: %s Condition Intercepted\n", $ENV{"REDIRECT_STATUS"};
...

Если скрипт предназначен для обработки конкретной ситуации с ошибкой, такой как 404 Not Found, он может использовать конкретный код и текст ошибки вместо этого.

Обратите внимание, что если ответ содержит заголовок Location: (чтобы выполнить перенаправление на стороне клиента), скрипт обязательно должен вывести соответствующий заголовок Status: (такой как 302 Found). В противном случае заголовок Location: может не иметь эффекта.

Документы о многоязычных ошибках

Вместе с установкой Apache HTTP Server предоставляется каталог кастомных документов об ошибках, переведенных на 16 разных языков. Также есть конфигурационный файл в каталоге конфигурации conf/extra, который можно включить, чтобы активировать эту функцию.

В файле конфигурации сервера вы увидите строку, например:

# Multi-language error messages
#Include conf/extra/httpd-multilang-errordoc.conf

Откомментирование этой Include строки активирует эту функцию и предоставит сообщения об ошибках, настроенные на языке, выбранном в браузере клиента.

Кроме того, эти документы содержат различные REDIRECT_ переменные, чтобы предоставить пользователю дополнительную информацию о том, что случилось и что он может сделать теперь.

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

mod_include и mod_negotiation должны быть включены для использования этой функции.