DOCSEARCHbyAlgolia
Submit Docs

Apache HTTP Server Documentation

repository·trunk·Indexed 26 days ago

https://github.com/apache/httpd

Documentation for the Apache HTTP Server, including guides on the server-status module (requiring mod_lua and mod_status), multi-language error document configuration, and the use of public domain icons. It also provides technical instructions for developers on SVG diagram styling, error log tagging using APLOGNO macros and Coccinelle, and performance benchmarking with the ab tool.

Tokens
21.8K
Snippets
18
Records
153
Agent score
84%

What's inside apache-httpd

  1. Identify new modules in Apache httpd trunk (2.5.x/2.6)

    trunk

    The trunk development line (targeting 2.5.x/2.6) introduces several new modules not present in the 2.4.x series. Key functional additions include:

    • Proxying: mod_proxy_beacon for UDP datagram channels (using ProxyBeacon* directives).
    • Authentication: The autht (authentication token) framework, including mod_autht_jwt (JWT signing/verification) and mod_auth_bearer (RFC 6750 Bearer tokens).
    • Logging: mod_log_json for structured JSON access logs, mod_journald for systemd journal logging, and mod_syslog for syslog provider support.
    • Security & Filters: mod_crypto for encrypting/decrypting request and response bodies via Crypto* directives.
    • WebDAV: Enhanced support via DAVquota (quota support) and DAVMSext (Microsoft WebDAV extensions).

  2. Requirements for server-status

    trunk

    To use the mod_lua version of server-status, ensure your environment meets the following requirements:

    • Apache httpd: version 2.4.6 or higher.
    • mod_lua: Must be installed (can be enabled during configuration with --enable-lua).
    • Lua Runtime: Supports Lua 5.1, 5.2, or LuaJIT.
    • mod_status: Must be loaded to enable traffic statistics.

  3. Install server-status via mod_lua handler

    trunk

    To install server-status as a handler, add the LuaMapHandler directive to your httpd.conf within the appropriate VirtualHost block. This maps the /server-status URL path directly to your Lua script file.

    LuaMapHandler ^/server-status$ /path/to/server-status.lua

  4. Configure mod_proxy_beacon on the Backend

    trunk

    Each backend acts as a sender, periodically announcing its presence to the proxy via UDP.

    Key Configuration Steps:

    1. Use ProxyBeaconAddress to point to the proxy's ProxyBeaconListen address.
    2. Use ProxyBeaconAdvertise to specify the URL the proxy should use to reach this backend. This must be the routable origin (e.g., http://10.0.0.5:8080), not 127.0.0.1.
    3. Use ProxyBeaconSecret to provide the same shared cluster secret used by the proxy.
    4. Use ProxyBeaconInterval to set the announcement frequency. This should be significantly smaller than the proxy's ProxyBeaconTimeout.
    # On each backend
ProxyBeaconAddress   proxy.example.com:5555
ProxyBeaconAdvertise http://10.0.0.5:8080
ProxyBeaconSecret    "a-long-random-shared-cluster-secret"
ProxyBeaconInterval  10

  5. Install and verify mod_proxy_beacon

    trunk

    To use mod_proxy_beacon, you must build Apache HTTPD with the --enable-proxy-beacon flag (or --enable-mods-shared=all).

    Requirements:

    • mod_proxy and mod_proxy_balancer must be installed.
    • mod_watchdog must be installed.
    • A non-prefork MPM (such as event or worker) is required. The module is silently inactive under the prefork MPM.
    • mod_proxy_http (or the relevant backend protocol module) must be installed to handle the actual proxying.

    To verify the module is loaded, use one of the following commands:

    # For shared builds
httpd -M 2>&1 | grep proxy_beacon

# For static builds
httpd -l | grep mod_proxy_beacon
    httpd -M 2>&1 | grep proxy_beacon
# or
httpd -l | grep mod_proxy_beacon

  6. Follow the SVG Diagram Style Guide

    trunk

    When creating new flowchart or diagram SVGs for the documentation, follow these visual conventions to ensure consistency:

    Fonts

    • Primary: Arial, Helvetica, sans-serif
    • Title: 12px, bold
    • Phase/section labels: 11px, bold, fill #444
    • Body text: 10px, fill #333
    • Edge labels (Yes/No): 9px, fill #555
    • Annotations/italic notes: 8px, fill #666, italic

    Colors and Shapes

    ElementFillStrokeNotes
    Process box (action)#e8e8e8#333rx:4 ry:4 rounded corners
    Decision diamond#fff8dc#333
    Terminal (start/done)#d4edda#333rx:12 ry:12 pill shape
    Redirect / error#f8d7da#333 or #b33rx:12 ry:12 pill shape
    Phase box (grouping)#fafafa#888rx:8 ry:8
    Warning box#f8d7da#b33rx:4 ry:4, stroke-width 1.5
    Lines/arrows—#333stroke-width 1.2
    Dashed lines (loops)—#333stroke-dasharray: 5,4

    General Conventions

    • Use diamonds for decisions, rounded rectangles for actions, and pill shapes for start/end terminals.
    • Place Yes/No labels on decision branches (9px, gray).
    • Use phase boxes to group related steps in the same processing context.
    • Use dashed lines for loop-back paths or optional flows.
    • Center titles at the top of the SVG.
    • Typical viewBox dimensions: Width 440–650px, Height 360–750px.

  7. Configure mod_proxy_beacon on the Reverse Proxy

    trunk

    The reverse proxy acts as the receiver. It listens for UDP datagrams from backends and dynamically manages the balancer membership.

    Key Configuration Steps:

    1. Use ProxyBeaconListen to bind a UDP socket to receive announcements.
    2. Use ProxyBeaconBalancer to specify which balancer the members should be added to.
    3. Use ProxyBeaconSecret to provide the shared cluster secret (required).
    4. Set ProxyBeaconTimeout to define how long a backend can be silent before being evicted.
    5. Ensure the target <Proxy balancer://...> has sufficient growth slots to accommodate the expected fleet size.

    Note: ProxyBeaconListen and ProxyBeaconAddress are mutually exclusive on a single server. A server is either a receiver or a sender.

    # On the reverse proxy
ProxyBeaconListen   0.0.0.0:5555
ProxyBeaconSecret   "a-long-random-shared-cluster-secret"
ProxyBeaconBalancer cluster

# Drop a backend from rotation if it goes silent for 30s; re-add on next beacon.
ProxyBeaconTimeout  30

# An initially EMPTY balancer with spare slots for the dynamic members.
<Proxy balancer://cluster>
    ProxySet growth=16
</Proxy>

ProxyPass        "/" "balancer://cluster/"
ProxyPassReverse "/" "balancer://cluster/"

  8. Identify safe modules and directives for back-porting from trunk to 2.4.x

    trunk

    When migrating features from the trunk (2.5.x/2.6) to a stable 2.4.x environment, use the following tier-based recommendations to minimize ABI risk and dependency issues:

    Tier 1: Recommended (Low risk, self-contained)

    These are additive modules or discrete directives that are generally safe to cherry-pick:

    • Loggers: mod_log_json, mod_syslog, mod_journald
    • Modules: mod_allowhandlers, mod_crypto (requires APR crypto), mod_proxy_beacon
    • Core Directives: LogLevelOverride, HttpExpectStrict, HttpContentLengthHeadZero, IndexForbiddenReturn404, SessionCookieMaxAge, MimeOptions, MimeMagicDecompression, SSLPolicy, DAVLockDBType, DAVHonorMtimeHeader

    Tier 2: Feasible with Caution (Bundled dependencies)

    These require careful dependency ordering or a small framework to function:

    • Authentication Set: mod_autht_core + mod_autht_jwt + mod_auth_bearer (the new "autht" provider category).
    • Async Proxy/Websocket: ProxyAsync* and ProxyWebsocket* directives (requires verifying underlying core async support in 2.4.x).
    • DAV Extensions: mod_dav quota or MS extensions (DAVquota, DAVMSext).

    Tier 3: Do NOT Back-port (High risk/Incompatible)

    Avoid these as they are experimental, obsolete, or involve breaking ABI changes:

    • Core Engine Refactors: Changes involving the core/http split, generic-HTTP filter split, ap_method_mask_t, bucket REQUEST/RESPONSE/HEADERS types, or ssl_var_lookup signature changes.
    • Experimental/Obsolete Modules: mpm_simple, mod_noloris, mod_policy, mod_ssl_ct (incompatible with OpenSSL-3), mod_serf, or mod_lbmethod_rr (example code).

  9. Install server-status as a web app

    trunk

    To install server-status as a plain web app, you must first enable .lua scripts to be handled by mod_lua by adding the AddHandler directive to your VirtualHost configuration. Once enabled, place the .lua script within your document root and access it via its URL.

    AddHandler lua-script .lua

  10. Generate PNGs from SVGs using rsvg-convert

    trunk

    To convert SVG diagrams into PNGs for documentation, use rsvg-convert (part of the librsvg package).

    1. Install librsvg

    • macOS: brew install librsvg
    • Fedora/RHEL/CentOS: dnf install librsvg2-tools
    • Debian/Ubuntu: apt-get install librsvg2-bin

    2. Convert SVGs

    To maintain consistency with the documentation build, keep PNGs at 1x scale (matching the SVG viewBox dimensions).

    Convert at 1x (matching viewBox):

    rsvg-convert -o output.png input.svg

    Convert with explicit dimensions:

    rsvg-convert -w 520 -h 720 -o output.png input.svg
    # Convert at 1x (matching SVG viewBox dimensions):
rsvg-convert -o rewrite_l_flag_looping.png rewrite_l_flag_looping.svg

# Or specify explicit dimensions:
rsvg-convert -w 520 -h 720 -o rewrite_l_flag_looping.png rewrite_l_flag_looping.svg

  11. Overview of mod_proxy_beacon

    trunk

    mod_proxy_beacon provides a self-registering reverse-proxy balancer membership mechanism. Backend servers announce their presence to a front-end proxy via unicast UDP datagrams. The proxy then automatically adds, enables, or evicts these backends as live members of a balancer:// group.

    Key Characteristics:

    • Transport: Unicast UDP (not multicast), making it suitable for cross-host control planes and traversing the public Internet.
    • Reliability: Designed to tolerate UDP loss and reordering. Announcements are periodic and idempotent; out-of-order datagrams are rejected via monotonic timestamps.
    • Architecture: Uses a single mod_watchdog singleton child process to manage the UDP socket and membership changes.
    • Security: Requires a shared secret for authentication using SipHash-2-4. It provides replay protection via a freshness window and per-URL monotonic timestamps.
    • Compatibility: Inactive under the prefork MPM due to the requirement for a singleton watchdog child.

  12. Overview of mod_ssl

    trunk
    The mod_ssl module provides strong cryptography for the Apache 2 webserver. It implements Secure Sockets Layer (SSL v2/v3) and Transport Layer Security (TLS v1) protocols by leveraging the OpenSSL library. It is used to enable HTTPS and secure communication for Apache servers.