API Changes in Apache HTTP Server 2.4 since 2.2

This document describes changes to the Apache HTTPD API from version 2.2 to 2.4, that may be of interest to module/application developers and core hacks. As of the first GA release of the 2.4 branch API compatibility is preserved for the life of the 2.4 branch. (The VERSIONING description for the 2.4 release provides more information about API compatibility.)

API changes fall into two categories: APIs that are altogether new, and existing APIs that are expanded or changed. The latter are further divided into those where all changes are backwards-compatible (so existing modules can ignore them), and those that might require attention by maintainers. As with the transition from HTTPD 2.0 to 2.2, existing modules and applications will require recompiling and may call for some attention, but most should not require any substantial updating (although some may be able to take advantage of API changes to offer significant improvements).

For the purpose of this document, the API is split according to the public header files. These headers are themselves the reference documentation, and can be used to generate a browsable HTML reference with make docs

Introduces a new API to parse and evaluate boolean and algebraic expressions, including provision for a standard syntax and customised variants.

Introduces a new API to enable httpd child processes to serve different purposes.

is lost, and apmpmregistertimedcallback

In addition to the existing regexp wrapper, a new higher-level API ap_rxplus

is now provided. This provides the capability to compile Perl-style expressions like s/regexp/replacement/flags

and to execute them against arbitrary strings. Support for regexp backreferences is also added.

Introduces an API for modules to allocate and manage memory slots, most commonly for shared memory.

API to manage a shared object cache.

common structures for heartbeat modules

The function signature for apparsehtaccess

has been changed. A aprtablet

of individual directives allowed for override must now be passed (override remains).

macro to declare all modules.APLOGUSEMODULE

macro necessary for per-module loglevels in multi-file modules.check_config

function to process wildcardsapconfigfilet

to return error codes, and add appcfgstrerror()

for retrieving an error description.AllowOverrideList

directive. apcheckcmdcontext() accepts a new flag NOTINHTACCESS to detect this case.apdefault_type

, all 2.2 authnz APIapgetservernamefor_url

to support IPv6 literals.apregistererrorlog_handler

to register error log format string handlers.error_log

hook have changed. Declaration has moved to http_core.h

to determine if the server is in the initial configuration preflight phase or not. This is both easier to use and more correct than the old method of creating a pool userdata entry in the process pool.apgetconn_socket

to get the socket descriptor for a connection. This should be used instead of accessing the core connection config directly.APLOG_TRACEn

config reading stage need to call apreservemodule_slots()

in their pre_config hook

become macro wrappers (backwards-compatible if APLOG_MARK

macro is used, except that is no longer possible to use #ifdef

inside the argument list)module_index

added to errorlog hookaplogcommandline

hook to apply additional access control and/or bypass authentication.aphookcheckaccessex

When possible, registering all access control hooks (including authentication and authorization hooks) using APAUTHINTERNALPERCONF

is recommended. If all modules' access control hooks are registered with this flag, then whenever the server handles an internal sub-request that matches the same set of access control configuration directives as the initial request (which is the common case), it can avoid invoking the access control hooks another time.

If your module requires the old behavior and must perform access control checks on every sub-request with a different URI from the initial request, even if that URI matches the same set of access control configuration directives, then use APAUTHINTERNALPERURI

Introduces the new provider framework for authn and authz

function to the cache provider interface, allowing atomic writes to cache. Add a cache_status()

hook to report the cache decision. All private structures and functions were removed.

This introduces low-level APIs to send arbitrary headers, and exposes functions to handle HTTP OPTIONS and TRACE.

Changes the disk format of the disk cache to support atomic cache updates without locking. The device/inode pair of the body file is embedded in the header file, allowing confirmation that the header and body belong to one another.

The moddiskcache module has been renamed to modcachedisk in order to be consistent with the naming of other modules within the server.

, to make input data available to multiple application/handler modules where required, and to parse HTML form data.mod_request

(locking uses the new apmutex API)mpmquery

is made non-backwards-compatible as an alternative version is introduced. Additional proxy_balancer support. Child status stuff revamped.

Introduces a new API for managing HTTP Cookies.

A wrapper for APR proc and global mutexes in httpd, providing common configuration for the underlying mechanism and location of lock files.

In order to take advantage of per-module loglevel configuration, any source file that calls the aplog*

functions should declare which module it belongs to. If the module's modulestruct is called foomodule

, the following code can be used to remain backward compatible with HTTPD 2.0 and 2.2:

Note: This is absolutely required for C++-language modules. It can be skipped for C-language modules, though that breaks module-specific log level support for files without it.

The number of parameters of the aplog*

has changed. Normally, the change is completely transparent. However, changes are required if a module uses APLOG_MARK

typically uses both of these constructs.

The easiest way to change code which passes APLOG_MARK

to its own functions is to define and use a different macro that expands to the parameters required by those functions, as APLOG_MARK

should only be used when calling aplog*

will necessarily differ between 2.4 and earlier releases, as 2.4 requires a new third argument, APLOGMODULEINDEX

aplogperror(file, line, APLOG_ERR, 0, p, "Failed to allocate dynamic lock structure");

are now implemented as macros. This means that it is no longer possible to use #ifdef

, as this would cause undefined behavor according to C99.

pointer must be passed to aplogerror()

when called after startup. This was always appropriate, but there are even more limitations with a NULL

in 2.4 than in previous releases. Beginning with 2.3.12, the global variable apserverconf

only when it is valid to pass NULL

Consider the following changes to take advantage of the new APLOG_TRACE1..8

levels. If expensive trace processing needs to be bypassed depending on the configured log level, use the APLOGtracen

macros to first check if tracing is enabled.Modules sometimes add process id and/or thread id to their log messages. These ids are now logged by default, so it may not be necessary for the module to log them explicitly. (Users may remove them from the error log format, but they can be instructed to add it back if necessary for problem diagnosis.)

instead. This new function handles the odd case where the server name is an IPv6 literal address.apgetserver_version()

. When generating output, where the amount of information should be configurable by ServerTokens, use apgetserver_banner()

and checking for state APMPMQSTOPPING

configuration. Register an auth provider function for each supported entity using apregisterauth_provider()

processing. (Consult bundled modules for detailed examples.)apserverconf->process->pool

; these allow your mutexes to be configurable with the Mutex

directive; you can also remove any configuration mechanisms in your module for such mutexes CORE_PRIVATE

contained information describing the failure. Now, an aprstatust

parameter must be provided. Pass 0/APRSUCCESS if there is no such error information, or a valid aprstatus_t

value otherwise.mpm_default.h

are now universally available via ap_config.h

is 0, also log the value of the new field suexecdisabledreason

, which contains an explanation of why it is not available.ExtendedStatus

, which in turn required that modstatus was loaded. In 2.4, just set apextended_status

in a pre-config hook and the extended status data will be available.apargsto_table()

would be helpful.apparseform_data()

so that the global configuration for the location of such files, either by the DEFAULTRELRUNTIMEDIR

compile setting or the DefaultRuntimeDir

Modules | Directives | FAQ | Glossary | Sitemap

Apache HTTP Server Version 2.4