Apache: Обновления API в Apache HTTPD 2.4

RU EN

Пункт 215. Обновления API в Apache HTTPD 2.4

В этом документе описываются изменения в Apache HTTPD API с версии 2.2 до 2.4, которые могут быть интересны разработчикам модулей/приложений и основным специалистам. Начиная с первого общедоступного выпуска API-интерфейса ветки 2.4, совместимость с API ветки 2.4 сохраняется на протяжении всей жизни ветки 2.4. (Описание VERSIONING для версии 2.4 содержит дополнительную информацию о совместимости API.)

Изменения API делятся на две категории: совершенно новые API и существующие API, которые расширяются или изменяются. Последние далее делятся на те, в которых все изменения обратно совместимы (поэтому существующие модули могут их игнорировать), и те, которые могут потребовать внимания со стороны сопровождающих. Как и при переходе с HTTPD 2.0 на 2.2, существующие модули и приложения потребуют перекомпиляции и могут потребовать некоторого внимания, но большинство из них не требуют существенного обновления (хотя некоторые могут воспользоваться преимуществами изменений API, чтобы предложить значительные улучшения).

Для целей этого документа API разделен в соответствии с файлами общедоступных заголовков. Эти заголовки сами по себе являются справочной документацией и могут использоваться для создания доступного для просмотра HTML-справочника с расширением make docs .

Измененные API

ap_expr (НОВИНКА!)

Представляет новый API для анализа и оценки логических и алгебраических выражений, включая предоставление стандартного синтаксиса и настраиваемых вариантов.

ap_listen (изменено; обратно совместимо)

Представляет новый API, позволяющий дочерним процессам httpd служить различным целям.

ap_mpm (изменено)

ap_mpm_run заменяется новым mpm крючком. И ap_graceful_stop_signalled утерян, и ap_mpm_register_timed_callback есть новый.

ap_regex (изменено)

ap_rxplus В дополнение к существующей оболочке регулярных выражений теперь предоставляется новый API более высокого уровня . Это дает возможность компилировать выражения в стиле Perl s/regexp/replacement/flags и выполнять их для произвольных строк. Также добавлена поддержка обратных ссылок регулярных выражений.

ap_slotmem (НОВИНКА!)

Представляет API для модулей для выделения слотов памяти и управления ими, чаще всего для разделяемой памяти.

ap_socache (НОВИНКА!)

API для управления общим кешем объектов.

сердцебиение (НОВИНКА!)

общие структуры для модулей сердцебиения

ap_parse_htaccess (изменено)

Сигнатура функции для ap_parse_htaccess была изменена. A apr_table_t из отдельных директив, разрешенных для переопределения, теперь должны быть переданы (переопределение остается).

http_config (изменено)

Вводит уровни ведения журналов для каждого модуля и каталога, включая оболочки макросов.
Новый AP_DECLARE_MODULE макрос для объявления всех модулей.
Новый APLOG_USE_MODULE макрос необходим для помодульных уровней ведения журнала в многофайловых модулях.
Новый API для сохранения данных при выгрузке/загрузке модуля
Новый check_config крючок
Новая ap_process_fnmatch_configs() функция для обработки подстановочных знаков
Измените ap_configfile_t , ap_cfg_getline() , ap_cfg_getc() чтобы возвращать коды ошибок, и добавьте ap_pcfg_strerror() для получения описания ошибки.
Любая директива конфигурации, разрешенная в контексте ACCESS_CONF, теперь должна правильно обрабатывать вызовы из файла .htaccess через новую AllowOverrideList директиву. ap_check_cmd_context() принимает новый флаг NOT_IN_HTACCESS для обнаружения этого случая.

http_core (изменено)

УДАЛЕНО ap_default_type , ap_requires все API аутентификации 2.2
Вводит дополнительные функции для logio и authnz
Новая функция ap_get_server_name_for_url для поддержки литералов IPv6.
Новая функция ap_register_errorlog_handler для регистрации обработчиков строк формата журнала ошибок.
Аргументы error_log хука изменились. Декларация перемещена в http_core.h .
Новая функция ap_state_query для определения того, находится ли сервер на этапе предварительной проверки начальной конфигурации или нет. Это проще в использовании и более правильно, чем старый метод создания записи пользовательских данных пула в пуле процессов.
Новая функция ap_get_conn_socket для получения дескриптора сокета для соединения. Это следует использовать вместо прямого доступа к конфигурации основного соединения.

