Apache HTTP Server Version 2.5
Available Languages: en
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.
ap_mpm_run
is replaced by a new mpm
hook.
Also ap_graceful_stop_signalled
is lost, and
ap_mpm_register_timed_callback
is new.
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 ap_parse_htaccess
has been
changed. A apr_table_t
of individual directives allowed
for override must now be passed (override remains).
AP_DECLARE_MODULE
macro to declare all modules.APLOG_USE_MODULE
macro necessary for per-module loglevels in
multi-file modules.check_config
hookap_process_fnmatch_configs()
function to process wildcardsap_configfile_t
, ap_cfg_getline()
,
ap_cfg_getc()
to return error codes, and add
ap_pcfg_strerror()
for retrieving an error description.AllowOverrideList
directive.
ap_check_cmd_context() accepts a new flag NOT_IN_HTACCESS to detect
this case.ap_default_type
, ap_requires
, all
2.2 authnz APIap_get_server_name_for_url
to support IPv6
literals.ap_register_errorlog_handler
to register error log
format string handlers.error_log
hook have changed. Declaration has moved to
http_core.h
.ap_state_query
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.ap_get_conn_socket
to get the socket descriptor for a
connection. This should be used instead of accessing the core
connection config directly.APLOG_TRACEn
CONN_STATE
valuesap_escape_html
updated;
ap_unescape_all
, ap_escape_path_segment_buffer
EXEC_ON_READ
config
reading stage need to call ap_reserve_module_slots()
or
ap_reserve_module_slots_directive()
in their
pre_config hook
.APLOG_TRACEn
ap_log_*error
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 error_log hookap_log_command_line
EOR
bucket typeap_process_async_request
AP_AUTH_INTERNAL_PER_CONF
and
AP_AUTH_INTERNAL_PER_URI
access_checker_ex
hook to apply additional access control
and/or bypass authentication.ap_hook_check_access_ex
,
ap_hook_check_access
, ap_hook_check_authn
,
ap_hook_check_authz
which accept
AP_AUTH_INTERNAL_PER_*
flagsap_hook_access_checker
,
access_checker_ex
, ap_hook_check_user_id
,
ap_hook_auth_checker
When possible, registering all access control hooks (including
authentication and authorization hooks) using AP_AUTH_INTERNAL_PER_CONF
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
AP_AUTH_INTERNAL_PER_URI
.
Introduces the new provider framework for authn and authz
Introduces a commit_entity()
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 mod_disk_cache module has been renamed to mod_cache_disk in order to be consistent with the naming of other modules within the server.
The API for mod_request
, to make input data
available to multiple application/handler modules where required,
and to parse HTML form data.
accept
, lockfile
, lock_mech
,
set_scoreboard
(locking uses the new ap_mutex API)mpm_query
, timed_callback
, and
get_name
monitor
hook,
ap_reclaim_child_processes
,
ap_relieve_child_processes
ap_get_scoreboard_worker
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.
no description available
A wrapper for APR proc and global mutexes in httpd, providing common configuration for the underlying mechanism and location of lock files.
NEW: ap_args_to_table
NEW: ap_recent_ctime_ex
In order to take advantage of per-module loglevel configuration, any
source file that calls the ap_log_*
functions should declare
which module it belongs to. If the module's module_struct is called
foo_module
, the following code can be used to remain
backward compatible with HTTPD 2.0 and 2.2:
#include <http_log.h>
#ifdef APLOG_USE_MODULE
APLOG_USE_MODULE(foo);
#endif
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 ap_log_*
functions and the
definition of APLOG_MARK
has changed. Normally, the change
is completely transparent. However, changes are required if a
module uses APLOG_MARK
as a parameter to its own functions
or if a module calls ap_log_*
without passing
APLOG_MARK
. A module which uses wrappers
around ap_log_*
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 ap_log_*
directly. In this way, the code will remain compatible with HTTPD 2.0
and 2.2.
Code which calls ap_log_*
without passing
APLOG_MARK
will necessarily differ between 2.4 and earlier
releases, as 2.4 requires a new third argument,
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
are now implemented as macros. This means
that it is no longer possible to use #ifdef
inside the
argument list of ap_log_*error
, as this would cause
undefined behavior according to C99.
A server_rec
pointer must be passed to
ap_log_error()
when called after startup. This
was always appropriate, but there are even more limitations with
a NULL
server_rec
in 2.4 than in
previous releases. Beginning with 2.3.12, the global variable
ap_server_conf
can always be used as
the server_rec
parameter, as it will be
NULL
only when it is valid to pass NULL
to ap_log_error()
. ap_server_conf
should be used only when a more appropriate server_rec
is not available.
Consider the following changes to take advantage of the new
APLOG_TRACE1..8
log levels:
APLOG_DEBUG
and
consider if one of the APLOG_TRACEn
levels is
more appropriate.APLOG_TRACEn
levels. If expensive
trace processing needs to be bypassed depending on the
configured log level, use the APLOGtracen
and APLOGrtracen
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.)
ap_default_type()
ap_get_server_name()
ap_get_server_name_for_url()
instead. This new
function handles the odd case where the server name is an IPv6
literal address.ap_get_server_version()
ap_get_server_description()
.
When generating output, where the amount of information
should be configurable by ServerTokens, use
ap_get_server_banner()
.ap_graceful_stop_signalled()
ap_mpm_query(AP_MPMQ_MPM_STATE)
and checking for
state AP_MPMQ_STOPPING
.ap_max_daemons_limit
, ap_my_generation
,
and ap_threads_per_child
ap_mpm_query()
query codes
AP_MPMQ_MAX_DAEMON_USED
, AP_MPMQ_GENERATION
,
and AP_MPMQ_MAX_THREADS
, respectively.ap_mpm_query()
ap_requires()
Require
configuration.
Register an auth provider function for each supported entity using
ap_register_auth_provider()
. The function will be
called as necessary during Require
processing. (Consult bundled modules for detailed examples.)ap_server_conf->process->pool
userdataap_state_query(AP_SQ_MAIN_STATE)
.ap_retained_data_create()
and
ap_retained_data_get()
.apr_global_mutex_create()
,
apr_proc_mutex_create()
ap_mutex_register()
,
ap_global_mutex_create()
, and
ap_proc_mutex_create()
; 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
dav_new_error()
and dav_new_error_tag()
errno
contained
information describing the failure. Now,
an apr_status_t
parameter must be provided. Pass
0/APR_SUCCESS if there is no such error information, or a valid
apr_status_t
value otherwise.mpm_default.h
, DEFAULT_LOCKFILE
,
DEFAULT_THREAD_LIMIT
, DEFAULT_PIDLOG
,
etc.DEFAULT_PIDLOG
and DEFAULT_REL_RUNTIMEDIR
are now universally
available via ap_config.h
.unixd_config
conn_rec->remote_ip
and
conn_rec->remote_addr
request_rec->useragent_ip
and
request_rec->useragent_addr
.conn_rec->client_ip
and
conn_rec->client_addr
.ap_unixd_config.suexec_enabled
is 0,
also log the value of the new
field suexec_disabled_reason
, which contains an
explanation of why it is not available.ExtendedStatus
had to be
set to On
, which in turn required that
mod_status was loaded. In 2.4, just
set ap_extended_status
to 1
in a
pre-config hook and the extended status data will be
available.ap_args_to_table()
would be
helpful.ap_parse_form_data()
.Content-Length
and Transfer-Encoding
to see if a body was
specifiedap_request_has_body()
.ap_pool_cleanup_set_null()
.ap_runtime_dir_relative()
so that the global
configuration for the location of such files, either by the
DEFAULT_REL_RUNTIMEDIR
compile setting or the
DefaultRuntimeDir
directive,
will be respected. Apache httpd 2.4.2 and above.Available Languages: en