httpd (изменено)

Ввести уровень журнала для каждого каталога и модуля
Новые уровни логов APLOG_TRACEn
Введите идентификаторы журнала ошибок для запросов и подключений.
Поддержка mod_request keep_body
Поддержка буферизации данных фильтра для асинхронных запросов.
Новые CONN_STATE значения
Изменения функций: ap_escape_html обновлено; ap_unescape_all , ap_escape_path_segment_buffer
Модули, которые загружают другие модули позже EXEC_ON_READ этапа чтения конфигурации, должны вызывать ap_reserve_module_slots() или ap_reserve_module_slots_directive() в своих файлах pre_config hook .
IP-адрес агента пользователя для каждого запроса теперь можно отслеживать независимо от IP-адреса клиента соединения для поддержки развертываний с балансировщиками нагрузки.

http_log (изменено)

Ввести уровень журнала для каждого каталога и модуля
Новые уровни логов APLOG_TRACEn
ap_log_*error стать обертками макросов (обратно совместимы, если APLOG_MARK используется макрос, за исключением того, что его больше нельзя использовать #ifdef внутри списка аргументов)
ведение журнала по каналам переработано
module_index добавлено в хук error_log
новая функция: ap_log_command_line

http_request (изменено)

Новый API auth_internal и API auth_provider
Новый EOR тип ковша
Новая функция ap_process_async_request
Новые флаги AP_AUTH_INTERNAL_PER_CONF и AP_AUTH_INTERNAL_PER_URI
Новый access_checker_ex хук для применения дополнительного контроля доступа и/или обхода аутентификации.
Новые функции ap_hook_check_access_ex , ap_hook_check_access , ap_hook_check_authn , ap_hook_check_authz которые принимают AP_AUTH_INTERNAL_PER_* флаги
УСТАРЕЛО прямое использование ap_hook_access_checker , access_checker_ex , ap_hook_check_user_id , ap_hook_auth_checker

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

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

mod_auth (НОВИНКА!)

Представляет новую структуру провайдера для authn и authz.

mod_cache (изменено)

Вводит commit_entity() функцию в интерфейс поставщика кеша, разрешающую атомарную запись в кеш. Добавьте cache_status() хук, чтобы сообщить о решении кеша. Все частные структуры и функции были удалены.

mod_core (НОВИНКА!)

Это вводит низкоуровневые API для отправки произвольных заголовков и предоставляет функции для обработки HTTP OPTIONS и TRACE.

mod_cache_disk (изменено)

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

mod_disk_cache (переименован)

Модуль mod_disk_cache был переименован в mod_cache_disk, чтобы соответствовать именам других модулей на сервере.

mod_request (НОВИНКА!)

API для mod_request , чтобы при необходимости сделать входные данные доступными для нескольких модулей приложения/обработчика, а также для анализа данных формы HTML.

mpm_common (изменено)

УДАЛЕНИЕ: accept , lockfile , lock_mech , set_scoreboard (блокировка использует новый API ap_mutex)
НОВЫЙ API для отказа от привилегий (делегирует эту зависящую от платформы функцию модулям)
НОВЫЕ крючки: mpm_query , timed_callback , и get_name
ИЗМЕНЕНЫ интерфейсы: monitor хук, ap_reclaim_child_processes , ap_relieve_child_processes

табло (изменено)

ap_get_scoreboard_worker становится несовместимым с предыдущими версиями, поскольку представлена альтернативная версия. Дополнительная поддержка proxy_balancer. Детский статус переработан.

util_cookies (НОВИНКА!)

Представляет новый API для управления файлами cookie HTTP.

util_ldap (изменено)

нет описания

util_mutex (НОВИНКА!)

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

util_script (изменено)

НОВЫЙ: ap_args_to_table

util_time (изменено)

НОВЫЙ: ap_recent_ctime_ex

Конкретная информация по обновлению модулей с версии 2.2

Ведение журнала

Чтобы воспользоваться конфигурацией уровня журнала для каждого модуля, любой исходный файл, вызывающий функции, ap_log_* должен объявлять, к какому модулю он принадлежит. Если вызывается module_struct модуля foo_module , можно использовать следующий код, чтобы сохранить обратную совместимость с HTTPD 2.0 и 2.2:

#include <http_log.h> #ifdef APLOG_USE_MODULE APLOG_USE_MODULE(foo); #endif

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

Изменилось количество параметров функций ap_log_* и определение . APLOG_MARK Обычно изменение полностью прозрачно. Однако изменения требуются, если модуль использует APLOG_MARK в качестве параметра свои собственные функции или если модуль вызывает ap_log_* без передачи APLOG_MARK . Модуль, использующий обертки, ap_log_* обычно использует обе эти конструкции.

Самый простой способ изменить код, который передается APLOG_MARK своим собственным функциям, — это определить и использовать другой макрос, который расширяется до параметров, требуемых этими функциями, которые APLOG_MARK следует использовать только при ap_log_* прямом вызове. Таким образом, код останется совместимым с HTTPD 2.0 и 2.2.

Код, который вызывается ap_log_* без передачи, APLOG_MARK обязательно будет отличаться между версиями 2.4 и более ранними, поскольку версия 2.4 требует нового третьего аргумента, APLOG_MODULE_INDEX .

/* code for httpd 2.0/2.2 */ ap_log_perror(file, line, APLOG_ERR, 0, p, "Failed to allocate dynamic lock structure"); /* code for httpd 2.4 */ ap_log_perror(file, line, APLOG_MODULE_INDEX, APLOG_ERR, 0, p, "Failed to allocate dynamic lock structure");

ap_log_*error теперь реализованы как макросы. Это означает, что больше нельзя использовать #ifdef внутри списка аргументов ap_log_*error , так как это приведет к неопределенному поведению в соответствии с C99.

Указатель server_rec должен быть передан ap_log_error() при вызове после запуска. Это всегда было уместно, но ограничений в версии 2.4 еще больше, NULL server_rec чем в предыдущих версиях. Начиная с версии 2.3.12 глобальную переменную ap_server_conf всегда можно использовать в качестве server_rec параметра, так как это будет NULL только тогда, когда допустимо перейти NULL к ap_log_error() . следует использовать только тогда, когда нет ap_server_conf более подходящего . server_rec

Рассмотрите следующие изменения, чтобы воспользоваться преимуществами новых APLOG_TRACE1..8 уровней журнала:

Проверьте текущее использование APLOG_DEBUG и подумайте, APLOG_TRACEn является ли один из уровней более подходящим.
Если ваш модуль в настоящее время имеет механизм для настройки количества выполняемых журналов отладки, рассмотрите возможность исключения этого механизма и использования различных APLOG_TRACEn уровней. Если требуется обойти дорогостоящую обработку трассировки в зависимости от настроенного уровня журнала, используйте макросы и, чтобы сначала проверить, включена ли трассировка. APLOGtracen APLOGrtracen

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

Если ваш модуль использует эти существующие API...

ap_default_type()

Это больше не доступно; Content-Type должен быть настроен явно или добавлен приложением.

ap_get_server_name()

Если возвращенное имя сервера используется в URL-адресе, используйте ap_get_server_name_for_url() вместо него. Эта новая функция обрабатывает странный случай, когда имя сервера является литеральным адресом IPv6.

ap_get_server_version()

В целях ведения журнала, если необходима подробная информация, используйте ap_get_server_description() . При создании выходных данных, где объем информации должен настраиваться с помощью ServerTokens, используйте ap_get_server_banner() .

ap_graceful_stop_signalled()

Замените вызовом ap_mpm_query(AP_MPMQ_MPM_STATE) и проверкой состояния AP_MPMQ_STOPPING .

ap_max_daemons_limit , ap_my_generation , и ap_threads_per_child

Используйте ap_mpm_query() коды запросов AP_MPMQ_MAX_DAEMON_USED , AP_MPMQ_GENERATION и AP_MPMQ_MAX_THREADS соответственно.

ap_mpm_query()

Убедитесь, что он не используется до тех пор, пока хук register-hooks не завершится. В противном случае MPM, построенный как DSO, не имел бы возможности включить поддержку этой функции.

ap_requires()

Главный сервер теперь предоставляет улучшенную инфраструктуру для управления Require конфигурацией. Зарегистрируйте функцию поставщика аутентификации для каждого поддерживаемого объекта, используя ap_register_auth_provider() . Функция будет вызываться по мере необходимости во время Require обработки. (Подробные примеры см. в комплектных модулях.)

ap_server_conf->process->pool данные пользователя

Необязательный:

Если ваш модуль использует это, чтобы определить, какой этап хуков запуска выполняется, используйте ap_state_query(AP_SQ_MAIN_STATE) .
Если ваш модуль использует это для хранения данных при выгрузке и перезагрузке вашего модуля, используйте ap_retained_data_create() и ap_retained_data_get() .

apr_global_mutex_create() , apr_proc_mutex_create()

Необязательно: см. ap_mutex_register() , ap_global_mutex_create() , и ap_proc_mutex_create() ; они позволяют настраивать ваши мьютексы с помощью Mutex директивы; вы также можете удалить любые механизмы конфигурации в вашем модуле для таких мьютексов.

CORE_PRIVATE

Теперь это не нужно и игнорируется.

dav_new_error() и dav_new_error_tag()

Ранее предполагалось, что они errno содержат информацию, описывающую сбой. Теперь apr_status_t необходимо указать параметр. Передайте 0/APR_SUCCESS, если такой информации об ошибке нет, или допустимое apr_status_t значение в противном случае.

mpm_default.h , DEFAULT_LOCKFILE , DEFAULT_THREAD_LIMIT , DEFAULT_PIDLOG , и т.д.

Заголовочный файл и большинство установленных в нем значений конфигурации по умолчанию больше не видны модулям. (Большинство из них все еще можно переопределить во время сборки.) DEFAULT_PIDLOG и DEFAULT_REL_RUNTIMEDIR теперь они повсеместно доступны через файлы ap_config.h .

unixd_config

Он был переименован в ap_unixd_config.

unixd_setup_child()

Он был переименован в ap_unixd_setup_child(), но большинству вызывающих пользователей следует вызывать добавленный хук ap_run_drop_privives().

conn_rec->remote_ip и conn_rec->remote_addr

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

Если вам требуется IP-адрес пользовательского агента, который может быть подключен непосредственно к серверу или может быть дополнительно отделен от сервера прозрачным балансировщиком нагрузки или прокси-сервером, используйте request_rec->useragent_ip и request_rec->useragent_addr .
Когда вам требуется IP-адрес клиента, который подключен непосредственно к серверу, который может быть агентом пользователя или балансировщиком нагрузки или прокси-сервером, используйте conn_rec->client_ip и conn_rec->client_addr .

Если ваш модуль поддерживает эту функцию...

suEXEC: Необязательно: если ваш модуль регистрирует ошибку при ap_unixd_config.suexec_enabled значении 0, также запишите значение нового поля suexec_disabled_reason , которое содержит объяснение, почему оно недоступно.
Расширенные данные о статусе в табло: В предыдущих выпусках ExtendedStatus необходимо было установить значение On , что, в свою очередь, требовало загрузки mod_status. В 2.4 просто установите ap_extended_status в 1 хуке предварительной конфигурации, и расширенные данные о состоянии будут доступны.

Ваш модуль...

Разобрать аргументы запроса: Подумайте, ap_args_to_table() будет ли это полезно.
Разобрать данные формы...: Используйте ap_parse_form_data() .
Проверьте поля заголовка запроса Content-Length и Transfer-Encoding убедитесь, что тело указано.: Используйте ap_request_has_body() .
Реализовать очистку, которая очищает переменные указателя: Используйте ap_pool_cleanup_set_null() .
Создавайте файлы времени выполнения, такие как файлы общей памяти, файлы pid и т. д.: Используйте , чтобы соблюдалась ap_runtime_dir_relative() глобальная конфигурация расположения таких файлов либо в DEFAULT_REL_RUNTIMEDIR настройках компиляции, либо в директиве. Apache httpd 2.4.2 и выше. DefaultRuntimeDir