control block as in the following example: Require ip 192.168.0 For more information on access control directives, see MOD AUTHZ HOST. Strictly limiting access is essential if you are using a forward proxy (using the P ROXY R EQUESTS directive). Otherwise, your server can be used by any client to access arbitrary hosts while hiding his or her true identity. This is dangerous both for your network and for the Internet at large. When using a reverse proxy (using the P ROXY PASS directive with ProxyRequests Off), access control is less critical because clients can only contact the hosts that you have specifically configured. See Also the Proxy-Chain-Auth (p. 850) environment variable. 792 CHAPTER 10. APACHE MODULES Slow Startup If you’re using the P ROXY B LOCK directive, hostnames’ IP addresses are looked up and cached during startup for later match test. This may take a few seconds (or more) depending on the speed with which the hostname lookups occur. Intranet Proxy An Apache httpd proxy server situated in an intranet needs to forward external requests through the company’s firewall (for this, configure the P ROXY R EMOTE directive to forward the respective scheme to the firewall proxy). However, when it has to access resources within the intranet, it can bypass the firewall when accessing hosts. The N O P ROXY directive is useful for specifying which hosts belong to the intranet and should be accessed directly. Users within an intranet tend to omit the local domain name from their WWW requests, thus requesting "http://somehost/" instead of http://somehost.example.com/. Some commercial proxy servers let them get away with this and simply serve the request, implying a configured local domain. When the P ROXY D OMAIN directive is used and the server is configured for proxy service, Apache httpd can return a redirect response and send the client to the correct, fully qualified, server address. This is the preferred method since the user’s bookmark files will then contain fully qualified hosts. Protocol Adjustments For circumstances where MOD PROXY is sending requests to an origin server that doesn’t properly implement keepalives or HTTP/1.1, there are two environment variables (p. 92) that can force the request to use HTTP/1.0 with no keepalive. These are set via the S ET E NV directive. These are the force-proxy-request-1.0 and proxy-nokeepalive notes. ProxyPass "http://buggyappserver:7001/foo/" SetEnv force-proxy-request-1.0 1 SetEnv proxy-nokeepalive 1 Request Bodies Some request methods such as POST include a request body. The HTTP protocol requires that requests which include a body either use chunked transfer encoding or send a Content-Length request header. When passing these requests on to the origin server, MOD PROXY HTTP will always attempt to send the Content-Length. But if the body is large and the original request used chunked encoding, then chunked encoding may also be used in the upstream request. You can control this selection using environment variables (p. 92) . Setting proxy-sendcl ensures maximum compatibility with upstream servers by always sending the Content-Length, while setting proxy-sendchunked minimizes resource usage by using chunked encoding. Under some circumstances, the server must spool request bodies to disk to satisfy the requested handling of request bodies. For example, this spooling will occur if the original body was sent with chunked encoding (and is large), but the administrator has asked for backend requests to be sent with Content-Length or as HTTP/1.0. This spooling can also occur if the request body already has a Content-Length header, but the server is configured to filter incoming request bodies. L IMIT R EQUEST B ODY only applies to request bodies that the server will spool to disk 10.81. APACHE MODULE MOD PROXY 793 Reverse Proxy Request Headers When acting in a reverse-proxy mode (using the P ROXY PASS directive, for example), MOD PROXY HTTP adds several request headers in order to pass information to the origin server. These headers are: X-Forwarded-For The IP address of the client. X-Forwarded-Host The original host requested by the client in the Host HTTP request header. X-Forwarded-Server The hostname of the proxy server. Be careful when using these headers on the origin server, since they will contain more than one (commaseparated) value if the original request already contained one of these headers. For example, you can use %{X-Forwarded-For}i in the log format string of the origin server to log the original clients IP address, but you may get more than one address if the request passes through several proxies. See also the P ROXY P RESERVE H OST and P ROXY V IA directives, which control other request headers. Note: If you need to specify custom request headers to be added to the forwarded request, use the R EQUEST H EADER directive. BalancerGrowth Directive Description: Syntax: Default: Context: Status: Module: Compatibility: Number of additional Balancers that can be added Post-configuration BalancerGrowth # BalancerGrowth 5 server config, virtual host Extension mod proxy BalancerGrowth is only available in Apache HTTP Server 2.3.13 and later. This directive allows for growth potential in the number of Balancers available for a virtualhost in addition to the number pre-configured. It only takes effect if there is at least one pre-configured Balancer. BalancerInherit Directive Description: Syntax: Default: Context: Status: Module: Compatibility: Inherit proxy Balancers/Workers defined from the main server BalancerInherit On|Off BalancerInherit On server config, virtual host Extension mod proxy BalancerInherit is only available in Apache HTTP Server 2.4.5 and later. This directive will cause the current server/vhost to "inherit" Balancers and Workers defined in the main server. This can cause issues and inconsistent behavior if using the Balancer Manager for dynamic changes and so should be disabled if using that feature. The setting in the global server defines the default for all vhosts. Disabling P ROXY PASS I NHERIT also disables BalancerInherit. 794 CHAPTER 10. APACHE MODULES BalancerMember Directive Description: Syntax: Context: Status: Module: Add a member to a load balancing group BalancerMember [balancerurl] url [key=value [key=value ...]] directory Extension mod proxy This directive adds a member to a load balancing group. It can be used within a container directive and can take any of the key value pair parameters available to P ROXY PASS directives. One additional parameter is available only to BALANCER M EMBER directives: loadfactor. This is the member load factor - a number between 1 (default) and 100, which defines the weighted load to be applied to the member in question. The balancerurl is only needed when not within a container directive. It corresponds to the url of a balancer defined in P ROXY PASS directive. The path component of the balancer URL in any container directive is ignored. Trailing slashes should typically be removed from the URL of a BALANCER M EMBER. BalancerPersist Directive Description: Syntax: Default: Context: Status: Module: Compatibility: Attempt to persist changes made by the Balancer Manager across restarts. BalancerPersist On|Off BalancerPersist Off server config, virtual host Extension mod proxy BalancerPersist is only available in Apache HTTP Server 2.4.4 and later. This directive will cause the shared memory storage associated with the balancers and balancer members to be persisted across restarts. This allows these local changes to not be lost during the normal restart/graceful state transitions. NoProxy Directive Description: Syntax: Context: Status: Module: Hosts, domains, or networks that will be connected to directly NoProxy host [host] ... server config, virtual host Extension mod proxy This directive is only useful for Apache httpd proxy servers within intranets. The N O P ROXY directive specifies a list of subnets, IP addresses, hosts and/or domains, separated by spaces. A request to a host which matches one or more of these is always served directly, without forwarding to the configured P ROXY R EMOTE proxy server(s). Example ProxyRemote NoProxy * http://firewall.example.com:81 .example.com 192.168.112.0/21 The host arguments to the N O P ROXY directive are one of the following type list: Domain A Domain is a partially qualified DNS domain name, preceded by a period. It represents a list of hosts which logically belong to the same DNS domain or zone (i.e., the suffixes of the hostnames are all ending in Domain). 10.81. APACHE MODULE MOD PROXY 795 Examples .com .example.org. To distinguish Domains from Hostnames (both syntactically and semantically; a DNS domain can have a DNS A record, too!), Domains are always written with a leading period. =⇒Note Domain name comparisons are done without regard to the case, and Domains are always as- sumed to be anchored in the root of the DNS tree; therefore, the two domains .ExAmple.com and .example.com. (note the trailing period) are considered equal. Since a domain comparison does not involve a DNS lookup, it is much more efficient than subnet comparison. SubNet A SubNet is a partially qualified internet address in numeric (dotted quad) form, optionally followed by a slash and the netmask, specified as the number of significant bits in the SubNet. It is used to represent a subnet of hosts which can be reached over a common network interface. In the absence of the explicit net mask it is assumed that omitted (or zero valued) trailing digits specify the mask. (In this case, the netmask can only be multiples of 8 bits wide.) Examples: 192.168 or 192.168.0.0 the subnet 192.168.0.0 with an implied netmask of 16 valid bits (sometimes used in the netmask form 255.255.0.0) 192.168.112.0/21 the subnet 192.168.112.0/21 with a netmask of 21 valid bits (also used in the form 255.255.248.0) As a degenerate case, a SubNet with 32 valid bits is the equivalent to an IPAddr, while a SubNet with zero valid bits (e.g., 0.0.0.0/0) is the same as the constant Default , matching any IP address. IPAddr A IPAddr represents a fully qualified internet address in numeric (dotted quad) form. Usually, this address represents a host, but there need not necessarily be a DNS domain name connected with the address. Example 192.168.123.7 =⇒Note An IPAddr does not need to be resolved by the DNS system, so it can result in more effective apache performance. Hostname A Hostname is a fully qualified DNS domain name which can be resolved to one or more IPAddrs via the DNS domain name service. It represents a logical host (in contrast to Domains, see above) and must be resolvable to at least one IPAddr (or often to a list of hosts with different IPAddrs). Examples prep.ai.example.edu www.example.org =⇒Note In many situations, it is more effective to specify an IPAddr in place of a Hostname since a DNS lookup can be avoided. Name resolution in Apache httpd can take a remarkable deal of time when the connection to the name server uses a slow PPP link. Hostname comparisons are done without regard to the case, and Hostnames are always assumed to be anchored in the root of the DNS tree; therefore, the two hosts WWW.ExAmple.com and www.example.com. (note the trailing period) are considered equal. See also • DNS Issues (p. 121) 796 CHAPTER 10. APACHE MODULES Proxy Directive Description: Syntax: Context: Status: Module: Container for directives applied to proxied resources ... server config, virtual host Extension mod proxy Directives placed in

sections apply only to matching proxied content. Shell-style wildcards are allowed. For example, the following will allow only hosts in yournetwork.example.com to access content via your proxy server: Require host yournetwork.example.com The following example will process all files in the foo directory of example.com through the INCLUDES filter when they are sent through the proxy server: SetOutputFilter INCLUDES The next example will allow web clients from the specified IP addresses to issue CONNECT requests to access the https://www.example.com/ SSL server if MOD PROXY CONNECT is enabled. Require ip 192.168.0.0/16 =⇒Differences from the Location configuration section A backend URL matches the configuration section if it begins with the the wildcard-url string, even if the last path segment in the directive only matches a prefix of the backend URL. For example, matches all of http://example.com/foo, http://example.com/foo/bar, and http://example.com/foobar. The matching of the final URL differs from the behavior of the section, which for purposes of this note treats the final path component as if it ended in a slash. For more control over the matching, see

. See also •

ProxyAddHeaders Directive Description: Syntax: Default: Context: Status: Module: Compatibility: Add proxy information in X-Forwarded-* headers ProxyAddHeaders Off|On ProxyAddHeaders On server config, virtual host, directory Extension mod proxy Available in version 2.3.10 and later 10.81. APACHE MODULE MOD PROXY 797 This directive determines whether or not proxy related information should be passed to the backend server through X-Forwarded-For, X-Forwarded-Host and X-Forwarded-Server HTTP headers. =⇒Effectiveness This option is of use only for HTTP proxying, as handled by MOD PROXY HTTP. ProxyBadHeader Directive Description: Syntax: Default: Context: Status: Module: Determines how to handle bad header lines in a response ProxyBadHeader IsError|Ignore|StartBody ProxyBadHeader IsError server config, virtual host Extension mod proxy The P ROXY BAD H EADER directive determines the behavior of MOD PROXY if it receives syntactically invalid response header lines (i.e. containing no colon) from the origin server. The following arguments are possible: IsError Abort the request and end up with a 502 (Bad Gateway) response. This is the default behavior. Ignore Treat bad header lines as if they weren’t sent. StartBody When receiving the first bad header line, finish reading the headers and treat the remainder as body. This helps to work around buggy backend servers which forget to insert an empty line between the headers and the body. ProxyBlock Directive Description: Syntax: Context: Status: Module: Disallow proxy requests to certain hosts ProxyBlock *|hostname|partial-hostname [hostname|partial-hostname]... server config, virtual host Extension mod proxy The P ROXY B LOCK directive can be used to block FTP or HTTP access to certain hosts via the proxy, based on a full or partial hostname match, or, if applicable, an IP address comparison. Each of the arguments to the P ROXY B LOCK directive can be either * or a alphanumeric string. At startup, the module will attempt to resolve every alphanumeric string from a DNS name to a set of IP addresses, but any DNS errors are ignored. If an asterisk "*" argument is specified, MOD PROXY will deny access to all FTP or HTTP sites. Otherwise, for any request for an HTTP or FTP resource via the proxy, MOD PROXY will check the hostname of the request URI against each specified string. If a partial string match is found, access is denied. If no matches against hostnames are found, and a remote (forward) proxy is configured using P ROXY R EMOTE or P ROXY R EMOTE M ATCH, access is allowed. If no remote (forward) proxy is configured, the IP address of the hostname from the URI is compared against all resolved IP addresses determined at startup. Access is denied if any match is found. Note that the DNS lookups may slow down the startup time of the server. Example ProxyBlock news.example.com auctions.example.com friends.example.com 798 CHAPTER 10. APACHE MODULES Note that example would also be sufficient to match any of these sites. Hosts would also be matched if referenced by IP address. Note also that ProxyBlock * blocks connections to all sites. ProxyDomain Directive Description: Syntax: Context: Status: Module: Default domain name for proxied requests ProxyDomain Domain server config, virtual host Extension mod proxy This directive is only useful for Apache httpd proxy servers within intranets. The P ROXY D OMAIN directive specifies the default domain which the apache proxy server will belong to. If a request to a host without a domain name is encountered, a redirection response to the same host with the configured Domain appended will be generated. Example ProxyRemote NoProxy ProxyDomain " *" "http://firewall.example.com:81" ".example.com" "192.168.112.0/21" ".example.com" ProxyErrorOverride Directive Description: Syntax: Default: Context: Status: Module: Override error pages for proxied content ProxyErrorOverride On|Off ProxyErrorOverride Off server config, virtual host, directory Extension mod proxy This directive is useful for reverse-proxy setups where you want to have a common look and feel on the error pages seen by the end user. This also allows for included files (via MOD INCLUDE’s SSI) to get the error code and act accordingly. (Default behavior would display the error page of the proxied server. Turning this on shows the SSI Error message.) This directive does not affect the processing of informational (1xx), normal success (2xx), or redirect (3xx) responses. ProxyIOBufferSize Directive Description: Syntax: Default: Context: Status: Module: Determine size of internal data throughput buffer ProxyIOBufferSize bytes ProxyIOBufferSize 8192 server config, virtual host Extension mod proxy 10.81. APACHE MODULE MOD PROXY 799 The P ROXY IOB UFFER S IZE directive adjusts the size of the internal buffer which is used as a scratchpad for the data between input and output. The size must be at least 512. In almost every case, there’s no reason to change that value. If used with AJP, this directive sets the maximum AJP packet size in bytes. Values larger than 65536 are set to 65536. If you change it from the default, you must also change the packetSize attribute of your AJP connector on the Tomcat side! The attribute packetSize is only available in Tomcat 5.5.20+ and 6.0.2+ Normally it is not necessary to change the maximum packet size. Problems with the default value have been reported when sending certificates or certificate chains. ProxyMatch Directive Description: Syntax: Context: Status: Module: Container for directives applied to regular-expression-matched proxied resources ... server config, virtual host Extension mod proxy The

directive is identical to the

directive, except that it matches URLs using regular expressions. From 2.4.8 onwards, named groups and backreferences are captured and written to the environment with the corresponding name prefixed with "MATCH " and in upper case. This allows elements of URLs to be referenced from within expressions (p. 99) and modules like MOD REWRITE. In order to prevent confusion, numbered (unnamed) backreferences are ignored. Use named groups instead. [ˆ/]+)> require ldap-group cn=%{env:MATCH_SITENAME},ou=combined,o=Example See also •

ProxyMaxForwards Directive Description: Syntax: Default: Context: Status: Module: Maximium number of proxies that a request can be forwarded through ProxyMaxForwards number ProxyMaxForwards -1 server config, virtual host Extension mod proxy The P ROXY M AX F ORWARDS directive specifies the maximum number of proxies through which a request may pass if there’s no Max-Forwards header supplied with the request. This may be set to prevent infinite proxy loops or a DoS attack. Example ProxyMaxForwards 15 Note that setting P ROXY M AX F ORWARDS is a violation of the HTTP/1.1 protocol (RFC2616), which forbids a Proxy setting Max-Forwards if the Client didn’t set it. Earlier Apache httpd versions would always set it. A negative P ROXY M AX F ORWARDS value, including the default -1, gives you protocol-compliant behavior but may leave you open to loops. 800 CHAPTER 10. APACHE MODULES ProxyPass Directive Description: Syntax: Context: Status: Module: Compatibility: Maps remote servers into the local server URL-space ProxyPass [path] !|url [key=value [key=value ...]] [interpolate] [noquery] server config, virtual host, directory Extension mod proxy Unix Domain Socket (UDS) support added in 2.4.7 [nocanon] This directive allows remote servers to be mapped into the space of the local server. The local server does not act as a proxy in the conventional sense but appears to be a mirror of the remote server. The local server is often called a reverse proxy or gateway. The path is the name of a local virtual path; url is a partial URL for the remote server and cannot include a query string. =⇒Note: This directive cannot be used within a context. ! The P R directive should usually be set off when using P ROXY PASS . ROXY EQUESTS In 2.4.7 and later, support for using a Unix Domain Socket is available by using a target which prepends unix:/path/lis.sock|. For example, to proxy HTTP and target the UDS at /home/www/socket, you would use unix:/home/www.socket|http://localhost/whatever/. Since the socket is local, the hostname used (in this case localhost) is moot, but it is passed as the Host: header value of the request. =⇒Note: The path associated with the unix: URL is D R D aware. =⇒Note: R R requires the [P,NE] option to prevent the ’|’ character from being escaped. EFAULT UNTIME IR EWRITE ULE When used inside a section, the first argument is omitted and the local directory is obtained from the . The same will occur inside a section; however, ProxyPass does not interpret the regexp as such, so it is necessary to use P ROXY PASS M ATCH in this situation instead. Suppose the local server has address http://example.com/; then ProxyPass "http://backend.example.com/" will cause a local request for http://example.com/mirror/foo/bar to be internally converted into a proxy request to http://backend.example.com/bar. The ProxyPass directive is not supported in or sections. If you require a more flexible reverse-proxy configuration, see the R EWRITE RULE directive with the [P] flag. The following alternative syntax is possible; however, it can carry a performance penalty when present in very large numbers. The advantage of the below syntax is that it allows for dynamic control via the Balancer Manager (p. 824) interface: ProxyPass "/mirror/foo/" "http://backend.example.com/" ! If the first argument ends with a trailing /, the second argument should also end with a trailing /, and vice versa. Otherwise, the resulting requests to the backend may miss some needed slashes and do not deliver the expected results. The ! directive is useful in situations where you don’t want to reverse-proxy a subdirectory, e.g. 10.81. APACHE MODULE MOD PROXY 801 ProxyPass "http://backend.example.com/" ProxyPass "!" ProxyPass "/mirror/foo/i" "!" ProxyPass "/mirror/foo" "http://backend.example.com" will proxy all requests to /mirror/foo to backend.example.com except requests made to /mirror/foo/i. ! Ordering ProxyPass Directives The configured P ROXY PASS and P ROXY PASS M ATCH rules are checked in the order of configuration. The first rule that matches wins. So usually you should sort conflicting P ROXY PASS rules starting with the longest URLs first. Otherwise, later rules for longer URLS will be hidden by any earlier rule which uses a leading substring of the URL. Note that there is some relation with worker sharing. In contrast, only one P ROXY PASS directive can be placed in a L OCATION block, and the most specific location will take precedence. For the same reasons, exclusions must come before the general P ROXY PASS directives. ProxyPass key=value Parameters In Apache HTTP Server 2.1 and later, mod proxy supports pooled connections to a backend server. Connections created on demand can be retained in a pool for future use. Limits on the pool size and other settings can be coded on the P ROXY PASS directive using key=value parameters, described in the tables below. By default, mod proxy will allow and retain the maximum number of connections that could be used simultaneously by that web server child process. Use the max parameter to reduce the number from the default. Use the ttl parameter to set an optional time to live; connections which have been unused for at least ttl seconds will be closed. ttl can be used to avoid using a connection which is subject to closing because of the backend server’s keep-alive timeout. The pool of connections is maintained per web server child process, and max and other settings are not coordinated among all child processes, except when only one child process is allowed by configuration or MPM design. Example ProxyPass "/example" "http://backend.example.com" max=20 ttl=120 retry=300 BalancerMember parameters Parameter Default Description min 0 max 1...n Minimum number of connection pool entries, unrelated to the actual number of connections. This only needs to be modified from the default for special circumstances where heap memory associated with the backend connections should be preallocated or retained. Maximum number of connections that will be allowed to the backend server. The default for this limit is the number of threads per process in the active MPM. In the Prefork MPM, this is always 1; while with other MPMs, it is controlled by the T HREADS P ER C HILD directive. 802 CHAPTER 10. APACHE MODULES smax max acquire - connectiontimeout timeout disablereuse Off enablereuse On flushpackets off flushwait 10 iobuffersize 8192 Retained connection pool entries above this limit are freed during certain operations if they have been unused for longer than the time to live, controlled by the ttl parameter. If the connection pool entry has an associated connection, it will be closed. This only needs to be modified from the default for special circumstances where connection pool entries and any associated connections which have exceeded the time to live need to be freed or closed more aggressively. If set, this will be the maximum time to wait for a free connection in the connection pool, in milliseconds. If there are no free connections in the pool, the Apache httpd will return SERVER BUSY status to the client. Connect timeout in seconds. The number of seconds Apache httpd waits for the creation of a connection to the backend to complete. By adding a postfix of ms, the timeout can be also set in milliseconds. This parameter should be used when you want to force mod proxy to immediately close a connection to the backend after being used, and thus, disable its persistent connection and pool for that backend. This helps in various situations where a firewall between Apache httpd and the backend server (regardless of protocol) tends to silently drop connections or when backends themselves may be under round- robin DNS. To disable connection pooling reuse, set this property value to On. This is the inverse of ’disablereuse’ above, provided as a convenience for scheme handlers that require opt-in for connection reuse (such as MOD PROXY FCGI ). Determines whether the proxy module will auto-flush the output brigade after each "chunk" of data. ’off’ means that it will flush only when needed; ’on’ means after each chunk is sent; and ’auto’ means poll/wait for a period of time and flush if no input has been received for ’flushwait’ milliseconds. Currently, this is in effect only for AJP. The time to wait for additional input, in milliseconds, before flushing the output brigade if ’flushpackets’ is ’auto’. Adjusts the size of the internal scratchpad IO buffer. This allows you to override the P ROXY IOB UFFER S IZE for a specific worker. This must be at least 512 or set to 0 for the system default of 8192. 10.81. APACHE MODULE MOD PROXY keepalive Off lbset 0 ping 0 receivebuffersize 0 redirect - 803 This parameter should be used when you have a firewall between your Apache httpd and the backend server, which tends to drop inactive connections. This flag will tell the Operating System to send KEEP ALIVE messages on inactive connections and thus prevent the firewall from dropping the connection. To enable keepalive, set this property value to On. The frequency of initial and subsequent TCP keepalive probes depends on global OS settings, and may be as high as 2 hours. To be useful, the frequency configured in the OS must be smaller than the threshold used by the firewall. Sets the load balancer cluster set that the worker is a member of. The load balancer will try all members of a lower numbered lbset before trying higher numbered ones. Ping property tells the webserver to "test" the connection to the backend before forwarding the request. For negative values, the test is a simple socket check; for positive values, it’s a more functional check, dependent upon the protocol. For AJP, it causes MOD PROXY AJP to send a CPING request on the ajp13 connection (implemented on Tomcat 3.3.2+, 4.1.28+ and 5.0.13+). For HTTP, it causes MOD PROXY HTTP to send a 100-Continue to the backend (only valid for HTTP/1.1 - for non HTTP/1.1 backends, this property has no effect). In both cases, the parameter is the delay in seconds to wait for the reply. This feature has been added to avoid problems with hung and busy backends. This will increase the network traffic during the normal operation which could be an issue, but it will lower the traffic in case some of the cluster nodes are down or busy. By adding a postfix of ms, the delay can be also set in milliseconds. Adjusts the size of the explicit (TCP/IP) network buffer size for proxied connections. This allows you to override the P ROXY R ECEIVE B UFFER S IZE for a specific worker. This must be at least 512 or set to 0 for the system default. Redirection Route of the worker. This value is usually set dynamically to enable safe removal of the node from the cluster. If set, all requests without session id will be redirected to the BalancerMember that has route parameter equal to this value. 804 CHAPTER 10. APACHE MODULES retry 60 route - status - timeout P ROXY T IMEOUT ttl - Connection pool worker retry timeout in seconds. If the connection pool worker to the backend server is in the error state, Apache httpd will not forward any requests to that server until the timeout expires. This enables to shut down the backend server for maintenance and bring it back online later. A value of 0 means always retry workers in an error state with no timeout. Route of the worker when used inside load balancer. The route is a value appended to session id. Single letter value defining the initial status of this worker. D Worker is disabled and will not accept any requests; will be automatically retried. S Worker is administratively stopped; will not accept requests and will not be automatically retried I Worker is in ignore-errors mode and will always be considered available. H Worker is in hotstandby mode and will only be used if no other viable workers are available. E Worker is in an error state. N Worker is in drain mode and will only accept existing sticky sessions destined for itself and ignore all other requests. Status can be set (which is the default) by prepending with ’+’ or cleared by prepending with ’-’. Thus, a setting of ’SE’ sets this worker to Stopped and clears the in-error flag. Connection timeout in seconds. The number of seconds Apache httpd waits for data sent by / to the backend. Time to live for inactive connections and associated connection pool entries, in seconds. Once reaching this limit, a connection will not be used again; it will be closed at some later time. 10.81. APACHE MODULE MOD PROXY flusher flush 805 Name of the provider used by See the documentation of this module for more details. MOD PROXY FDPASS . If the Proxy directive scheme starts with the balancer:// (eg: balancer://cluster, any path information is ignored), then a virtual worker that does not really communicate with the backend server will be created. Instead, it is responsible for the management of several "real" workers. In that case, the special set of parameters can be added to this virtual worker. See MOD PROXY BALANCER for more information about how the balancer works. Balancer parameters 806 CHAPTER 10. APACHE MODULES Parameter Default Description lbmethod byrequests maxattempts nofailover One less than the number of workers, or 1 with a single worker. Off stickysession - stickysessionsep "." scolonpathdelim Off timeout 0 failonstatus - failontimeout Off nonce Balancer load-balance method. Select the load-balancing scheduler method to use. Either byrequests, to perform weighted request counting; bytraffic, to perform weighted traffic byte count balancing; or bybusyness, to perform pending request balancing. The default is byrequests. Maximum number of failover attempts before giving up. If set to On, the session will break if the worker is in error state or disabled. Set this value to On if backend servers do not support session replication. Balancer sticky session name. The value is usually set to something like JSESSIONID or PHPSESSIONID, and it depends on the backend application server that support sessions. If the backend application server uses different names for cookies and url encoded id (like servlet containers), use — to separate them. The first part is for the cookie; the second is for the path. Available in Apache HTTP Server 2.4.4 and later. Sets the separation symbol in the session cookie. Some backend application servers do not use the ’.’ as the symbol. For example, the Oracle Weblogic server uses ’!’. The correct symbol can be set using this option. The setting of ’Off’ signifies that no symbol is used. If set to On, the semi-colon character ’;’ will be used as an additional sticky session path delimiter/separator. This is mainly used to emulate mod jk’s behavior when dealing with paths such as JSESSIONID=6736bcf34;foo=aabfa Balancer timeout in seconds. If set, this will be the maximum time to wait for a free worker. The default is to not wait. A single or comma-separated list of HTTP status codes. If set, this will force the worker into error state when the backend returns any status code in the list. Worker recovery behaves the same as other worker errors. If set, an IO read timeout after a request is sent to the backend will force the worker into error state. Worker recovery behaves the same as other worker errors. Available in Apache HTTP Server 2.4.5 and later. The protective nonce used in the balancer-manager application page. The default is to use an automatically determined UUID-based nonce, to provide for further protection for the page. If set, then the nonce is set to that value. A setting of None disables all nonce checking. =⇒ Note In addition to the nonce, the balancer-manager page 10.81. APACHE MODULE MOD PROXY 807 A sample balancer setup: ProxyPass "/special-area" "http://special.example.com" smax=5 max=10 ProxyPass "/" "balancer://mycluster/" stickysession=JSESSIONID|jsessionid nofai BalancerMember ajp://1.2.3.4:8009 BalancerMember ajp://1.2.3.5:8009 loadfactor=20 # Less powerful server, don’t send as many requests there, BalancerMember ajp://1.2.3.6:8009 loadfactor=5 Setting up a hot-standby that will only be used if no other members are available: ProxyPass "/" "balancer://hotcluster/" BalancerMember ajp://1.2.3.4:8009 loadfactor=1 BalancerMember ajp://1.2.3.5:8009 loadfactor=2 # The server below is on hot standby BalancerMember ajp://1.2.3.6:8009 status=+H ProxySet lbmethod=bytraffic Additional ProxyPass Keywords Normally, mod proxy will canonicalise ProxyPassed URLs. But this may be incompatible with some backends, particularly those that make use of PATH INFO. The optional nocanon keyword suppresses this and passes the URL path "raw" to the backend. Note that this keyword may affect the security of your backend, as it removes the normal limited protection against URL-based attacks provided by the proxy. Normally, mod proxy will include the query string when generating the SCRIPT FILENAME environment variable. The optional noquery keyword (available in httpd 2.4.1 and later) prevents this. The optional interpolate keyword, in combination with P ROXY PASS I NTERPOLATE E NV, causes the ProxyPass to interpolate environment variables, using the syntax ${VARNAME}. Note that many of the standard CGI-derived environment variables will not exist when this interpolation happens, so you may still have to resort to MOD REWRITE for complex rules. Also note that interpolation is not supported within the scheme portion of a URL. Dynamic determination of the scheme can be accomplished with MOD REWRITE as in the following example. RewriteEngine On RewriteCond RewriteRule RewriteCond RewriteRule %{HTTPS} =off . - [E=protocol:http] %{HTTPS} =on . - [E=protocol:https] RewriteRule ˆ/mirror/foo/(.*) %{ENV:protocol}://backend.example.com/$1 [P] ProxyPassReverse "/mirror/foo/" "http://backend.example.com/" ProxyPassReverse "/mirror/foo/" "https://backend.example.com/" 808 CHAPTER 10. APACHE MODULES ProxyPassInherit Directive Description: Syntax: Default: Context: Status: Module: Compatibility: Inherit ProxyPass directives defined from the main server ProxyPassInherit On|Off ProxyPassInherit On server config, virtual host Extension mod proxy ProxyPassInherit is only available in Apache HTTP Server 2.4.5 and later. This directive will cause the current server/vhost to "inherit" P ROXY PASS directives defined in the main server. This can cause issues and inconsistent behavior if using the Balancer Manager for dynamic changes and so should be disabled if using that feature. The setting in the global server defines the default for all vhosts. Disabling ProxyPassInherit also disables BALANCER I NHERIT. ProxyPassInterpolateEnv Directive Description: Syntax: Default: Context: Status: Module: Enable Environment Variable interpolation in Reverse Proxy configurations ProxyPassInterpolateEnv On|Off ProxyPassInterpolateEnv Off server config, virtual host, directory Extension mod proxy This directive, together with the interpolate argument to P ROXY PASS, P ROXY PASS R EVERSE, P ROXY PASS R EVER SE C OOKIE D OMAIN , and P ROXY PASS R EVERSE C OOKIE PATH , enables reverse proxies to be dynamically configured using environment variables which may be set by another module such as MOD REWRITE. It affects the P ROX Y PASS , P ROXY PASS R EVERSE , P ROXY PASS R EVERSE C OOKIE D OMAIN , and P ROXY PASS R EVERSE C OOKIE PATH directives and causes them to substitute the value of an environment variable varname for the string ${varname} in configuration directives if the interpolate option is set. Keep this turned off (for server performance) unless you need it! ProxyPassMatch Directive Description: Syntax: Context: Status: Module: Maps remote servers into the local server URL-space using regular expressions ProxyPassMatch [regex] !|url [key=value [key=value ...]] server config, virtual host, directory Extension mod proxy This directive is equivalent to P ROXY PASS but makes use of regular expressions instead of simple prefix matching. The supplied regular expression is matched against the url, and if it matches, the server will substitute any parenthesized matches into the given string and use it as a new url. =⇒Note: This directive cannot be used within a context. Suppose the local server has address http://example.com/; then ProxyPassMatch "ˆ/(.*\.gif)$" "http://backend.example.com/$1" will cause a local request for http://example.com/foo/bar.gif to be internally converted into a proxy request to http://backend.example.com/foo/bar.gif. 10.81. APACHE MODULE MOD PROXY 809 =⇒Note The URL argument must be parsable as a URL before regexp substitutions (as well as after). This limits the matches you can use. For instance, if we had used ProxyPassMatch "ˆ(/.*\.gif)$" "http://backend.example.com:8000$1" in our previous example, it would fail with a syntax error at server startup. This is a bug (PR 46665 in the ASF bugzilla), and the workaround is to reformulate the match: ProxyPassMatch "ˆ/(.*\.gif)$" "http://backend.example.com:8000/$1" The ! directive is useful in situations where you don’t want to reverse-proxy a subdirectory. When used inside a section, the first argument is omitted and the regexp is obtained from the . If you require a more flexible reverse-proxy configuration, see the R EWRITE RULE directive with the [P] flag. =⇒Default Substitution When the URL parameter doesn’t use any backreferences into the regular expression, the original URL will be appended to the URL parameter. ! Security Warning Take care when constructing the target URL of the rule, considering the security impact from allowing the client influence over the set of URLs to which your server will act as a proxy. Ensure that the scheme and hostname part of the URL is either fixed or does not allow the client undue influence. ProxyPassReverse Directive Description: Syntax: Context: Status: Module: Adjusts the URL in HTTP response headers sent from a reverse proxied server ProxyPassReverse [path] url [interpolate] server config, virtual host, directory Extension mod proxy This directive lets Apache httpd adjust the URL in the Location, Content-Location and URI headers on HTTP redirect responses. This is essential when Apache httpd is used as a reverse proxy (or gateway) to avoid bypassing the reverse proxy because of HTTP redirects on the backend servers which stay behind the reverse proxy. Only the HTTP response headers specifically mentioned above will be rewritten. Apache httpd will not rewrite other response headers, nor will it by default rewrite URL references inside HTML pages. This means that if the proxied content contains absolute URL references, they will bypass the proxy. To rewrite HTML content to match the proxy, you must load and enable MOD PROXY HTML. path is the name of a local virtual path; url is a partial URL for the remote server. These parameters are used the same way as for the P ROXY PASS directive. For example, suppose the local server has address http://example.com/; then ProxyPass "/mirror/foo/" "http://backend.example.com/" ProxyPassReverse "/mirror/foo/" "http://backend.example.com/" ProxyPassReverseCookieDomain backend.example.com public.example.com ProxyPassReverseCookiePath "/" "/mirror/foo/" 810 CHAPTER 10. APACHE MODULES will not only cause a local request for the http://example.com/mirror/foo/bar to be internally converted into a proxy request to http://backend.example.com/bar (the functionality which ProxyPass provides here). It also takes care of redirects which the server backend.example.com sends when redirecting http://backend.example.com/bar to http://backend.example.com/quux . Apache httpd adjusts this to http://example.com/mirror/foo/quux before forwarding the HTTP redirect response to the client. Note that the hostname used for constructing the URL is chosen in respect to the setting of the U SE C ANONICAL NAME directive. Note that this P ROXY PASS R EVERSE directive can also be used in conjunction with the proxy feature (RewriteRule ... [P]) from MOD REWRITE because it doesn’t depend on a corresponding P ROXY PASS directive. The optional interpolate keyword, used together with P ROXY PASS I NTERPOLATE E NV, enables interpolation of environment variables specified using the format ${VARNAME}. Note that interpolation is not supported within the scheme portion of a URL. When used inside a section, the first argument is omitted and the local directory is obtained from the . The same occurs inside a section, but will probably not work as intended, as ProxyPassReverse will interpret the regexp literally as a path; if needed in this situation, specify the ProxyPassReverse outside the section or in a separate section. This directive is not supported in or sections. ProxyPassReverseCookieDomain Directive Description: Syntax: Context: Status: Module: Adjusts the Domain string in Set-Cookie headers from a reverse- proxied server ProxyPassReverseCookieDomain internal-domain public-domain [interpolate] server config, virtual host, directory Extension mod proxy Usage is basically similar to P ROXY PASS R EVERSE, but instead of rewriting headers that are a URL, this rewrites the domain string in Set-Cookie headers. ProxyPassReverseCookiePath Directive Description: Syntax: Context: Status: Module: Adjusts the Path string in Set-Cookie headers from a reverse- proxied server ProxyPassReverseCookiePath internal-path public-path [interpolate] server config, virtual host, directory Extension mod proxy Useful in conjunction with P ROXY PASS R EVERSE in situations where backend URL paths are mapped to public paths on the reverse proxy. This directive rewrites the path string in Set-Cookie headers. If the beginning of the cookie path matches internal-path, the cookie path will be replaced with public-path. In the example given with P ROXY PASS R EVERSE, the directive: ProxyPassReverseCookiePath "/" "/mirror/foo/" will rewrite a cookie with backend path / (or /example or, in fact, anything) to /mirror/foo/. 10.81. APACHE MODULE MOD PROXY 811 ProxyPreserveHost Directive Description: Syntax: Default: Context: Status: Module: Compatibility: Use incoming Host HTTP request header for proxy request ProxyPreserveHost On|Off ProxyPreserveHost Off server config, virtual host, directory Extension mod proxy Usable in directory context in 2.3.3 and later. When enabled, this option will pass the Host: line from the incoming request to the proxied host, instead of the hostname specified in the P ROXY PASS line. This option should normally be turned Off. It is mostly useful in special configurations like proxied mass name-based virtual hosting, where the original Host header needs to be evaluated by the backend server. ProxyReceiveBufferSize Directive Description: Syntax: Default: Context: Status: Module: Network buffer size for proxied HTTP and FTP connections ProxyReceiveBufferSize bytes ProxyReceiveBufferSize 0 server config, virtual host Extension mod proxy The P ROXY R ECEIVE B UFFER S IZE directive specifies an explicit (TCP/IP) network buffer size for proxied HTTP and FTP connections, for increased throughput. It has to be greater than 512 or set to 0 to indicate that the system’s default buffer size should be used. Example ProxyReceiveBufferSize 2048 ProxyRemote Directive Description: Syntax: Context: Status: Module: Remote proxy used to handle certain requests ProxyRemote match remote-server server config, virtual host Extension mod proxy This defines remote proxies to this proxy. match is either the name of a URL-scheme that the remote server supports, or a partial URL for which the remote server should be used, or * to indicate the server should be contacted for all requests. remote-server is a partial URL for the remote server. Syntax: remote-server = scheme://hostname[:port] scheme is effectively the protocol that should be used to communicate with the remote server; only http and https are supported by this module. When using https, the requests are forwarded through the remote proxy using the HTTP CONNECT method. 812 CHAPTER 10. APACHE MODULES Example ProxyRemote http://goodguys.example.com/ http://mirrorguys.example.com:8000 ProxyRemote * http://cleverproxy.localdomain ProxyRemote ftp http://ftpproxy.mydomain:8080 In the last example, the proxy will forward FTP requests, encapsulated as yet another HTTP proxy request, to another proxy which can handle them. This option also supports reverse proxy configuration; a backend webserver can be embedded within a virtualhost URL space even if that server is hidden by another forward proxy. ProxyRemoteMatch Directive Description: Syntax: Context: Status: Module: Remote proxy used to handle requests matched by regular expressions ProxyRemoteMatch regex remote-server server config, virtual host Extension mod proxy The P ROXY R EMOTE M ATCH is identical to the P ROXY R EMOTE directive, except that the first argument is a regular expression match against the requested URL. ProxyRequests Directive Description: Syntax: Default: Context: Status: Module: Enables forward (standard) proxy requests ProxyRequests On|Off ProxyRequests Off server config, virtual host Extension mod proxy This allows or prevents Apache httpd from functioning as a forward proxy server. (Setting ProxyRequests to Off does not disable use of the P ROXY PASS directive.) In a typical reverse proxy or gateway configuration, this option should be set to Off. In order to get the functionality of proxying HTTP or FTP sites, you need also MOD PROXY HTTP or MOD PROXY FTP (or both) present in the server. In order to get the functionality of (forward) proxying HTTPS sites, you need MOD PROXY CONNECT enabled in the server. ! Warning Do not enable proxying with P ROXY R EQUESTS until you have secured your server. Open proxy servers are dangerous both to your network and to the Internet at large. See also • Forward and Reverse Proxies/Gateways 10.81. APACHE MODULE MOD PROXY 813 ProxySet Directive Description: Syntax: Context: Status: Module: Set various Proxy balancer or member parameters ProxySet url key=value [key=value ...] directory Extension mod proxy This directive is used as an alternate method of setting any of the parameters available to Proxy balancers and workers normally done via the P ROXY PASS directive. If used within a container directive, the url argument is not required. As a side effect the respective balancer or worker gets created. This can be useful when doing reverse proxying via a R EWRITE RULE instead of a P ROXY PASS directive. BalancerMember http://www2.example.com:8080 loadfactor=1 BalancerMember http://www3.example.com:8080 loadfactor=2 ProxySet lbmethod=bytraffic ProxySet keepalive=On ProxySet balancer://foo lbmethod=bytraffic timeout=15 ProxySet ajp://backend:7001 timeout=15 ! Warning Keep in mind that the same parameter key can have a different meaning depending whether it is applied to a balancer or a worker, as shown by the two examples above regarding timeout. ProxySourceAddress Directive Description: Syntax: Context: Status: Module: Compatibility: Set local IP address for outgoing proxy connections ProxySourceAddress address server config, virtual host Extension mod proxy Available in version 2.3.9 and later This directive allows to set a specific local address to bind to when connecting to a backend server. ProxyStatus Directive Description: Syntax: Default: Context: Status: Module: Show Proxy LoadBalancer status in mod status ProxyStatus Off|On|Full ProxyStatus Off server config, virtual host Extension mod proxy 814 CHAPTER 10. APACHE MODULES This directive determines whether or not proxy loadbalancer status data is displayed via the MOD STATUS server-status page. =⇒Note Full is synonymous with On ProxyTimeout Directive Description: Syntax: Default: Context: Status: Module: Network timeout for proxied requests ProxyTimeout seconds Value of T I M E O U T server config, virtual host Extension mod proxy This directive allows a user to specifiy a timeout on proxy requests. This is useful when you have a slow/buggy appserver which hangs, and you would rather just return a timeout and fail gracefully instead of waiting however long it takes the server to return. ProxyVia Directive Description: Syntax: Default: Context: Status: Module: Information provided in the Via HTTP response header for proxied requests ProxyVia On|Off|Full|Block ProxyVia Off server config, virtual host Extension mod proxy This directive controls the use of the Via: HTTP header by the proxy. Its intended use is to control the flow of proxy requests along a chain of proxy servers. See RFC 261668 (HTTP/1.1), section 14.45 for an explanation of Via: header lines. • If set to Off, which is the default, no special processing is performed. If a request or reply contains a Via: header, it is passed through unchanged. • If set to On, each request and reply will get a Via: header line added for the current host. • If set to Full, each generated Via: header line will additionally have the Apache httpd server version shown as a Via: comment field. • If set to Block, every proxy request will have all its Via: header lines removed. No new Via: header will be generated. 68 http://www.ietf.org/rfc/rfc2616.txt 10.82. APACHE MODULE MOD PROXY AJP 10.82 815 Apache Module mod proxy ajp Description: Status: ModuleIdentifier: SourceFile: AJP support module for MOD PROXY Extension proxy ajp module mod proxy ajp.c Summary This module requires the service of MOD PROXY. version 1.3 (hereafter AJP13). It provides support for the Apache JServ Protocol Thus, in order to get the ability of handling AJP13 protocol, MOD PROXY and MOD PROXY AJP have to be present in the server. ! Warning Do not enable proxying until you have secured your server (p. 787) . Open proxy servers are dangerous both to your network and to the Internet at large. Directives This module provides no directives. See also • MOD PROXY • Environment Variable documentation (p. 92) Usage This module is used to reverse proxy to a backend application server (e.g. Apache Tomcat) using the AJP13 protocol. The usage is similar to an HTTP reverse proxy, but uses the ajp:// prefix: Simple Reverse Proxy ProxyPass "/app" "ajp://backend.example.com:8009/app" Balancers may also be used: Balancer Reverse Proxy BalancerMember ajp://app1.example.com:8009 loadfactor=1 BalancerMember ajp://app2.example.com:8009 loadfactor=2 ProxySet lbmethod=bytraffic ProxyPass "/app" "balancer://cluster/app" Note that usually no P ROXY PASS R EVERSE directive is necessary. The AJP request includes the original host header given to the proxy, and the application server can be expected to generate self-referential headers relative to this host, so no rewriting is necessary. The main exception is when the URL path on the proxy differs from that on the backend. In this case, a redirect header can be rewritten relative to the original host URL (not the backend ajp:// URL), for example: 816 CHAPTER 10. APACHE MODULES Rewriting Proxied Path ProxyPass "/apps/foo" "ajp://backend.example.com:8009/foo" ProxyPassReverse "/apps/foo" "http://www.example.com/foo" However, it is usually better to deploy the application on the backend server at the same path as the proxy rather than to take this approach. Environment Variables Environment variables whose names have the prefix AJP are forwarded to the origin server as AJP request attributes (with the AJP prefix removed from the name of the key). Overview of the protocol The AJP13 protocol is packet-oriented. A binary format was presumably chosen over the more readable plain text for reasons of performance. The web server communicates with the servlet container over TCP connections. To cut down on the expensive process of socket creation, the web server will attempt to maintain persistent TCP connections to the servlet container, and to reuse a connection for multiple request/response cycles. Once a connection is assigned to a particular request, it will not be used for any others until the request-handling cycle has terminated. In other words, requests are not multiplexed over connections. This makes for much simpler code at either end of the connection, although it does cause more connections to be open at once. Once the web server has opened a connection to the servlet container, the connection can be in one of the following states: • Idle No request is being handled over this connection. • Assigned The connection is handling a specific request. Once a connection is assigned to handle a particular request, the basic request information (e.g. HTTP headers, etc) is sent over the connection in a highly condensed form (e.g. common strings are encoded as integers). Details of that format are below in Request Packet Structure. If there is a body to the request (content-length > 0), that is sent in a separate packet immediately after. At this point, the servlet container is presumably ready to start processing the request. As it does so, it can send the following messages back to the web server: • SEND HEADERS Send a set of headers back to the browser. • SEND BODY CHUNK Send a chunk of body data back to the browser. • GET BODY CHUNK Get further data from the request if it hasn’t all been transferred yet. This is necessary because the packets have a fixed maximum size and arbitrary amounts of data can be included the body of a request (for uploaded files, for example). (Note: this is unrelated to HTTP chunked transfer). • END RESPONSE Finish the request-handling cycle. Each message is accompanied by a differently formatted packet of data. See Response Packet Structures below for details. 10.82. APACHE MODULE MOD PROXY AJP 817 Basic Packet Structure There is a bit of an XDR heritage to this protocol, but it differs in lots of ways (no 4 byte alignment, for example). AJP13 uses network byte order for all data types. There are four data types in the protocol: bytes, booleans, integers and strings. Byte A single byte. Boolean A single byte, 1 = true, 0 = false. Using other non-zero values as true (i.e. C-style) may work in some places, but it won’t in others. Integer A number in the range of 0 to 2ˆ16 (32768). Stored in 2 bytes with the high-order byte first. String A variable-sized string (length bounded by 2ˆ16). Encoded with the length packed into two bytes first, followed by the string (including the terminating ’\0’). Note that the encoded length doesnotinclude the trailing ’\0’ – it is likestrlen. This is a touch confusing on the Java side, which is littered with odd autoincrement statements to skip over these terminators. I believe the reason this was done was to allow the C code to be extra efficient when reading strings which the servlet container is sending back – with the terminating \0 character, the C code can pass around references into a single buffer, without copying. if the \0 was missing, the C code would have to copy things out in order to get its notion of a string. Packet Size According to much of the code, the max packet size is 8 * 1024 bytes (8K). The actual length of the packet is encoded in the header. Packet Headers Packets sent from the server to the container begin with 0x1234. Packets sent from the container to the server begin with AB (that’s the ASCII code for A followed by the ASCII code for B). After those first two bytes, there is an integer (encoded as above) with the length of the payload. Although this might suggest that the maximum payload could be as large as 2ˆ16, in fact, the code sets the maximum to be 8K. Packet Format (Server->Container) Byte Contents 0 0x12 1 0x34 2 Data Length (n) 3 Data 4...(n+3) Packet Format (Container->Server) Byte Contents 0 A 1 B 2 Data Length (n) 3 Data 4...(n+3) For most packets, the first byte of the payload encodes the type of message. The exception is for request body packets sent from the server to the container – they are sent with a standard packet header ( 0x1234 and then length of the packet), but without any prefix code after that. The web server can send the following messages to the servlet container: 818 CHAPTER 10. APACHE MODULES Code 2 7 8 Type of Packet Forward Request Shutdown Ping 10 CPing none Data Meaning Begin the request-processing cycle with the following data The web server asks the container to shut itself down. The web server asks the container to take control (secure login phase). The web server asks the container to respond quickly with a CPong. Size (2 bytes) and corresponding body data. To ensure some basic security, the container will only actually do the Shutdown if the request comes from the same machine on which it’s hosted. The first Data packet is send immediately after the Forward Request by the web server. The servlet container can send the following types of messages to the webserver: Code 3 Type of Packet Send Body Chunk 4 Send Headers 5 End Response 6 Get Body Chunk 9 CPong Reply Meaning Send a chunk of the body from the servlet container to the web server (and presumably, onto the browser). Send the response headers from the servlet container to the web server (and presumably, onto the browser). Marks the end of the response (and thus the request-handling cycle). Get further data from the request if it hasn’t all been transferred yet. The reply to a CPing request Each of the above messages has a different internal structure, detailed below. Request Packet Structure For messages from the server to the container of type Forward Request: AJP13_FORWARD_REQUEST := prefix_code (byte) 0x02 = JK_AJP13_FORWARD_REQUEST method (byte) protocol (string) req_uri (string) remote_addr (string) remote_host (string) server_name (string) server_port (integer) is_ssl (boolean) num_headers (integer) request_headers *(req_header_name req_header_value) attributes *(attribut_name attribute_value) request_terminator (byte) OxFF The request headers have the following structure: req_header_name := sc_req_header_name | (string) [see below for how this is parsed] sc_req_header_name := 0xA0xx (integer) req_header_value := (string) 10.82. APACHE MODULE MOD PROXY AJP 819 The attributes are optional and have the following structure: attribute_name := sc_a_name | (sc_a_req_attribute string) attribute_value := (string) Not that the all-important header is content-length, because it determines whether or not the container looks for another packet immediately. Detailed description of the elements of Forward Request Request prefix For all requests, this will be 2. See above for details on other Prefix codes. Method The HTTP method, encoded as a single byte: Command Name OPTIONS GET HEAD POST PUT DELETE TRACE PROPFIND PROPPATCH MKCOL COPY MOVE LOCK UNLOCK ACL REPORT VERSION-CONTROL CHECKIN CHECKOUT UNCHECKOUT SEARCH MKWORKSPACE UPDATE LABEL MERGE BASELINE CONTROL MKACTIVITY Code 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 Later version of ajp13, will transport additional methods, even if they are not in this list. 820 CHAPTER 10. APACHE MODULES protocol, req uri, remote addr, remote host, server name, server port, is ssl These are all fairly self-explanatory. Each of these is required, and will be sent for every request. Headers The structure of request headers is the following: First, the number of headers num headers is encoded. Then, a series of header name req header name / value req header value pairs follows. Common header names are encoded as integers, to save space. If the header name is not in the list of basic headers, it is encoded normally (as a string, with prefixed length). The list of common headers sc req header nameand their codes is as follows (all are case-sensitive): Name accept accept-charset accept-encoding accept-language authorization connection content-type content-length cookie cookie2 host pragma referer user-agent Code value 0xA001 0xA002 0xA003 0xA004 0xA005 0xA006 0xA007 0xA008 0xA009 0xA00A 0xA00B 0xA00C 0xA00D 0xA00E Code name SC REQ ACCEPT SC REQ ACCEPT CHARSET SC REQ ACCEPT ENCODING SC REQ ACCEPT LANGUAGE SC REQ AUTHORIZATION SC REQ CONNECTION SC REQ CONTENT TYPE SC REQ CONTENT LENGTH SC REQ COOKIE SC REQ COOKIE2 SC REQ HOST SC REQ PRAGMA SC REQ REFERER SC REQ USER AGENT The Java code that reads this grabs the first two-byte integer and if it sees an ’0xA0’ in the most significant byte, it uses the integer in the second byte as an index into an array of header names. If the first byte is not 0xA0, it assumes that the two-byte integer is the length of a string, which is then read in. This works on the assumption that no header names will have length greater than 0x9FFF (==0xA000 - 1), which is perfectly reasonable, though somewhat arbitrary. =⇒Note: The content-length header is extremely important. If it is present and non-zero, the container assumes that the request has a body (a POST request, for example), and immediately reads a separate packet off the input stream to get that body. Attributes The attributes prefixed with a ? (e.g. ?context) are all optional. For each, there is a single byte code to indicate the type of attribute, and then its value (string or integer). They can be sent in any order (though the C code always sends them in the order listed below). A special terminating code is sent to signal the end of the list of optional attributes. The list of byte codes is: 10.82. APACHE MODULE MOD PROXY AJP 821 Information ?context ?servlet path ?remote user ?auth type ?query string ?jvm route ?ssl cert ?ssl cipher ?ssl session ?req attribute Code Value 0x01 0x02 0x03 0x04 0x05 0x06 0x07 0x08 0x09 0x0A Type Of Value String String String String String String String String ?ssl key size are done 0x0B 0xFF Integer - Note Not currently implemented Not currently implemented Name (the name of the attribute follows) request terminator The context and servlet path are not currently set by the C code, and most of the Java code completely ignores whatever is sent over for those fields (and some of it will actually break if a string is sent along after one of those codes). I don’t know if this is a bug or an unimplemented feature or just vestigial code, but it’s missing from both sides of the connection. The remote user and auth type presumably refer to HTTP-level authentication, and communicate the remote user’s username and the type of authentication used to establish their identity (e.g. Basic, Digest). The query string, ssl cert, ssl cipher, and ssl session refer to the corresponding pieces of HTTP and HTTPS. The jvm route, is used to support sticky sessions – associating a user’s sesson with a particular Tomcat instance in the presence of multiple, load-balancing servers. Beyond this list of basic attributes, any number of other attributes can be sent via the req attribute code 0x0A. A pair of strings to represent the attribute name and value are sent immediately after each instance of that code. Environment values are passed in via this method. Finally, after all the attributes have been sent, the attribute terminator, 0xFF, is sent. This signals both the end of the list of attributes and also then end of the Request Packet. Response Packet Structure for messages which the container can send back to the server. 822 CHAPTER 10. APACHE MODULES AJP13_SEND_BODY_CHUNK := prefix_code 3 chunk_length (integer) chunk *(byte) chunk_terminator (byte) Ox00 AJP13_SEND_HEADERS := prefix_code 4 http_status_code (integer) http_status_msg (string) num_headers (integer) response_headers *(res_header_name header_value) res_header_name := sc_res_header_name | (string) [see below for how this is parsed] sc_res_header_name := 0xA0 (byte) header_value := (string) AJP13_END_RESPONSE := prefix_code 5 reuse (boolean) AJP13_GET_BODY_CHUNK := prefix_code 6 requested_length (integer) Details: Send Body Chunk The chunk is basically binary data, and is sent directly back to the browser. Send Headers The status code and message are the usual HTTP things (e.g. 200 and OK). The response header names are encoded the same way the request header names are. See header encoding above for details about how the codes are distinguished from the strings. The codes for common headers are: 10.82. APACHE MODULE MOD PROXY AJP Name Content-Type Content-Language Content-Length Date Last-Modified Location Set-Cookie Set-Cookie2 Servlet-Engine Status WWW-Authenticate 823 Code value 0xA001 0xA002 0xA003 0xA004 0xA005 0xA006 0xA007 0xA008 0xA009 0xA00A 0xA00B After the code or the string header name, the header value is immediately encoded. End Response Signals the end of this request-handling cycle. If the reuse flag is true (anything other than 0 in the actual C code), this TCP connection can now be used to handle new incoming requests. If reuse is false (==0), the connection should be closed. Get Body Chunk The container asks for more data from the request (If the body was too large to fit in the first packet sent over or when the request is chunked). The server will send a body packet back with an amount of data which is the minimum of the request length, the maximum send body size (8186 (8 Kbytes - 6)), and the number of bytes actually left to send from the request body. If there is no more data in the body (i.e. the servlet container is trying to read past the end of the body), the server will send back an empty packet, which is a body packet with a payload length of 0. (0x12,0x34,0x00,0x00) 824 CHAPTER 10. APACHE MODULES 10.83 Apache Module mod proxy balancer Description: Status: ModuleIdentifier: SourceFile: MOD PROXY extension for load balancing Extension proxy balancer module mod proxy balancer.c Summary This module requires the service of MOD PROXY and it provides load balancing for all the supported protocols. The most important ones are: • HTTP, using MOD PROXY HTTP • FTP, using MOD PROXY FTP • AJP13, using MOD PROXY AJP • WebSocket, using MOD PROXY WSTUNNEL The Load balancing scheduler algorithm is not provided by this module but from other ones such as: • MOD LBMETHOD BYREQUESTS • MOD LBMETHOD BYTRAFFIC • MOD LBMETHOD BYBUSYNESS • MOD LBMETHOD HEARTBEAT Thus, in order to get the ability of load balancing, MOD PROXY, MOD PROXY BALANCER and at least one of load balancing scheduler algorithm modules have to be present in the server. ! Warning Do not enable proxying until you have secured your server (p. 787) . Open proxy servers are dangerous both to your network and to the Internet at large. Directives This module provides no directives. See also • MOD PROXY Load balancer scheduler algorithm At present, there are 3 load balancer scheduler algorithms available for use: Request Counting, Weighted Traffic Counting and Pending Request Counting. These are controlled via the lbmethod value of the Balancer definition. See the P ROXY PASS directive for more information, especially regarding how to configure the Balancer and BalancerMembers. 10.83. APACHE MODULE MOD PROXY BALANCER 825 Load balancer stickyness The balancer supports stickyness. When a request is proxied to some back-end, then all following requests from the same user should be proxied to the same back-end. Many load balancers implement this feature via a table that maps client IP addresses to back-ends. This approach is transparent to clients and back-ends, but suffers from some problems: unequal load distribution if clients are themselves hidden behind proxies, stickyness errors when a client uses a dynamic IP address that changes during a session and loss of stickyness, if the mapping table overflows. The module MOD PROXY BALANCER implements stickyness on top of two alternative means: cookies and URL encoding. Providing the cookie can be either done by the back-end or by the Apache web server itself. The URL encoding is usually done on the back-end. Examples of a balancer configuration Before we dive into the technical details, here’s an example of how you might use MOD PROXY BALANCER to provide load balancing between two back-end servers: BalancerMember http://192.168.1.50:80 BalancerMember http://192.168.1.51:80 ProxyPass "/test" "balancer://mycluster" ProxyPassReverse "/test" "balancer://mycluster" Another example of how to provide load balancing with stickyness using MOD HEADERS, even if the back-end server does not set a suitable session cookie: Header add Set-Cookie "ROUTEID=.%{BALANCER_WORKER_ROUTE}e; path=/" env=BALANCER_ROUTE_CHANG BalancerMember http://192.168.1.50:80 route=1 BalancerMember http://192.168.1.51:80 route=2 ProxySet stickysession=ROUTEID ProxyPass "/test" "balancer://mycluster" ProxyPassReverse "/test" "balancer://mycluster" Exported Environment Variables At present there are 6 environment variables exported: BALANCER SESSION STICKY This is assigned the stickysession value used for the current request. It is the name of the cookie or request parameter used for sticky sessions BALANCER SESSION ROUTE This is assigned the route parsed from the current request. BALANCER NAME This is assigned the name of the balancer used for the current request. The value is something like balancer://foo. BALANCER WORKER NAME This is assigned the name of the worker used for the current request. The value is something like http://hostA:1234. BALANCER WORKER ROUTE This is assigned the route of the worker that will be used for the current request. 826 CHAPTER 10. APACHE MODULES BALANCER ROUTE CHANGED This is set to 1 if the session route does not match the worker route (BALANCER SESSION ROUTE != BALANCER WORKER ROUTE) or the session does not yet have an established route. This can be used to determine when/if the client needs to be sent an updated route when sticky sessions are used. Enabling Balancer Manager Support This module requires the service of MOD STATUS. Balancer manager enables dynamic update of balancer members. You can use balancer manager to change the balance factor of a particular member, or put it in the off line mode. Thus, in order to get the ability of load balancer management, MOD STATUS and MOD PROXY BALANCER have to be present in the server. To enable load balancer management for browsers from the example.com domain add this code to your httpd.conf configuration file SetHandler balancer-manager Require host example.com You can now access load balancer manager by using a Web browser to access the page http://your.server.name/balancer-manager. Please note that only Balancers defined outside of containers can be dynamically controlled by the Manager. Details on load balancer stickyness When using cookie based stickyness, you need to configure the name of the cookie that contains the information about which back-end to use. This is done via the stickysession attribute added to either P ROXY PASS or P ROXY S ET. The name of the cookie is case-sensitive. The balancer extracts the value of the cookie and looks for a member worker with route equal to that value. The route must also be set in either P ROXY PASS or P ROXY S ET. The cookie can either be set by the back-end, or as shown in the above example by the Apache web server itself. Some back-ends use a slightly different form of stickyness cookie, for instance Apache Tomcat. Tomcat adds the name of the Tomcat instance to the end of its session id cookie, separated with a dot (.) from the session id. Thus if the Apache web server finds a dot in the value of the stickyness cookie, it only uses the part behind the dot to search for the route. In order to let Tomcat know about its instance name, you need to set the attribute jvmRoute inside the Tomcat configuration file conf/server.xml to the value of the route of the worker that connects to the respective Tomcat. The name of the session cookie used by Tomcat (and more generally by Java web applications based on servlets) is JSESSIONID (upper case) but can be configured to something else. The second way of implementing stickyness is URL encoding. The web server searches for a query parameter in the URL of the request. The name of the parameter is specified again using stickysession. The value of the parameter is used to lookup a member worker with route equal to that value. Since it is not easy to extract and manipulate all URL links contained in responses, generally the work of adding the parameters to each link is done by the back-end generating the content. In some cases it might be feasible doing this via the web server using MOD SUBSTITUTE or MOD SED . This can have negative impact on performance though. The Java standards implement URL encoding slightly different. They use a path info appended to the URL using a semicolon (;) as the separator and add the session id behind. As in the cookie case, Apache Tomcat can include the configured jvmRoute in this path info. To let Apache find this sort of path info, you neet to set scolonpathdelim to On in P ROXY PASS or P ROXY S ET. Finally you can support cookies and URL encoding at the same time, by configuring the name of the cookie and the name of the URL parameter separated by a vertical bar (|) as in the following example: 10.83. APACHE MODULE MOD PROXY BALANCER 827 ProxyPass "/test" "balancer://mycluster" stickysession=JSESSIONID|jsessionid scolonpathdeli BalancerMember http://192.168.1.50:80 route=node1 BalancerMember http://192.168.1.51:80 route=node2 If the cookie and the request parameter both provide routing information for the same request, the information from the request parameter is used. Troubleshooting load balancer stickyness If you experience stickyness errors, e.g. users lose their application sessions and need to login again, you first want to check whether this is because the back-ends are sometimes unavailable or whether your configuration is wrong. To find out about possible stability problems with the back-ends, check your Apache error log for proxy error messages. To verify your configuration, first check, whether the stickyness is based on a cookie or on URL encoding. Next step would be logging the appropriate data in the access log by using an enhanced L OG F ORMAT. The following fields are useful: %{MYCOOKIE}C The value contained in the cookie with name MYCOOKIE. The name should be the same given in the stickysession attribute. %{Set-Cookie}o This logs any cookie set by the back-end. You can track, whether the back-end sets the session cookie you expect, and to which value it is set. %{BALANCER SESSION STICKY}e The name of the cookie or request parameter used to lookup the routing information. %{BALANCER SESSION ROUTE}e The route information found in the request. %{BALANCER WORKER ROUTE}e The route of the worker chosen. %{BALANCER ROUTE CHANGED}e Set to 1 if the route in the request is different from the route of the worker, i.e. the request couldn’t be handled sticky. Common reasons for loss of session are session timeouts, which are usually configurable on the back-end server. The balancer also logs detailed information about handling stickyness to the error log, if the log level is set to debug or higher. This is an easy way to troubleshoot stickyness problems, but the log volume might be to high for production servers under high load. 828 CHAPTER 10. APACHE MODULES 10.84 Apache Module mod proxy connect Description: Status: ModuleIdentifier: SourceFile: MOD PROXY extension for CONNECT request handling Extension proxy connect module mod proxy connect.c Summary This module requires the service of MOD PROXY. It provides support for the CONNECT HTTP method. This method is mainly used to tunnel SSL requests through proxy servers. Thus, in order to get the ability of handling CONNECT requests, MOD PROXY and MOD PROXY CONNECT have to be present in the server. CONNECT is also used when the server needs to send an HTTPS request through a forward proxy. In this case the server acts as a CONNECT client. This functionality is part of MOD PROXY and MOD PROXY CONNECT is not needed in this case. ! Warning Do not enable proxying until you have secured your server (p. 787) . Open proxy servers are dangerous both to your network and to the Internet at large. Directives • AllowCONNECT See also • MOD PROXY Request notes MOD PROXY CONNECT creates the following request notes for logging using the %{VARNAME}n format in L OG F OR MAT or E RROR L OG F ORMAT: proxy-source-port The local port used for the connection to the backend server. CONNECT method requests are controlled by the P ROXY block as any other HTTP request going through. SSL connections through a proxy may be filtered explicitely by specifying the target host and port, for instance: Require ip 192.168.0.0/16 10.84. APACHE MODULE MOD PROXY CONNECT 829 AllowCONNECT Directive Description: Syntax: Default: Context: Status: Module: Compatibility: Ports that are allowed to CONNECT through the proxy AllowCONNECT port[-port] [port[-port]] ... AllowCONNECT 443 563 server config, virtual host Extension mod proxy connect Moved from MOD PROXY in Apache 2.3.5. Port ranges available since Apache 2.3.7. The A LLOW CONNECT directive specifies a list of port numbers or ranges to which the proxy CONNECT method may connect. Today’s browsers use this method when a https connection is requested and proxy tunneling over HTTP is in effect. By default, only the default https port (443) and the default snews port (563) are enabled. Use the A LLOW CONNECT directive to override this default and allow connections to the listed ports only. 830 CHAPTER 10. APACHE MODULES 10.85 Apache Module mod proxy express Description: Status: ModuleIdentifier: SourceFile: Dynamic mass reverse proxy extension for MOD PROXY Extension proxy express module mod proxy express.c Summary This module creates dynamically configured mass reverse proxies, by mapping the Host: header of the HTTP request to a server name and backend URL stored in a DBM file. This allows for easy use of a huge number of reverse proxies with no configuration changes. It is much less feature-full than MOD PROXY BALANCER, which also provides dynamic growth, but is intended to handle much, much larger numbers of backends. It is ideally suited as a front-end HTTP switch. This module requires the service of MOD PROXY. ! Warning Do not enable proxying until you have secured your server (p. 787) . Open proxy servers are dangerous both to your network and to the Internet at large. =⇒Limitations • This module is not intended to replace the dynamic capability of MOD PROXY BALANCER . Instead, it is intended to be mostly a lightweight and fast alternative to using MOD REWRITE with R EWRITE M AP and the [P] flag for mapped reverse proxying. • It does not support regex or pattern matching at all. • It emulates: ServerName front.end.server ProxyPass "/" "back.end.server:port" ProxyPassReverse "/" "back.end.server:port" That is, the entire URL is appended to the mapped backend URL. This is in keeping with the intent of being a simple but fast reverse proxy switch. Directives • ProxyExpressDBMFile • ProxyExpressDBMType • ProxyExpressEnable See also • MOD PROXY 10.85. APACHE MODULE MOD PROXY EXPRESS 831 ProxyExpressDBMFile Directive Description: Syntax: Default: Context: Status: Module: Compatibility: Pathname to DBM file. ProxyExpressDBMFile None server config, virtual host Extension mod proxy express Available in Apache 2.3.13 and later The P ROXY E XPRESS DBMF ILE directive points to the location of the Express map DBM file. This file serves to map the incoming server name, obtained from the Host: header, to a backend URL. =⇒Note The file is constructed from a plain text file format using the httxt2dbm (p. 328) util- ity. ProxyExpress map file ## ##express-map.txt: ## www1.example.com http://192.168.211.2:8080 www2.example.com http://192.168.211.12:8088 www3.example.com http://192.168.212.10 Create DBM file httxt2dbm -i express-map.txt -o emap Configuration ProxyExpressEnable on ProxyExpressDBMFile emap ProxyExpressDBMType Directive Description: Syntax: Default: Context: Status: Module: Compatibility: DBM type of file. ProxyExpressDBMFile "default" server config, virtual host Extension mod proxy express Available in Apache 2.3.13 and later The P ROXY E XPRESS DBMT YPE directive controls the DBM type expected by the module. The default is the default DBM type created with httxt2dbm (p. 328) . Possible values are (not all may be available at run time): 832 CHAPTER 10. APACHE MODULES Value Description db gdbm ndbm sdbm default Berkeley DB files GDBM files NDBM files SDBM files (always available) default DBM type ProxyExpressEnable Directive Description: Syntax: Default: Context: Status: Module: Compatibility: Enable the module functionality. ProxyExpressEnable [on|off] off server config, virtual host Extension mod proxy express Available in Apache 2.3.13 and later The P ROXY E XPRESS E NABLE directive controls whether the module will be active. 10.86. APACHE MODULE MOD PROXY FCGI 10.86 833 Apache Module mod proxy fcgi Description: Status: ModuleIdentifier: SourceFile: Compatibility: FastCGI support module for MOD PROXY Extension proxy fcgi module mod proxy fcgi.c Available in version 2.3 and later Summary This module requires the service of MOD PROXY. It provides support for the FastCGI69 protocol. Thus, in order to get the ability of handling the FastCGI protocol, MOD PROXY and MOD PROXY FCGI have to be present in the server. Unlike mod fcgid70 and mod fastcgi71 , MOD PROXY FCGI has no provision for starting the application process; fcgistarter is provided (on some platforms) for that purpose. Alternatively, external launching or process management may be available in the FastCGI application framework in use. ! Warning Do not enable proxying until you have secured your server (p. 787) . Open proxy servers are dangerous both to your network and to the Internet at large. Directives This module provides no directives. See also • fcgistarter • MOD PROXY • MOD AUTHNZ FCGI Examples Remember, in order to make the following examples work, you have to enable MOD PROXY and MOD PROXY FCGI. Single application instance ProxyPass "/myapp/" "fcgi://localhost:4000/" MOD PROXY FCGI disables connection reuse by default, so after a request has been completed the connection will NOT be held open by that httpd child process and won’t be reused. If the FastCGI application is able to handle concurrent connections from httpd, you can opt-in to connection reuse as shown in the following example: Single application instance, connection reuse (2.4.11 and later) ProxyPass "/myapp/" "fcgi://localhost:4000/" enablereuse=on The following example passes the request URI as a filesystem path for the PHP-FPM daemon to run. The request URL is implicitly added to the 2nd parameter. The hostname and port following fcgi:// are where PHP-FPM is listening. Connection pooling is enabled. 69 http://www.fastcgi.com/ 70 http://httpd.apache.org/mod 71 http://www.fastcgi.com/ fcgid/ 834 CHAPTER 10. APACHE MODULES PHP-FPM ProxyPassMatch "ˆ/myapp/.*\.php(/.*)?$" "fcgi://localhost:9000/var/www/" enablereuse=on The following example passes the request URI as a filesystem path for the PHP-FPM daemon to run. In this case, PHP-FPM is listening on a unix domain socket (UDS). Requires 2.4.9 or later. With this syntax, the hostname and optional port following fcgi:// are ignored. PHP-FPM with UDS # UDS does not currently support connection reuse ProxyPassMatch "ˆ/(.*\.php(/.*)?)$" "unix:/var/run/php5-fpm.sock|fcgi://localhost/var/www/" The balanced gateway needs MOD PROXY BALANCER and at least one load balancer algorithm module, such as MOD LBMETHOD BYREQUESTS, in addition to the proxy modules listed above. MOD LBMETHOD BYREQUESTS is the default, and will be used for this example configuration. Balanced gateway to multiple application instances ProxyPass "/myapp/" "balancer://myappcluster/" BalancerMember "fcgi://localhost:4000" BalancerMember "fcgi://localhost:4001" You can also force a request to be handled as a reverse-proxy request, by creating a suitable Handler pass-through. The example configuration below will pass all requests for PHP scripts to the specified FastCGI server using reverse proxy. This feature is available in Apache HTTP Server 2.4.10 and later. For performance reasons, you will want to define a worker (p. 787) representing the same fcgi:// backend. The benefit of this form is that it allows the normal mapping of URI to filename to occur in the server, and the local filesystem result is passed to the backend. When FastCGI is configured this way, the server can calculate the most accurate PATH INFO. Proxy via Handler # Note: The only part that varies is /path/to/app.sock SetHandler "proxy:unix:/path/to/app.sock|fcgi://localhost/" # Define a matching worker. # The part that is matched to the SetHandler is the part that # follows the pipe. If you need to distinguish, "localhost; can # be anything unique. SetHandler "proxy:fcgi://localhost:9000" SetHandler "proxy:balancer://myappcluster/" 10.86. APACHE MODULE MOD PROXY FCGI 835 Environment Variables In addition to the configuration directives that control the behaviour of MOD PROXY, there are a number of environment variables that control the FCGI protocol provider: proxy-fcgi-pathinfo When configured via P ROXY PASS or P ROXY PASS M ATCH, MOD PROXY FCGI will not set the PATH INFO environment variable. This allows the backend FCGI server to correctly determine SCRIPT NAME and Script-URI and be compliant with RFC 3875 section 3.3. If instead you need MOD PROXY FCGI to generate a "best guess" for PATH INFO, set this env-var. This is a workaround for a bug in some FCGI implementations. This variable can be set to multiple values to tweak at how the best guess is chosen (In 2.4.11 and later only): first-dot PATH INFO is split from the slash following the first "." in the URL. last-dot PATH INFO is split from the slash following the last "." in the URL. full PATH INFO is calculated by an attempt to map the URL to the local filesystem. unescape PATH INFO is the path component of the URL, unescaped / decoded. any other value PATH INFO is the same as the path component of the URL. Originally, this was the only proxy-fcgi-pathinfo option. 836 CHAPTER 10. APACHE MODULES 10.87 Apache Module mod proxy fdpass Description: Status: ModuleIdentifier: SourceFile: Compatibility: fdpass external process support module for MOD PROXY Extension proxy fdpass module mod proxy fdpass.c Available for unix in version 2.3 and later Summary This module requires the service of MOD PROXY. It provides support for the passing the socket of the client to another process. mod proxy fdpass uses the ability of AF UNIX domain sockets to pass an open file descriptor72 to allow another process to finish handling a request. The module has a proxy fdpass flusher provider interface, which allows another module to optionally send the response headers, or even the start of the response body. The default flush provider disables keep-alive, and sends the response headers, letting the external process just send a response body. In order to use another provider, you have to set the flusher parameter in the P ROXY PASS directive. At this time the only data passed to the external process is the client socket. To receive a client socket, call recvfrom with an allocated struct cmsghdr73 . Future versions of this module may include more data after the client socket, but this is not implemented at this time. Directives This module provides no directives. See also • MOD PROXY 72 http://www.freebsd.org/cgi/man.cgi?query=recv 73 http://www.kernel.org/doc/man-pages/online/pages/man3/cmsg.3.html 10.88. APACHE MODULE MOD PROXY FTP 10.88 837 Apache Module mod proxy ftp Description: Status: ModuleIdentifier: SourceFile: FTP support module for MOD PROXY Extension proxy ftp module mod proxy ftp.c Summary This module requires the service of MOD PROXY. It provides support for the proxying FTP sites. Note that FTP support is currently limited to the GET method. Thus, in order to get the ability of handling FTP proxy requests, MOD PROXY and MOD PROXY FTP have to be present in the server. ! Warning Do not enable proxying until you have secured your server (p. 787) . Open proxy servers are dangerous both to your network and to the Internet at large. Directives • ProxyFtpDirCharset • ProxyFtpEscapeWildcards • ProxyFtpListOnWildcard See also • MOD PROXY Why doesn’t file type xxx download via FTP? You probably don’t have that particular file type defined as application/octet-stream in your proxy’s mime.types configuration file. A useful line can be application/octet-stream bin dms lha lzh exe class tgz taz Alternatively you may prefer to default everything to binary: ForceType application/octet-stream How can I force an FTP ASCII download of File xxx? In the rare situation where you must download a specific file using the FTP ASCII transfer method (while the default transfer is in binary mode), you can override MOD PROXY’s default by suffixing the request with ;type=a to force an ASCII transfer. (FTP Directory listings are always executed in ASCII mode, however.) 838 CHAPTER 10. APACHE MODULES How can I do FTP upload? Currently, only GET is supported for FTP in mod proxy. You can of course use HTTP upload (POST or PUT) through an Apache proxy. How can I access FTP files outside of my home directory? An FTP URI is interpreted relative to the home directory of the user who is logging in. Alas, to reach higher directory levels you cannot use /../, as the dots are interpreted by the browser and not actually sent to the FTP server. To address this problem, the so called Squid %2f hack was implemented in the Apache FTP proxy; it is a solution which is also used by other popular proxy servers like the Squid Proxy Cache74 . By prepending /%2f to the path of your request, you can make such a proxy change the FTP starting directory to / (instead of the home directory). For example, to retrieve the file /etc/motd, you would use the URL: ftp://user@host/%2f/etc/motd How can I hide the FTP cleartext password in my browser’s URL line? To log in to an FTP server by username and password, Apache uses different strategies. In absence of a user name and password in the URL altogether, Apache sends an anonymous login to the FTP server, i.e., user: anonymous password: apache proxy@ This works for all popular FTP servers which are configured for anonymous access. For a personal login with a specific username, you can embed the user name into the URL, like in: ftp://username@host/myfile If the FTP server asks for a password when given this username (which it should), then Apache will reply with a 401 (Authorization required) response, which causes the Browser to pop up the username/password dialog. Upon entering the password, the connection attempt is retried, and if successful, the requested resource is presented. The advantage of this procedure is that your browser does not display the password in cleartext (which it would if you had used ftp://username:password@host/myfile in the first place). =⇒Note The password which is transmitted in such a way is not encrypted on its way. It travels between your browser and the Apache proxy server in a base64-encoded cleartext string, and between the Apache proxy and the FTP server as plaintext. You should therefore think twice before accessing your FTP server via HTTP (or before accessing your personal files via FTP at all!) When using insecure channels, an eavesdropper might intercept your password on its way. 74 http://www.squid-cache.org/ 10.88. APACHE MODULE MOD PROXY FTP 839 Why do I get a file listing when I expected a file to be downloaded? In order to allow both browsing the directories on an FTP server and downloading files, Apache looks at the request URL. If it looks like a directory, or contains wildcard characters ("*?[{˜"), then it guesses that a listing is wanted instead of a download. You can disable the special handling of names with wildcard characters. See the P ROXY F TP L IST O N W ILDCARD directive. ProxyFtpDirCharset Directive Description: Syntax: Default: Context: Status: Module: Compatibility: Define the character set for proxied FTP listings ProxyFtpDirCharset character set ProxyFtpDirCharset ISO-8859-1 server config, virtual host, directory Extension mod proxy ftp Moved from MOD PROXY in Apache 2.3.5. The P ROXY F TP D IR C HARSET directive defines the character set to be set for FTP directory listings in HTML generated by MOD PROXY FTP. ProxyFtpEscapeWildcards Directive Description: Syntax: Default: Context: Status: Module: Compatibility: Whether wildcards in requested filenames are escaped when sent to the FTP server ProxyFtpEscapeWildcards [on|off] on server config, virtual host, directory Extension mod proxy ftp Available in Apache 2.3.3 and later The P ROXY F TP E SCAPE W ILDCARDS directive controls whether wildcard characters ("*?[{˜") in requested filenames are escaped with backslash before sending them to the FTP server. That is the default behavior, but many FTP servers don’t know about the escaping and try to serve the literal filenames they were sent, including the backslashes in the names. Set to "off" to allow downloading files with wildcards in their names from FTP servers that don’t understand wildcard escaping. ProxyFtpListOnWildcard Directive Description: Syntax: Default: Context: Status: Module: Compatibility: Whether wildcards in requested filenames trigger a file listing ProxyFtpListOnWildcard [on|off] on server config, virtual host, directory Extension mod proxy ftp Available in Apache 2.3.3 and later The P ROXY F TP L IST O N W ILDCARD directive controls whether wildcard characters ("*?[{˜") in requested filenames cause MOD PROXY FTP to return a listing of files instead of downloading a file. By default (value on), they do. Set to "off" to allow downloading files even if they have wildcard characters in their names. 840 10.89 CHAPTER 10. APACHE MODULES Apache Module mod proxy hcheck Description: Status: ModuleIdentifier: SourceFile: Compatibility: Dynamic health check of Balancer members (workers) for MOD PROXY Extension proxy hcheck module mod proxy hcheck.c Available in Apache 2.4.21 and later Summary This module provides for dynamic health checking of balancer members (workers). This can be enabled on a workerby-worker basis. The health check is done independently of the actual reverse proxy requests. This module requires the service of MOD WATCHDOG. 10.89. APACHE MODULE MOD PROXY HCHECK 841 =⇒Parameters The health check mechanism is enabled via the use of additional BalancerMember parameters, which are configured in the standard way via P ROXY PASS: A new BalancerMember status state (flag) is defined via this module: "C". When the worker is taken offline due to failures as determined by the health check module, this flag is set, and can be seen (and modified) via the balancer-manager. Parameter Default Description hcmethod None No dynamic performed. Method None health check Choices are: TCP OPTIONS HEAD GET hcpasses 1 hcfails 1 hcinterval 30 hcuri hctemplate hcexpr *: Unless hcexpr is used, a 2xx or 3xx HTTP status will be interpreted as passing the health check Number of successful health check tests before worker is reenabled Number of failed health check tests before worker is disabled Period of health checks in seconds (e.g. performed every 30 seconds) Additional URI to be appended to the worker URL for the health check. Name of template, created via P ROXY HCT EMPLATE to use for setting health check parameters for this worker Name of expression, created via P ROXY HCE XPR, used to check response headers for health. If not used, 2xx thru 3xx status codes imply success Description No dynamic health checking done Check that a socket to the backend can be created: e.g. "are you up" Send an HTTP OPTIONS request to the backend Send an HTTP HEAD request to the backend Send an HTTP GET request to the backend Note * * * 842 CHAPTER 10. APACHE MODULES Directives • ProxyHCExpr • ProxyHCTemplate • ProxyHCTPsize See also • MOD PROXY Usage examples The following example shows how one might configured health checking for various backend servers: ProxyHCExpr ok234 {%{REQUEST_STATUS} =˜ /ˆ[234]/} ProxyHCExpr gdown {%{REQUEST_STATUS} =˜ /ˆ[5]/} ProxyHCExpr in_maint {hc(’body’) !˜ /Under maintenance/} BalancerMember http://www.example.com/ hcmethod=GET hcexpr=in_maint hcuri=/status.php BalancerMember http://www2.example.com/ hcmethod=HEAD hcexpr=ok234 hcinterval=10 BalancerMember http://www3.example.com/ hcmethod=TCP hcinterval=5 hcpasses=2 hcfails=3 BalancerMember http://www4.example.com/ ProxyPass "/" "balancer://foo" ProxyPassReverse "/" "balancer://foo" In this scenario, http://www.example.com/ is health checked by sending a GET /status.php request to that server and seeing that the returned page does not include the string Under maintenance. If it does, that server is put in health-check fail mode, and disabled. This dynamic check is performed every 30 seconds, which is the default. http://www2.example.com/ is checked by sending a simple HEAD request every 10 seconds and making sure that the response status is 2xx, 3xx or 4xx. http://www3.example.com/ is checked every 5 seconds by simply ensuring that the socket to that server is up. If the backend is marked as "down" and it passes 2 health check, it will be re-enabled and added back into the load balancer. It takes 3 back-to-back health check failures to disable the server and move it out of rotation. Finally, http://www4.example.com/ is not dynamically checked at all. ProxyHCExpr Directive Description: Syntax: Context: Status: Module: Creates a named condition expression to use to determine health of the backend based on its response. ProxyHCExpr name {ap expr expression} server config, virtual host Extension mod proxy hcheck The P ROXY HCE XPR directive allows for creating a named condition expression that checks the response headers of the backend server to determine its health. This named condition can then be assigned to balancer members via the hcexpr parameter 10.89. APACHE MODULE MOD PROXY HCHECK 843 ProxyHCExpr: Allow for 2xx/3xx/4xx as passing ProxyHCExpr ok234 {%{REQUEST_STATUS} =˜ /ˆ[234]/} ProxyPass "/apps" "http://backend.example.com/" hcexpr=ok234 =⇒normal The expression (p. 99) can use curly-parens ("{}") as quoting deliminators in addition to quotes. If using a health check method (eg: GET) which results in a response body, that body itself can be checked via ap expr using the hc() expression function, which is unique to this module. In the following example, we send the backend a GET request and if the response body contains the phrase Under maintenance, we want to disable the backend. ProxyHCExpr: Checking response body ProxyHCExpr in_maint {hc(’body’) !˜ /Under maintenance/} ProxyPass "/apps" "http://backend.example.com/" hcexpr=in_maint hcmethod=get hcuri=/stat NOTE: Since response body can quite large, it is best if used against specific status pages. ProxyHCTemplate Directive Description: Syntax: Context: Status: Module: Creates a named template for setting various health check parameters ProxyHCTemplate name parameter=setting <...> server config, virtual host Extension mod proxy hcheck The P ROXY HCT EMPLATE directive allows for creating a named set (template) of health check parameters that can then be assigned to balancer members via the hctemplate parameter ProxyHCTemplate ProxyHCTemplate tcp5 hcmethod=tcp hcinterval=5 ProxyPass "/apps" "http://backend.example.com/" hctemplate=tcp5 ProxyHCTPsize Directive Description: Syntax: Context: Status: Module: Sets the size of the threadpool used for the health check workers. ProxyHCTPsize server config, virtual host Extension mod proxy hcheck If Apache httpd and APR are built with thread support, the health check module will offload the work of the actual checking to a threadpool associated with the Watchdog process, allowing for parallel checks. The P ROXY HCTP SIZE directive determines the size of this threadpool. If set to 0, no threadpool is used at all, resulting in serialized health checks. The default size is 16. ProxyHCTPsize ProxyHCTPsize 32 844 CHAPTER 10. APACHE MODULES 10.90 Apache Module mod proxy html Description: Status: ModuleIdentifier: SourceFile: Compatibility: Rewrite HTML links in to ensure they are addressable from Clients’ networks in a proxy context. Base proxy html module mod proxy html.c Version 2.4 and later. Available as a third-party module for earlier 2.x versions Summary This module provides an output filter to rewrite HTML links in a proxy situation, to ensure that links work for users outside the proxy. It serves the same purpose as Apache’s ProxyPassReverse directive does for HTTP headers, and is an essential component of a reverse proxy. For example, if a company has an application server at appserver.example.com that is only visible from within the company’s internal network, and a public webserver www.example.com, they may wish to provide a gateway to the application server at http://www.example.com/appserver/. When the application server links to itself, those links need to be rewritten to work through the gateway. mod proxy html serves to rewrite foobar to foobar making it accessible from outside. mod proxy html was originally developed at Webing, whose extensive documentation75 may be useful to users. Directives • ProxyHTMLBufSize • ProxyHTMLCharsetOut • ProxyHTMLDocType • ProxyHTMLEnable • ProxyHTMLEvents • ProxyHTMLExtended • ProxyHTMLFixups • ProxyHTMLInterp • ProxyHTMLLinks • ProxyHTMLMeta • ProxyHTMLStripComments • ProxyHTMLURLMap ProxyHTMLBufSize Directive Description: Syntax: Context: Status: Module: Compatibility: Sets the buffer size increment for buffering inline scripts and stylesheets. ProxyHTMLBufSize bytes server config, virtual host, directory Base mod proxy html Version 2.4 and later; available as a third-party for earlier 2.x versions 75 http://apache.webthing.com/mod proxy html/ 10.90. APACHE MODULE MOD PROXY HTML 845 In order to parse non-HTML content (stylesheets and scripts) embedded in HTML documents, mod proxy html has to read the entire script or stylesheet into a buffer. This buffer will be expanded as necessary to hold the largest script or stylesheet in a page, in increments of bytes as set by this directive. The default is 8192, and will work well for almost all pages. However, if you know you’re proxying pages containing stylesheets and/or scripts bigger than 8K (that is, for a single script or stylesheet, NOT in total), it will be more efficient to set a larger buffer size and avoid the need to resize the buffer dynamically during a request. ProxyHTMLCharsetOut Directive Description: Syntax: Context: Status: Module: Compatibility: Specify a charset for mod proxy html output. ProxyHTMLCharsetOut Charset | * server config, virtual host, directory Base mod proxy html Version 2.4 and later; available as a third-party for earlier 2.x versions This selects an encoding for mod proxy html output. It should not normally be used, as any change from the default UTF-8 (Unicode - as used internally by libxml2) will impose an additional processing overhead. The special token ProxyHTMLCharsetOut * will generate output using the same encoding as the input. Note that this relies on MOD XML 2 ENC being loaded. ProxyHTMLDocType Directive Description: Syntax: Default: Context: Status: Module: Compatibility: Sets an HTML or XHTML document type declaration. ProxyHTMLDocType HTML|XHTML [Legacy] OR ProxyHTMLDocType fpi [SGML|XML] OR ProxyHTMLDocType html5 OR ProxyHTMLDocType auto ProxyHTMLDocType auto (2.5/trunk versions); no FPI (2.4.x) server config, virtual host, directory Base mod proxy html Version 2.4 and later; available as a third-party for earlier 2.x versions In the first form, documents will be declared as HTML 4.01 or XHTML 1.0 according to the option selected. This option also determines whether HTML or XHTML syntax is used for output. Note that the format of the documents coming from the backend server is immaterial: the parser will deal with it automatically. If the optional second argument is set to "Legacy", documents will be declared "Transitional", an option that may be necessary if you are proxying pre-1998 content or working with defective authoring/publishing tools. In the second form, it will insert your own FPI. The optional second argument determines whether SGML/HTML or XML/XHTML syntax will be used. The third form declares documents as HTML 5. The fourth form is new in HTTPD trunk and not yet available in released versions, and uses libxml2’s HTML parser to detect the doctype. If the first form is used, mod proxy html will also clean up the HTML to the specified standard. It cannot fix every error, but it will strip out bogus elements and attributes. It will also optionally log other errors at L OG L EVEL Debug. 846 CHAPTER 10. APACHE MODULES ProxyHTMLEnable Directive Description: Syntax: Default: Context: Status: Module: Compatibility: Turns the proxy html filter on or off. ProxyHTMLEnable On|Off ProxyHTMLEnable Off server config, virtual host, directory Base mod proxy html Version 2.4 and later; available as a third-party module for earlier 2.x versions. A simple switch to enable or disable the proxy html filter. If MOD XML 2 ENC is loaded it will also automatically set up internationalisation support. Note that the proxy html filter will only act on HTML data (Content-Type text/html or application/xhtml+xml) and when the data are proxied. You can override this (at your own risk) by setting the PROXY HTML FORCE environment variable. ProxyHTMLEvents Directive Description: Syntax: Context: Status: Module: Compatibility: Specify attributes to treat as scripting events. ProxyHTMLEvents attribute [attribute ...] server config, virtual host, directory Base mod proxy html Version 2.4 and later; available as a third-party for earlier 2.x versions Specifies one or more attributes to treat as scripting events and apply P ROXY HTMLURLM APs to where enabled. You can specify any number of attributes in one or more ProxyHTMLEvents directives. Normally you’ll set this globally. If you set ProxyHTMLEvents in more than one scope so that one overrides the other, you’ll need to specify a complete set in each of those scopes. A default configuration is supplied in proxy-html.conf and defines the events in standard HTML 4 and XHTML 1. ProxyHTMLExtended Directive Description: Syntax: Default: Context: Status: Module: Compatibility: Determines whether to fix links in inline scripts, stylesheets, and scripting events. ProxyHTMLExtended On|Off ProxyHTMLExtended Off server config, virtual host, directory Base mod proxy html Version 2.4 and later; available as a third-party for earlier 2.x versions Set to Off, HTML links are rewritten according to the P ROXY HTMLURLM AP directives, but links appearing in Javascript and CSS are ignored. Set to On, all scripting events (as determined by P ROXY HTMLE VENTS) and embedded scripts or stylesheets are also processed by the P ROXY HTMLURLM AP rules, according to the flags set for each rule. Since this requires more parsing, performance will be best if you only enable it when strictly necessary. You’ll also need to take care over patterns matched, since the parser has no knowledge of what is a URL within an embedded script or stylesheet. In particular, extended matching of / is likely to lead to false matches. 10.90. APACHE MODULE MOD PROXY HTML 847 ProxyHTMLFixups Directive Description: Syntax: Context: Status: Module: Compatibility: Fixes for simple HTML errors. ProxyHTMLFixups [lowercase] [dospath] [reset] server config, virtual host, directory Base mod proxy html Version 2.4 and later; available as a third-party for earlier 2.x versions This directive takes one to three arguments as follows: • lowercase Urls are rewritten to lowercase • dospath Backslashes in URLs are rewritten to forward slashes. • reset Unset any options set at a higher level in the configuration. Take care when using these. The fixes will correct certain authoring mistakes, but risk also erroneously fixing links that were correct to start with. Only use them if you know you have a broken backend server. ProxyHTMLInterp Directive Description: Syntax: Default: Context: Status: Module: Compatibility: Enables per-request interpolation of P ROXY HTMLURLM AP rules. ProxyHTMLInterp On|Off ProxyHTMLInterp Off server config, virtual host, directory Base mod proxy html Version 2.4 and later; available as a third-party for earlier 2.x versions This enables per-request interpolation in P ROXY HTMLURLM AP to- and from- patterns. If interpolation is not enabled, all rules are pre-compiled at startup. With interpolation, they must be re-compiled for every request, which implies an extra processing overhead. It should therefore be enabled only when necessary. ProxyHTMLLinks Directive Description: Syntax: Context: Status: Module: Compatibility: Specify HTML elements that have URL attributes to be rewritten. ProxyHTMLLinks element attribute [attribute2 ...] server config, virtual host, directory Base mod proxy html Version 2.4 and later; available as a third-party for earlier 2.x versions Specifies elements that have URL attributes that should be rewritten using standard P ROXY HTMLURLM APs. You will need one ProxyHTMLLinks directive per element, but it can have any number of attributes. Normally you’ll set this globally. If you set ProxyHTMLLinks in more than one scope so that one overrides the other, you’ll need to specify a complete set in each of those scopes. A default configuration is supplied in proxy-html.conf and defines the HTML links for standard HTML 4 and XHTML 1. 848 CHAPTER 10. APACHE MODULES ProxyHTMLMeta Directive Description: Syntax: Default: Context: Status: Module: Compatibility: Turns on or off extra pre-parsing of metadata in HTML sections. ProxyHTMLMeta On|Off ProxyHTMLMeta Off server config, virtual host, directory Base mod proxy html Version 2.4 and later; available as a third-party module for earlier 2.x versions. This turns on or off pre-parsing of metadata in HTML sections. If not required, turning ProxyHTMLMeta Off will give a small performance boost by skipping this parse step. However, it is sometimes necessary for internationalisation to work correctly. ProxyHTMLMeta has two effects. Firstly and most importantly it enables detection of character encodings declared in the form or, in the case of an XHTML document, an XML declaration. It is NOT required if the charset is declared in a real HTTP header (which is always preferable) from the backend server, nor if the document is utf-8 (unicode) or a subset such as ASCII. You may also be able to dispense with it where documents use a default declared using XML 2E NC D EFAULT , but that risks propagating an incorrect declaration. A P ROXY HTMLC HARSET O UT can remove that risk, but is likely to be a bigger processing overhead than enabling ProxyHTMLMeta. The other effect of enabling ProxyHTMLMeta is to parse all declarations and convert them to real HTTP headers, in keeping with the original purpose of this form of the HTML element. ProxyHTMLStripComments Directive Description: Syntax: Default: Context: Status: Module: Compatibility: Determines whether to strip HTML comments. ProxyHTMLStripComments On|Off ProxyHTMLStripComments Off server config, virtual host, directory Base mod proxy html Version 2.4 and later; available as a third-party for earlier 2.x versions This directive will cause mod proxy html to strip HTML comments. Note that this will also kill off any scripts or styles embedded in comments (a bogosity introduced in 1995/6 with Netscape 2 for the benefit of then-older browsers, but still in use today). It may also interfere with comment-based processors such as SSI or ESI: be sure to run any of those before mod proxy html in the filter chain if stripping comments! ProxyHTMLURLMap Directive Description: Syntax: Context: Status: Module: Compatibility: Defines a rule to rewrite HTML links ProxyHTMLURLMap from-pattern to-pattern [flags] [cond] server config, virtual host, directory Base mod proxy html Version 2.4 and later; available as a third-party module for earlier 2.x versions. This is the key directive for rewriting HTML links. When parsing a document, whenever a link target matches frompattern, the matching portion will be rewritten to to-pattern, as modified by any flags supplied and by the P ROXYHTMLE XTENDED directive. 10.90. APACHE MODULE MOD PROXY HTML 849 The optional third argument may define any of the following Flags. Flags are case-sensitive. h Ignore HTML links (pass through unchanged) e Ignore scripting events (pass through unchanged) c Pass embedded script and style sections through untouched. L Last-match. If this rule matches, no more rules are applied (note that this happens automatically for HTML links). l Opposite to L. Overrides the one-change-only default behaviour with HTML links. R Use Regular Expression matching-and-replace. from-pattern is a regexp, and to-pattern a replacement string that may be based on the regexp. Regexp memory is supported: you can use brackets () in the from-pattern and retrieve the matches with $1 to $9 in the to-pattern. If R is not set, it will use string-literal search-and-replace. The logic is starts-with in HTML links, but contains in scripting events and embedded script and style sections. x Use POSIX extended Regular Expressions. Only applicable with R. i Case-insensitive matching. Only applicable with R. n Disable regexp memory (for speed). Only applicable with R. s Line-based regexp matching. Only applicable with R. ˆ Match at start only. This applies only to string matching (not regexps) and is irrelevant to HTML links. $ Match at end only. This applies only to string matching (not regexps) and is irrelevant to HTML links. V Interpolate environment variables in to-pattern. A string of the form ${varname|default} will be replaced by the value of environment variable varname. If that is unset, it is replaced by default. The |default is optional. NOTE: interpolation will only be enabled if P ROXY HTMLI NTERP is On. v Interpolate environment variables in from-pattern. Patterns supported are as above. NOTE: interpolation will only be enabled if P ROXY HTMLI NTERP is On. The optional fourth cond argument defines a condition that will be evaluated per Request, provided P ROXY HTMLI N TERP is On. If the condition evaluates FALSE the map will not be applied in this request. If TRUE, or if no condition is defined, the map is applied. A cond is evaluated by the Expression Parser (p. 99) . In addition, the simpler syntax of conditions in mod proxy html 3.x for HTTPD 2.0 and 2.2 is also supported. 850 CHAPTER 10. APACHE MODULES 10.91 Apache Module mod proxy http Description: Status: ModuleIdentifier: SourceFile: HTTP support module for MOD PROXY Extension proxy http module mod proxy http.c Summary This module requires the service of MOD PROXY. It provides the features used for proxying HTTP and HTTPS requests. MOD PROXY HTTP supports HTTP/0.9, HTTP/1.0 and HTTP/1.1. It does not provide any caching abilities. If you want to set up a caching proxy, you might want to use the additional service of the MOD CACHE module. Thus, in order to get the ability of handling HTTP proxy requests, MOD PROXY and MOD PROXY HTTP have to be present in the server. ! Warning Do not enable proxying until you have secured your server (p. 787) . Open proxy servers are dangerous both to your network and to the Internet at large. Directives This module provides no directives. See also • MOD PROXY • MOD PROXY CONNECT Environment Variables In addition to the configuration directives that control the behaviour of MOD PROXY, there are a number of environment variables that control the HTTP protocol provider. Environment variables below that don’t specify specific values are enabled when set to any value. proxy-sendextracrlf Causes proxy to send an extra CR-LF newline on the end of a request. This is a workaround for a bug in some browsers. force-proxy-request-1.0 Forces the proxy to send requests to the backend as HTTP/1.0 and disables HTTP/1.1 features. proxy-nokeepalive Forces the proxy to close the backend connection after each request. proxy-chain-auth If the proxy requires authentication, it will read and consume the proxy authentication credentials sent by the client. With proxy-chain-auth it will also forward the credentials to the next proxy in the chain. This may be necessary if you have a chain of proxies that share authentication information. Security Warning: Do not set this unless you know you need it, as it forwards sensitive information! proxy-sendcl HTTP/1.0 required all HTTP requests that include a body (e.g. POST requests) to include a ContentLength header. This environment variable forces the Apache proxy to send this header to the backend server, regardless of what the Client sent to the proxy. It ensures compatibility when proxying for an HTTP/1.0 or unknown backend. However, it may require the entire request to be buffered by the proxy, so it becomes very inefficient for large requests. 10.91. APACHE MODULE MOD PROXY HTTP 851 proxy-sendchunks or proxy-sendchunked This is the opposite of proxy-sendcl. It allows request bodies to be sent to the backend using chunked transfer encoding. This allows the request to be efficiently streamed, but requires that the backend server supports HTTP/1.1. proxy-interim-response This variable takes values RFC (the default) or Suppress. Earlier httpd versions would suppress HTTP interim (1xx) responses sent from the backend. This is technically a violation of the HTTP protocol. In practice, if a backend sends an interim response, it may itself be extending the protocol in a manner we know nothing about, or just broken. So this is now configurable: set proxy-interim-response RFC to be fully protocol compliant, or proxy-interim-response Suppress to suppress interim responses. proxy-initial-not-pooled If this variable is set, no pooled connection will be reused if the client request is the initial request on the frontend connection. This avoids the "proxy: error reading status line from remote server" error message caused by the race condition that the backend server closed the pooled connection after the connection check by the proxy and before data sent by the proxy reached the backend. It has to be kept in mind that setting this variable downgrades performance, especially with HTTP/1.0 clients. Request notes MOD PROXY HTTP creates the following request notes for logging using the %{VARNAME}n format in L OG F ORMAT or E RROR L OG F ORMAT: proxy-source-port The local port used for the connection to the backend server. proxy-status The HTTP status received from the backend server. 852 CHAPTER 10. APACHE MODULES 10.92 Apache Module mod proxy http2 Description: Status: ModuleIdentifier: SourceFile: HTTP/2 support module for MOD PROXY Extension proxy http2 module mod proxy http2.c Summary This module requires the service of MOD PROXY. It provides the features used for proxying HTTP/2 requests. MOD PROXY HTTP 2 supports HTTP/2 only. It does not provide any downgrades to HTTP/1.1. Thus, in order to get the ability of handling HTTP/2 proxy requests, MOD PROXY and MOD PROXY HTTP 2 have to be present in the server. MOD PROXY HTTP 2 works with incoming requests over HTTP/1.1 and HTTP/2 requests. If MOD HTTP 2 handles the frontend connection, requests against the same HTTP/2 backend are sent over a single connection, whenever possible. This module relies on libnghttp276 to provide the core http/2 engine. ! ! Warning This module is experimental. Its behaviors, directives, and defaults are subject to more change from release to release relative to other standard modules. Users are encouraged to consult the "CHANGES" file for potential updates. Warning Do not enable proxying until you have secured your server (p. 787) . Open proxy servers are dangerous both to your network and to the Internet at large. Directives This module provides no directives. See also • MOD HTTP 2 • MOD PROXY • MOD PROXY CONNECT Request notes MOD PROXY HTTP creates the following request notes for logging using the %{VARNAME}n format in L OG F ORMAT or E RROR L OG F ORMAT: proxy-source-port The local port used for the connection to the backend server. proxy-status The HTTP/2 status received from the backend server. 76 http://nghttp2.org/ 10.93. APACHE MODULE MOD PROXY SCGI 10.93 853 Apache Module mod proxy scgi Description: Status: ModuleIdentifier: SourceFile: SCGI gateway module for MOD PROXY Extension proxy scgi module mod proxy scgi.c Summary This module requires the service of MOD PROXY. It provides support for the SCGI protocol, version 177 . Thus, in order to get the ability of handling the SCGI protocol, MOD PROXY and MOD PROXY SCGI have to be present in the server. ! Warning Do not enable proxying until you have secured your server (p. 787) . Open proxy servers are dangerous both to your network and to the Internet at large. Directives • ProxySCGIInternalRedirect • ProxySCGISendfile See also • MOD PROXY • MOD PROXY BALANCER Examples Remember, in order to make the following examples work, you have to enable MOD PROXY and MOD PROXY SCGI. Simple gateway ProxyPass "/scgi-bin/" "scgi://localhost:4000/" The balanced gateway needs MOD PROXY BALANCER and at least one load balancer algorithm module, such as MOD LBMETHOD BYREQUESTS, in addition to the proxy modules listed above. MOD LBMETHOD BYREQUESTS is the default, and will be used for this example configuration. Balanced gateway ProxyPass "/scgi-bin/" "balancer://somecluster/" BalancerMember scgi://localhost:4000 BalancerMember scgi://localhost:4001 77 http://python.ca/scgi/protocol.txt 854 CHAPTER 10. APACHE MODULES Environment Variables In addition to the configuration directives that control the behaviour of MOD PROXY, an environment variable may also control the SCGI protocol provider: proxy-scgi-pathinfo By default MOD PROXY SCGI will neither create nor export the PATH INFO environment variable. This allows the backend SCGI server to correctly determine SCRIPT NAME and Script-URI and be compliant with RFC 3875 section 3.3. If instead you need MOD PROXY SCGI to generate a "best guess" for PATH INFO, set this env-var. The variable must be set before S ET E NV is effective. S ET E NV I F can be used instead: SetEnvIf Request URI . proxy-scgi-pathinfo ProxySCGIInternalRedirect Directive Description: Syntax: Default: Context: Status: Module: Compatibility: Enable or disable internal redirect responses from the backend ProxySCGIInternalRedirect On|Off|Headername ProxySCGIInternalRedirect On server config, virtual host, directory Extension mod proxy scgi The Headername feature is available in Apache httpd 2.4.13 and later. The P ROXY SCGII NTERNAL R EDIRECT enables the backend to internally redirect the gateway to a different URL. This feature originates in MOD CGI, which internally redirects the response if the response status is OK (200) and the response contains a Location (or configured alternate header) and its value starts with a slash (/). This value is interpreted as a new local URL that Apache httpd internally redirects to. MOD PROXY SCGI does the same as MOD CGI in this regard, except that you can turn off the feature or specify the use of a header other than Location. Example ProxySCGIInternalRedirect Off # Django and some other frameworks will fully qualify "local URLs" # set by the application, so an alternate header must be used. ProxySCGIInternalRedirect X-Location ProxySCGISendfile Directive Description: Syntax: Default: Context: Status: Module: Enable evaluation of X-Sendfile pseudo response header ProxySCGISendfile On|Off|Headername ProxySCGISendfile Off server config, virtual host, directory Extension mod proxy scgi The P ROXY SCGIS ENDFILE directive enables the SCGI backend to let files be served directly by the gateway. This is useful for performance purposes - httpd can use sendfile or other optimizations, which are not possible if the file comes over the backend socket. Additionally, the file contents are not transmitted twice. The P ROXY SCGIS ENDFILE argument determines the gateway behaviour: 10.93. APACHE MODULE MOD PROXY SCGI 855 Off No special handling takes place. On The gateway looks for a backend response header called X-Sendfile and interprets the value as the filename to serve. The header is removed from the final response headers. This is equivalent to ProxySCGISendfile X-Sendfile. anything else Similar to On, but instead of the hardcoded header name X-Sendfile, the argument is used as the header name. Example # Use the default header (X-Sendfile) ProxySCGISendfile On # Use a different header ProxySCGISendfile X-Send-Static 856 CHAPTER 10. APACHE MODULES 10.94 Apache Module mod proxy wstunnel Description: Status: ModuleIdentifier: SourceFile: Compatibility: Websockets support module for MOD PROXY Extension proxy wstunnel module mod proxy wstunnel.c Available in httpd 2.4.5 and later Summary This module requires the service of MOD PROXY. It provides support for the tunnelling of web socket connections to a backend websockets server. The connection is automatically upgraded to a websocket connection: HTTP Response Upgrade: WebSocket Connection: Upgrade Proxying requests to a websockets server like echo.websocket.org can be done using the P ROXY PASS directive: ProxyPass "/ws2/" "ws://echo.websocket.org/" ProxyPass "/wss2/" "wss://echo.websocket.org/" Load balancing for multiple backends can be achieved using MOD PROXY BALANCER. Directives • ProxyWebsocketAsync • ProxyWebsocketAsyncDelay • ProxyWebsocketIdleTimeout See also • MOD PROXY ProxyWebsocketAsync Directive Description: Syntax: Context: Status: Module: Instructs this module to try to create an asynchronous tunnel ProxyWebsocketAsync ON|OFF server config, virtual host Extension mod proxy wstunnel This directive instructs the server to try to create an asynchronous tunnel. If the current MPM does not support the necessary features, a synchronous tunnel is used. =⇒Note Async support is experimental and subject to change. 10.94. APACHE MODULE MOD PROXY WSTUNNEL 857 ProxyWebsocketAsyncDelay Directive Description: Syntax: Default: Context: Status: Module: Sets the amount of time the tunnel waits synchronously for data ProxyWebsocketAsyncDelay num[ms] ProxyWebsocketAsyncDelay 0 server config, virtual host Extension mod proxy wstunnel If P ROXY W EBSOCKETA SYNC is enabled, this directive controls how long the server synchronously waits for more data. =⇒Note Async support is experimental and subject to change. ProxyWebsocketIdleTimeout Directive Description: Syntax: Default: Context: Status: Module: Sets the maximum amount of time to wait for data on the websockets tunnel ProxyWebsocketIdleTimeout num[ms] ProxyWebsocketIdleTimeout 0 server config, virtual host Extension mod proxy wstunnel This directive imposes a maximum amount of time for the tunnel to be left open while idle. 858 10.95 CHAPTER 10. APACHE MODULES Apache Module mod ratelimit Description: Status: ModuleIdentifier: SourceFile: Bandwidth Rate Limiting for Clients Extension ratelimit module mod ratelimit.c Summary Provides a filter named RATE LIMIT to limit client bandwidth. The connection speed to be simulated is specified, in KiB/s, using the environment variable rate-limit. Example Configuration SetOutputFilter RATE_LIMIT SetEnv rate-limit 400 Directives This module provides no directives. 10.96. APACHE MODULE MOD REFLECTOR 10.96 859 Apache Module mod reflector Description: Status: ModuleIdentifier: SourceFile: Compatibility: Reflect a request body as a response via the output filter stack. Base reflector module mod reflector.c Version 2.3 and later Summary This module allows request bodies to be reflected back to the client, in the process passing the request through the output filter stack. A suitably configured chain of filters can be used to transform the request into a response. This module can be used to turn an output filter into an HTTP service. Directives • ReflectorHeader Examples Compression service Pass the request body through the DEFLATE filter to compress the body. This request requires a Content-Encoding request header containing "gzip" for the filter to return compressed data. SetHandler reflector SetOutputFilter DEFLATE Image downsampling service Pass the request body through an image downsampling filter, and reflect the results to the caller. SetHandler reflector SetOutputFilter DOWNSAMPLE ReflectorHeader Directive Description: Syntax: Context: Override: Status: Module: Reflect an input header to the output headers ReflectorHeader inputheader [outputheader] server config, virtual host, directory, .htaccess Options Base mod reflector This directive controls the reflection of request headers to the response. The first argument is the name of the request header to copy. If the optional second argument is specified, it will be used as the name of the response header, otherwise the original request header name will be used. 860 CHAPTER 10. APACHE MODULES 10.97 Apache Module mod remoteip Description: Status: ModuleIdentifier: SourceFile: Replaces the original client IP address for the connection with the useragent IP address list presented by a proxies or a load balancer via the request headers. Base remoteip module mod remoteip.c Summary This module is used to treat the useragent which initiated the request as the originating useragent as identified by httpd for the purposes of authorization and logging, even where that useragent is behind a load balancer, front end server, or proxy server. The module overrides the client IP address for the connection with the useragent IP address reported in the request header configured with the R EMOTE IPH EADER directive. Once replaced as instructed, this overridden useragent IP address is then used for the MOD AUTHZ HOST R EQUIRE IP feature, is reported by MOD STATUS , and is recorded by MOD LOG CONFIG %a and CORE %a format strings. The underlying client IP of the connection is available in the %{c}a format string. ! It is critical to only enable this behavior from intermediate hosts (proxies, etc) which are trusted by this server, since it is trivial for the remote useragent to impersonate another useragent. Directives • RemoteIPHeader • RemoteIPInternalProxy • RemoteIPInternalProxyList • RemoteIPProxiesHeader • RemoteIPTrustedProxy • RemoteIPTrustedProxyList See also • MOD AUTHZ HOST • MOD STATUS • MOD LOG CONFIG Remote IP Processing Apache by default identifies the useragent with the connection’s client ip value, and the connection remote host and remote logname are derived from this value. These fields play a role in authentication, authorization and logging and other purposes by other loadable modules. mod remoteip overrides the client IP of the connection with the advertised useragent IP as provided by a proxy or load balancer, for the duration of the request. A load balancer might establish a long lived keepalive connection with the server, and each request will have the correct useragent IP, even though the underlying client IP address of the load balancer remains unchanged. 10.97. APACHE MODULE MOD REMOTEIP 861 When multiple, comma delimited useragent IP addresses are listed in the header value, they are processed in Rightto-Left order. Processing halts when a given useragent IP address is not trusted to present the preceding IP address. The header field is updated to this remaining list of unconfirmed IP addresses, or if all IP addresses were trusted, this header is removed from the request altogether. In overriding the client IP, the module stores the list of intermediate hosts in a remoteip-proxy-ip-list note, which MOD LOG CONFIG can record using the %{remoteip-proxy-ip-list}n format token. If the administrator needs to store this as an additional header, this same value can also be recording as a header using the directive R EMOTE IPP ROXIES H EADER. =⇒IPv4-over-IPv6 Mapped Addresses As with httpd in general, any IPv4-over-IPv6 mapped addresses are recorded in their IPv4 representation. =⇒Internal (Private) Addresses All internal addresses 10/8, 172.16/12, 192.168/16, 169.254/16 and 127/8 blocks (and IPv6 addresses outside of the public 2000::/3 block) are only evaluated by mod remoteip when R EMOTE IPI NTERNAL P ROXY internal (intranet) proxies are registered. RemoteIPHeader Directive Description: Syntax: Context: Status: Module: Declare the header field which should be parsed for useragent IP addresses RemoteIPHeader header-field server config, virtual host Base mod remoteip The R EMOTE IPH EADER directive triggers MOD REMOTEIP to treat the value of the specified header-field header as the useragent IP address, or list of intermediate useragent IP addresses, subject to further configuration of the R EMOTE IPI NTERNAL P ROXY and R EMOTE IPT RUSTED P ROXY directives. ! Unless these other directives are used, MOD REMOTEIP will trust all hosts presenting a non internal address in the R EMOTE IPH EADER header value. Internal (Load Balancer) Example RemoteIPHeader X-Client-IP Proxy Example RemoteIPHeader X-Forwarded-For RemoteIPInternalProxy Directive Description: Syntax: Context: Status: Module: Declare client intranet IP addresses trusted to present the RemoteIPHeader value RemoteIPInternalProxy proxy-ip|proxy-ip/subnet|hostname ... server config, virtual host Base mod remoteip The R EMOTE IPI NTERNAL P ROXY directive adds one or more addresses (or address blocks) to trust as presenting a valid RemoteIPHeader value of the useragent IP. Unlike the R EMOTE IPT RUSTED P ROXY directive, any IP address presented in this header, including private intranet addresses, are trusted when passed from these proxies. 862 CHAPTER 10. APACHE MODULES Internal (Load Balancer) Example RemoteIPHeader X-Client-IP RemoteIPInternalProxy 10.0.2.0/24 RemoteIPInternalProxy gateway.localdomain RemoteIPInternalProxyList Directive Description: Syntax: Context: Status: Module: Declare client intranet IP addresses trusted to present the RemoteIPHeader value RemoteIPInternalProxyList filename server config, virtual host Base mod remoteip The R EMOTE IPI NTERNAL P ROXY L IST directive specifies a file parsed at startup, and builds a list of addresses (or address blocks) to trust as presenting a valid RemoteIPHeader value of the useragent IP. The ’#’ hash character designates a comment line, otherwise each whitespace or newline separated entry is processed identically to the R EMOTE IPI NTERNAL P ROXY directive. Internal (Load Balancer) Example RemoteIPHeader X-Client-IP RemoteIPInternalProxyList conf/trusted-proxies.lst conf/trusted-proxies.lst contents # Our internally trusted proxies; 10.0.2.0/24 #Everyone in the testing group gateway.localdomain #The front end balancer RemoteIPProxiesHeader Directive Description: Syntax: Context: Status: Module: Declare the header field which will record all intermediate IP addresses RemoteIPProxiesHeader HeaderFieldName server config, virtual host Base mod remoteip The R EMOTE IPP ROXIES H EADER directive specifies a header into which MOD REMOTEIP will collect a list of all of the intermediate client IP addresses trusted to resolve the useragent IP of the request. Note that intermediate R E MOTE IPT RUSTED P ROXY addresses are recorded in this header, while any intermediate R EMOTE IPI NTERNAL P ROXY addresses are discarded. Example RemoteIPHeader X-Forwarded-For RemoteIPProxiesHeader X-Forwarded-By 10.97. APACHE MODULE MOD REMOTEIP 863 RemoteIPTrustedProxy Directive Description: Syntax: Context: Status: Module: Restrict client IP addresses trusted to present the RemoteIPHeader value RemoteIPTrustedProxy proxy-ip|proxy-ip/subnet|hostname ... server config, virtual host Base mod remoteip The R EMOTE IPT RUSTED P ROXY directive restricts which peer IP addresses (or address blocks) will be trusted to present a valid RemoteIPHeader value of the useragent IP. Unlike the R EMOTE IPI NTERNAL P ROXY directive, any intranet or private IP address reported by such proxies, including the 10/8, 172.16/12, 192.168/16, 169.254/16 and 127/8 blocks (or outside of the IPv6 public 2000::/3 block) are not trusted as the useragent IP, and are left in the R EMOTE IPH EADER header’s value. ! By default, MOD REMOTEIP will trust all hosts presenting a non internal address in the R E MOTE IPH EADER header value. Trusted (Load Balancer) Example RemoteIPHeader X-Forwarded-For RemoteIPTrustedProxy 10.0.2.16/28 RemoteIPTrustedProxy proxy.example.com RemoteIPTrustedProxyList Directive Description: Syntax: Context: Status: Module: Restrict client IP addresses trusted to present the RemoteIPHeader value RemoteIPTrustedProxyList filename server config, virtual host Base mod remoteip The R EMOTE IPT RUSTED P ROXY L IST directive specifies a file parsed at startup, and builds a list of addresses (or address blocks) to trust as presenting a valid RemoteIPHeader value of the useragent IP. The ’#’ hash character designates a comment line, otherwise each whitespace or newline separated entry is processed identically to the R EMOTE IPT RUSTED P ROXY directive. Trusted (Load Balancer) Example RemoteIPHeader X-Forwarded-For RemoteIPTrustedProxyList conf/trusted-proxies.lst conf/trusted-proxies.lst contents # Identified external proxies; 192.0.2.16/28 #wap phone group of proxies proxy.isp.example.com #some well known ISP 864 CHAPTER 10. APACHE MODULES 10.98 Apache Module mod reqtimeout Description: Status: ModuleIdentifier: SourceFile: Set timeout and minimum data rate for receiving requests Extension reqtimeout module mod reqtimeout.c Directives • RequestReadTimeout Examples 1. Allow 10 seconds to receive the request including the headers and 30 seconds for receiving the request body: RequestReadTimeout header=10 body=30 2. Allow at least 10 seconds to receive the request body. If the client sends data, increase the timeout by 1 second for every 1000 bytes received, with no upper limit for the timeout (except for the limit given indirectly by L IMIT R EQUEST B ODY): RequestReadTimeout body=10,MinRate=1000 3. Allow at least 10 seconds to receive the request including the headers. If the client sends data, increase the timeout by 1 second for every 500 bytes received. But do not allow more than 30 seconds for the request including the headers: RequestReadTimeout header=10-30,MinRate=500 4. Usually, a server should have both header and body timeouts configured. If a common configuration is used for http and https virtual hosts, the timeouts should not be set too low: RequestReadTimeout header=20-40,MinRate=500 body=20,MinRate=500 RequestReadTimeout Directive Description: Syntax: Default: Context: Status: Module: Compatibility: Set timeout values for receiving request headers and body from client. RequestReadTimeout [header=timeout[-maxtimeout][,MinRate=rate] [body=timeout[-maxtimeout][,MinRate=rate] header=20-40,MinRate=500 body=20,MinRate=500 server config, virtual host Extension mod reqtimeout Defaulted to disabled in version 2.3.14 and earlier. This directive can set various timeouts for receiving the request headers and the request body from the client. If the client fails to send headers or body within the configured time, a 408 REQUEST TIME OUT error is sent. For SSL virtual hosts, the header timeout values include the time needed to do the initial SSL handshake. If the user’s browser is configured to query certificate revocation lists and the CRL server is not reachable, the initial SSL handshake may take a significant time until the browser gives up waiting for the CRL. Therefore the header timeout values should not be set to very low values for SSL virtual hosts. The body timeout values include the time needed for SSL renegotiation (if necessary). 10.98. APACHE MODULE MOD REQTIMEOUT 865 When an ACCEPT F ILTER is in use (usually the case on Linux and FreeBSD), the socket is not sent to the server process before at least one byte (or the whole request for httpready) is received. The header timeout configured with RequestReadTimeout is only effective after the server process has received the socket. For each of the two timeout types (header or body), there are three ways to specify the timeout: • Fixed timeout value: type=timeout The time in seconds allowed for reading all of the request headers or body, respectively. A value of 0 means no limit. • Disable module for a vhost:: header=0 body=0 This disables MOD REQTIMEOUT completely. • Timeout value that is increased when data is received: type=timeout,MinRate=data rate Same as above, but whenever data is received, the timeout value is increased according to the specified minimum data rate (in bytes per second). • Timeout value that is increased when data is received, with an upper bound: type=timeout-maxtimeout,MinRate=data rate Same as above, but the timeout will not be increased above the second value of the specified timeout range. 866 CHAPTER 10. APACHE MODULES 10.99 Apache Module mod request Description: Status: ModuleIdentifier: SourceFile: Compatibility: Filters to handle and make available HTTP request bodies Base request module mod request.c Available in Apache 2.3 and later Directives • KeptBodySize KeptBodySize Directive Description: Syntax: Default: Context: Status: Module: Keep the request body instead of discarding it up to the specified maximum size, for potential use by filters such as mod include. KeptBodySize maximum size in bytes KeptBodySize 0 directory Base mod request Under normal circumstances, request handlers such as the default handler for static files will discard the request body when it is not needed by the request handler. As a result, filters such as mod include are limited to making GET requests only when including other URLs as subrequests, even if the original request was a POST request, as the discarded request body is no longer available once filter processing is taking place. When this directive has a value greater than zero, request handlers that would otherwise discard request bodies will instead set the request body aside for use by filters up to the maximum size specified. In the case of the mod include filter, an attempt to POST a request to the static shtml file will cause any subrequests to be POST requests, instead of GET requests as before. This feature makes it possible to break up complex web pages and web applications into small individual components, and combine the components and the surrounding web page structure together using MOD INCLUDE. The components can take the form of CGI programs, scripted languages, or URLs reverse proxied into the URL space from another server using MOD PROXY. Note: Each request set aside has to be set aside in temporary RAM until the request is complete. As a result, care should be taken to ensure sufficient RAM is available on the server to support the intended load. Use of this directive should be limited to where needed on targeted parts of your URL space, and with the lowest possible value that is still big enough to hold a request body. If the request size sent by the client exceeds the maximum size allocated by this directive, the server will return 413 Request Entity Too Large. See also • mod include (p. 667) documentation • mod auth form (p. 466) documentation 10.100. APACHE MODULE MOD REWRITE 10.100 867 Apache Module mod rewrite Description: Status: ModuleIdentifier: SourceFile: Provides a rule-based rewriting engine to rewrite requested URLs on the fly Extension rewrite module mod rewrite.c Summary The MOD REWRITE module uses a rule-based rewriting engine, based on a PCRE regular-expression parser, to rewrite requested URLs on the fly. By default, MOD REWRITE maps a URL to a filesystem path. However, it can also be used to redirect one URL to another URL, or to invoke an internal proxy fetch. MOD REWRITE provides a flexible and powerful way to manipulate URLs using an unlimited number of rules. Each rule can have an unlimited number of attached rule conditions, to allow you to rewrite URL based on server variables, environment variables, HTTP headers, or time stamps. MOD REWRITE operates on the full URL path, including the path-info section. A rewrite rule can be invoked in httpd.conf or in .htaccess. The path generated by a rewrite rule can include a query string, or can lead to internal sub-processing, external request redirection, or internal proxy throughput. Further details, discussion, and examples, are provided in the detailed mod rewrite documentation (p. 146) . Directives • RewriteBase • RewriteCond • RewriteEngine • RewriteMap • RewriteOptions • RewriteRule Logging MOD REWRITE offers detailed logging of its actions at the trace1 to trace8 log levels. The log level can be set specifically for MOD REWRITE using the L OG L EVEL directive: Up to level debug, no actions are logged, while trace8 means that practically all actions are logged. =⇒Using a high trace log level for will slow down your Apache HTTP Server dramatically! Use a log level higher than trace2 only for debugging! MOD REWRITE Example LogLevel alert rewrite:trace3 =⇒RewriteLog Those familiar with earlier versions of MOD REWRITE will no doubt be looking for the RewriteLog and RewriteLogLevel directives. This functionality has been completely replaced by the new per-module logging configuration mentioned above. To get just the MOD REWRITE-specific log messages, pipe the log file through grep: tail -f error log|fgrep ’[rewrite:’ 868 CHAPTER 10. APACHE MODULES RewriteBase Directive Description: Syntax: Default: Context: Override: Status: Module: Sets the base URL for per-directory rewrites RewriteBase URL-path None directory, .htaccess FileInfo Extension mod rewrite The R EWRITE BASE directive specifies the URL prefix to be used for per-directory (htaccess) R EWRITE RULE directives that substitute a relative path. This directive is required when you use a relative path in a substitution in per-directory (htaccess) context unless either of the following conditions are true: • The original request, and the substitution, are underneath the D OCUMENT ROOT (as opposed to reachable by other means, such as A LIAS). • The filesystem path to the directory containing the R EWRITE RULE, suffixed by the relative substitution is also valid as a URL path on the server (this is rare). • In Apache HTTP Server 2.4.16 and later, this directive may be omitted when the request is mapped via A LIAS or MOD USERDIR. In the example below, R EWRITE BASE is necessary to avoid rewriting to http://example.com/opt/myapp1.2.3/welcome.html since the resource was not relative to the document root. This misconfiguration would normally cause the server to look for an "opt" directory under the document root. DocumentRoot "/var/www/example.com" AliasMatch "ˆ/myapp" "/opt/myapp-1.2.3" RewriteEngine On RewriteBase "/myapp/" RewriteRule "ˆindex\.html$" "welcome.html" RewriteCond Directive Description: Syntax: Context: Override: Status: Module: Defines a condition under which rewriting will take place RewriteCond TestString CondPattern server config, virtual host, directory, .htaccess FileInfo Extension mod rewrite The R EWRITE C OND directive defines a rule condition. One or more R EWRITE C OND can precede a R EWRITE RULE directive. The following rule is then only used if both the current state of the URI matches its pattern, and if these conditions are met. TestString is a string which can contain the following expanded constructs in addition to plain text: • RewriteRule backreferences: These are backreferences of the form $N (0 <= N <= 9). $1 to $9 provide access to the grouped parts (in parentheses) of the pattern, from the RewriteRule which is subject to the current set of RewriteCond conditions. $0 provides access to the whole string matched by that pattern. 10.100. APACHE MODULE MOD REWRITE 869 • RewriteCond backreferences: These are backreferences of the form %N (0 <= N <= 9). %1 to %9 provide access to the grouped parts (again, in parentheses) of the pattern, from the last matched RewriteCond in the current set of conditions. %0 provides access to the whole string matched by that pattern. • RewriteMap expansions: These are expansions of the form ${mapname:key|default}. See the documentation for RewriteMap for more details. • Server-Variables: These are variables of the form %{ NAME OF VARIABLE } where NAME OF VARIABLE can be a string taken from the following list: HTTP headers: connection & request: HTTP HTTP HTTP HTTP HTTP HTTP HTTP AUTH TYPE CONN REMOTE ADDR CONTEXT PREFIX CONTEXT DOCUMENT ROOT IPV6 PATH INFO QUERY STRING REMOTE ADDR REMOTE HOST REMOTE IDENT REMOTE PORT REMOTE USER REQUEST METHOD SCRIPT FILENAME ACCEPT COOKIE FORWARDED HOST PROXY CONNECTION REFERER USER AGENT server internals: DOCUMENT ROOT SCRIPT GROUP SCRIPT USER SERVER ADDR SERVER ADMIN SERVER NAME SERVER PORT SERVER PROTOCOL SERVER SOFTWARE date and time: specials: TIME TIME TIME TIME TIME TIME TIME TIME API VERSION CONN REMOTE ADDR HTTPS IS SUBREQ REMOTE ADDR REQUEST FILENAME REQUEST SCHEME REQUEST URI THE REQUEST YEAR MON DAY HOUR MIN SEC WDAY These variables all correspond to the similarly named HTTP MIME-headers, C variables of the Apache HTTP Server or struct tm fields of the Unix system. Most are documented here (p. 99) or elsewhere in the Manual or in the CGI specification. SERVER NAME and SERVER PORT depend on the values of U SE C ANONICAL NAME and U SE C ANONICAL P HYSICAL P ORT respectively. Those that are special to mod rewrite include those below. API VERSION This is the version of the Apache httpd module API (the internal interface between server and module) in the current httpd build, as defined in include/ap mmn.h. The module API version corresponds to the version of Apache httpd in use (in the release version of Apache httpd 1.3.14, for instance, it is 19990320:10), but is mainly of interest to module authors. CONN REMOTE ADDR Since 2.4.8: The peer IP address of the connection (see the MOD REMOTEIP module). HTTPS Will contain the text "on" if the connection is using SSL/TLS, or "off" otherwise. (This variable can be safely used regardless of whether or not MOD SSL is loaded). IS SUBREQ Will contain the text "true" if the request currently being processed is a sub-request, "false" otherwise. Sub-requests may be generated by modules that need to resolve additional files or URIs in order to complete their tasks. REMOTE ADDR The IP address of the remote host (see the MOD REMOTEIP module). REQUEST FILENAME The full local filesystem path to the file or script matching the request, if this has already been determined by the server at the time REQUEST FILENAME is referenced. Otherwise, such as 870 CHAPTER 10. APACHE MODULES when used in virtual host context, the same value as REQUEST URI. Depending on the value of ACCEPTPATH I NFO, the server may have only used some leading components of the REQUEST URI to map the request to a file. REQUEST SCHEME Will contain the scheme of the request (usually "http" or "https"). This value can be influenced with S ERVER NAME. REQUEST URI The path component of the requested URI, such as "/index.html". This notably excludes the query string which is available as its own variable named QUERY STRING. THE REQUEST The full HTTP request line sent by the browser to the server (e.g., "GET /index.html HTTP/1.1"). This does not include any additional headers sent by the browser. This value has not been unescaped (decoded), unlike most other variables below. If the TestString has the special value expr, the CondPattern will be treated as an ap expr (p. 99) . HTTP headers referenced in the expression will be added to the Vary header if the novary flag is not given. Other things you should be aware of: 1. The variables SCRIPT FILENAME and REQUEST FILENAME contain the same value - the value of the filename field of the internal request rec structure of the Apache HTTP Server. The first name is the commonly known CGI variable name while the second is the appropriate counterpart of REQUEST URI (which contains the value of the uri field of request rec). If a substitution occurred and the rewriting continues, the value of both variables will be updated accordingly. If used in per-server context (i.e., before the request is mapped to the filesystem) SCRIPT FILENAME and REQUEST FILENAME cannot contain the full local filesystem path since the path is unknown at this stage of processing. Both variables will initially contain the value of REQUEST URI in that case. In order to obtain the full local filesystem path of the request in per-server context, use an URL-based look-ahead %{LA-U:REQUEST FILENAME} to determine the final value of REQUEST FILENAME. 2. %{ENV:variable}, where variable can be any environment variable, is also available. This is looked-up via internal Apache httpd structures and (if not found there) via getenv() from the Apache httpd server process. 3. %{SSL:variable}, where variable is the name of an SSL environment variable (p. 916) , can be used whether or not MOD SSL is loaded, but will always expand to the empty string if it is not. Example: %{SSL:SSL CIPHER USEKEYSIZE} may expand to 128. These variables are available even without setting the StdEnvVars option of the SSLO PTIONS directive. 4. %{HTTP:header}, where header can be any HTTP MIME-header name, can always be used to obtain the value of a header sent in the HTTP request. Example: %{HTTP:Proxy-Connection} is the value of the HTTP header “Proxy-Connection:”. If a HTTP header is used in a condition this header is added to the Vary header of the response in case the condition evaluates to true for the request. It is not added if the condition evaluates to false for the request. Adding the HTTP header to the Vary header of the response is needed for proper caching. It has to be kept in mind that conditions follow a short circuit logic in the case of the ’ornext|OR’ flag so that certain conditions might not be evaluated at all. 5. %{LA-U:variable} can be used for look-aheads which perform an internal (URL-based) sub-request to determine the final value of variable. This can be used to access variable for rewriting which is not available at the current stage, but will be set in a later phase. For instance, to rewrite according to the REMOTE USER variable from within the per-server context (httpd.conf file) you must use %{LA-U:REMOTE USER} this variable is set by the authorization phases, which come after the URL translation phase (during which mod rewrite operates). On the other hand, because mod rewrite implements its per-directory context (.htaccess file) via the Fixup phase of the API and because the authorization phases come before this phase, you just can use %{REMOTE USER} in that context. 10.100. APACHE MODULE MOD REWRITE 871 6. %{LA-F:variable} can be used to perform an internal (filename-based) sub-request, to determine the final value of variable. Most of the time, this is the same as LA-U above. CondPattern is the condition pattern, a regular expression which is applied to the current instance of the TestString. TestString is first evaluated, before being matched against CondPattern. CondPattern is usually a perl compatible regular expression, but there is additional syntax available to perform other useful tests against the Teststring: 1. You can prefix the pattern string with a ’!’ character (exclamation mark) to negate the result of the condition, no matter what kind of CondPattern is used. 2. You can perform lexicographical string comparisons: CondPattern Lexicographically follows Treats the CondPattern as a plain string and compares it lexicographically to TestString. True if TestString lexicographically follows CondPattern. =CondPattern Lexicographically equal Treats the CondPattern as a plain string and compares it lexicographically to TestString. True if TestString is lexicographically equal to CondPattern (the two strings are exactly equal, character for character). If CondPattern is "" (two quotation marks) this compares TestString to the empty string. <=CondPattern Lexicographically less than or equal to Treats the CondPattern as a plain string and compares it lexicographically to TestString. True if TestString lexicographically precedes CondPattern, or is equal to CondPattern (the two strings are equal, character for character). >=CondPattern Lexicographically greater than or equal to Treats the CondPattern as a plain string and compares it lexicographically to TestString. True if TestString lexicographically follows CondPattern, or is equal to CondPattern (the two strings are equal, character for character). 3. You can perform integer comparisons: -eq Is numerically equal to The TestString is treated as an integer, and is numerically compared to the CondPattern. True if the two are numerically equal. -ge Is numerically greater than or equal to The TestString is treated as an integer, and is numerically compared to the CondPattern. True if the TestString is numerically greater than or equal to the CondPattern. -gt Is numerically greater than The TestString is treated as an integer, and is numerically compared to the CondPattern. True if the TestString is numerically greater than the CondPattern. -le Is numerically less than or equal to The TestString is treated as an integer, and is numerically compared to the CondPattern. True if the TestString is numerically less than or equal to the CondPattern. Avoid confusion with the -l by using the -L or -h variant. -lt Is numerically less than The TestString is treated as an integer, and is numerically compared to the CondPattern. True if the TestString is numerically less than the CondPattern. Avoid confusion with the -l by using the -L or -h variant. 872 CHAPTER 10. APACHE MODULES -ne Is numerically not equal to The TestString is treated as an integer, and is numerically compared to the CondPattern. True if the two are numerically different. This is equivalent to !-eq. 4. You can perform various file attribute tests: -d Is directory. Treats the TestString as a pathname and tests whether or not it exists, and is a directory. -f Is regular file. Treats the TestString as a pathname and tests whether or not it exists, and is a regular file. -F Is existing file, via subrequest. Checks whether or not TestString is a valid file, accessible via all the server’s currently-configured access controls for that path. This uses an internal subrequest to do the check, so use it with care - it can impact your server’s performance! -h Is symbolic link, bash convention. See -l. -l Is symbolic link. Treats the TestString as a pathname and tests whether or not it exists, and is a symbolic link. May also use the bash convention of -L or -h if there’s a possibility of confusion such as when using the -lt or -le tests. -L Is symbolic link, bash convention. See -l. -s Is regular file, with size. Treats the TestString as a pathname and tests whether or not it exists, and is a regular file with size greater than zero. -U Is existing URL, via subrequest. Checks whether or not TestString is a valid URL, accessible via all the server’s currently-configured access controls for that path. This uses an internal subrequest to do the check, so use it with care - it can impact your server’s performance! This flag only returns information about things like access control, authentication, and authorization. This flag does not return information about the status code the configured handler (static file, CGI, proxy, etc.) would have returned. -x Has executable permissions. Treats the TestString as a pathname and tests whether or not it exists, and has executable permissions. These permissions are determined according to the underlying OS. For example: RewriteCond /var/www/%{REQUEST_URI} !-f RewriteRule ˆ(.+) /other/archive/$1 [R] 5. If the TestString has the special value expr, the CondPattern will be treated as an ap expr (p. 99) . In the below example, -strmatch is used to compare the REFERER against the site hostname, to block unwanted hotlinking. RewriteCond expr "! %{HTTP_REFERER} -strmatch ’*://%{HTTP_HOST}/*’" RewriteRule "ˆ/images" "-" [F] 6. You can also set special flags for CondPattern by appending [flags] as the third argument to the RewriteCond directive, where flags is a comma-separated list of any of the following flags: 10.100. APACHE MODULE MOD REWRITE 873 • ’nocase|NC’ (no case) This makes the test case-insensitive - differences between ’A-Z’ and ’a-z’ are ignored, both in the expanded TestString and the CondPattern. This flag is effective only for comparisons between TestString and CondPattern. It has no effect on filesystem and subrequest checks. • ’ornext|OR’ (or next condition) Use this to combine rule conditions with a local OR instead of the implicit AND. Typical example: RewriteCond RewriteCond RewriteCond RewriteRule "%{REMOTE_HOST}" "ˆhost1" [OR] "%{REMOTE_HOST}" "ˆhost2" [OR] "%{REMOTE_HOST}" "ˆhost3" ...some special stuff for any of these hosts... Without this flag you would have to write the condition/rule pair three times. • ’novary|NV’ (no vary) If a HTTP header is used in the condition, this flag prevents this header from being added to the Vary header of the response. Using this flag might break proper caching of the response if the representation of this response varies on the value of this header. So this flag should be only used if the meaning of the Vary header is well understood. Example: To rewrite the Homepage of a site according to the “User-Agent:” header of the request, you can use the following: RewriteCond RewriteRule "%{HTTP_USER_AGENT}" "ˆ/$" "(iPhone|Blackberry|Android)" "/homepage.mobile.html" [L] RewriteRule "ˆ/$" "/homepage.std.html" [L] Explanation: If you use a browser which identifies itself as a mobile browser (note that the example is incomplete, as there are many other mobile platforms), the mobile version of the homepage is served. Otherwise, the standard page is served. RewriteEngine Directive Description: Syntax: Default: Context: Override: Status: Module: Enables or disables runtime rewriting engine RewriteEngine on|off RewriteEngine off server config, virtual host, directory, .htaccess FileInfo Extension mod rewrite The R EWRITE E NGINE directive enables or disables the runtime rewriting engine. If it is set to off this module does no runtime processing at all. It does not even update the SCRIPT URx environment variables. Use this directive to disable rules in a particular context, rather than commenting out all the R EWRITE RULE directives. Note that rewrite configurations are not inherited by virtual hosts. This means that you need to have a RewriteEngine on directive for each virtual host in which you wish to use rewrite rules. R EWRITE M AP directives of the type prg are not started during server initialization if they’re defined in a context that does not have R EWRITE E NGINE set to on 874 CHAPTER 10. APACHE MODULES RewriteMap Directive Description: Syntax: Context: Status: Module: Defines a mapping function for key-lookup RewriteMap MapName MapType:MapSource MapTypeOptions server config, virtual host Extension mod rewrite The R EWRITE M AP directive defines a Rewriting Map which can be used inside rule substitution strings by the mapping-functions to insert/substitute fields through a key lookup. The source of this lookup can be of various types. The MapName is the name of the map and will be used to specify a mapping-function for the substitution strings of a rewriting rule via one of the following constructs: ${ MapName : LookupKey } ${ MapName : LookupKey | DefaultValue } When such a construct occurs, the map MapName is consulted and the key LookupKey is looked-up. If the key is found, the map-function construct is substituted by SubstValue. If the key is not found then it is substituted by DefaultValue or by the empty string if no DefaultValue was specified. Empty values behave as if the key was absent, therefore it is not possible to distinguish between empty-valued keys and absent keys. For example, you might define a R EWRITE M AP as: RewriteMap examplemap "txt:/path/to/file/map.txt" You would then be able to use this map in a R EWRITE RULE as follows: RewriteRule "ˆ/ex/(.*)" "${examplemap:$1}" The meaning of the MapTypeOptions argument depends on particular MapType. See the Using RewriteMap (p. 166) for more information. The following combinations for MapType and MapSource can be used: txt A plain text file containing space-separated key-value pairs, one per line. (Details ... (p. 166) ) rnd Randomly selects an entry from a plain text file (Details ... (p. 166) ) dbm Looks up an entry in a dbm file containing name, value pairs. Hash is constructed from a plain text file format using the httxt2dbm (p. 328) utility. (Details ... (p. 166) ) int One of the four available internal functions provided by RewriteMap: toupper, tolower, escape or unescape. (Details ... (p. 166) ) prg Calls an external program or script to process the rewriting. (Details ... (p. 166) ) dbd or fastdbd A SQL SELECT statement to be performed to look up the rewrite target. (Details ... (p. 166) ) Further details, and numerous examples, may be found in the RewriteMap HowTo (p. 166) RewriteOptions Directive Description: Syntax: Context: Override: Status: Module: Sets some special options for the rewrite engine RewriteOptions Options server config, virtual host, directory, .htaccess FileInfo Extension mod rewrite 10.100. APACHE MODULE MOD REWRITE 875 The R EWRITE O PTIONS directive sets some special options for the current per-server or per-directory configuration. The Option string can currently only be one of the following: Inherit This forces the current configuration to inherit the configuration of the parent. In per-virtual-server context, this means that the maps, conditions and rules of the main server are inherited. In per-directory context this means that conditions and rules of the parent directory’s .htaccess configuration or sections are inherited. The inherited rules are virtually copied to the section where this directive is being used. If used in combination with local rules, the inherited rules are copied behind the local rules. The position of this directive - below or above of local rules - has no influence on this behavior. If local rules forced the rewriting to stop, the inherited rules won’t be processed. ! Rules inherited from the parent scope are applied after rules specified in the child scope. InheritBefore Like Inherit above, but the rules from the parent scope are applied before rules specified in the child scope. Available in Apache HTTP Server 2.3.10 and later. InheritDown If this option is enabled, all child configurations will inherit the configuration of the current configuration. It is equivalent to specifying RewriteOptions Inherit in all child configurations. See the Inherit option for more details on how the parent-child relationships are handled. Available in Apache HTTP Server 2.4.8 and later. InheritDownBefore Like InheritDown above, but the rules from the current scope are applied before rules specified in any child’s scope. Available in Apache HTTP Server 2.4.8 and later. IgnoreInherit This option forces the current and child configurations to ignore all rules that would be inherited from a parent specifying InheritDown or InheritDownBefore. Available in Apache HTTP Server 2.4.8 and later. AllowNoSlash By default, MOD REWRITE will ignore URLs that map to a directory on disk but lack a trailing slash, in the expectation that the MOD DIR module will issue the client with a redirect to the canonical URL with a trailing slash. When the D IRECTORY S LASH directive is set to off, the AllowNoSlash option can be enabled to ensure that rewrite rules are no longer ignored. This option makes it possible to apply rewrite rules within .htaccess files that match the directory without a trailing slash, if so desired. Available in Apache HTTP Server 2.4.0 and later. AllowAnyURI When R EWRITE RULE is used in VirtualHost or server context with version 2.2.22 or later of httpd, MOD REWRITE will only process the rewrite rules if the request URI is a URL-path (p. 377) . This avoids some security issues where particular rules could allow "surprising" pattern expansions (see CVE-2011-336878 and CVE-2011-431779 ). To lift the restriction on matching a URL-path, the AllowAnyURI option can be enabled, and MOD REWRITE will apply the rule set to any request URI string, regardless of whether that string matches the URL-path grammar required by the HTTP specification. Available in Apache HTTP Server 2.4.3 and later. ! Security Warning Enabling this option will make the server vulnerable to security issues if used with rewrite rules which are not carefully authored. It is strongly recommended that this option is not used. In particular, beware of input strings containing the ’@’ character which could change the interpretation of the transformed URI, as per the above CVE names. 78 http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2011-3368 79 http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2011-4317 876 CHAPTER 10. APACHE MODULES MergeBase With this option, the value of R EWRITE BASE is copied from where it’s explicitly defined into any subdirectory or sub-location that doesn’t define its own R EWRITE BASE. This was the default behavior in 2.4.0 through 2.4.3, and the flag to restore it is available Apache HTTP Server 2.4.4 and later. IgnoreContextInfo When a relative substitution is made in directory (htaccess) context and R EWRITE BASE has not been set, this module uses some extended URL and filesystem context information to change the relative substitution back into a URL. Modules such as MOD USERDIR and MOD ALIAS supply this extended context info. Available in 2.4.16 and later. RewriteRule Directive Description: Syntax: Context: Override: Status: Module: Defines rules for the rewriting engine RewriteRule Pattern Substitution [flags] server config, virtual host, directory, .htaccess FileInfo Extension mod rewrite The R EWRITE RULE directive is the real rewriting workhorse. The directive can occur more than once, with each instance defining a single rewrite rule. The order in which these rules are defined is important - this is the order in which they will be applied at run-time. Pattern is a perl compatible regular expression. On the first RewriteRule, it is matched against the (%-decoded) URLpath (p. 377) of the request, or, in per-directory context (see below), the URL path relative to that per-directory context. Subsequent patterns are matched against the output of the last matching RewriteRule. =⇒What is matched? In V H context, The Pattern will initially be matched against the part of the URL IRTUAL OST after the hostname and port, and before the query string (e.g. "/app1/index.html"). In D IRECTORY and htaccess context, the Pattern will initially be matched against the filesystem path, after removing the prefix that led the server to the current R EWRITE RULE (e.g. "app1/index.html" or "index.html" depending on where the directives are defined). If you wish to match against the hostname, port, or query string, use a R EWRITE C OND with the %{HTTP HOST}, %{SERVER PORT}, or %{QUERY STRING} variables respectively. In any case, remember that regular expressions are substring matches. That is, you don’t need the regex to describe the entire string, just the part that you wish to match. Thus, using a regex of . is often sufficient rather than .*, and the regex abc is not the same as ˆabc$. 10.100. APACHE MODULE MOD REWRITE 877 =⇒Per-directory Rewrites • The rewrite engine may be used in .htaccess (p. 249) files and in sections, with some additional complexity. • To enable the rewrite engine in this context, you need to set "RewriteEngine On" and "Options FollowSymLinks" must be enabled. If your administrator has disabled override of FollowSymLinks for a user’s directory, then you cannot use the rewrite engine. This restriction is required for security reasons. • When using the rewrite engine in .htaccess files the per-directory prefix (which always is the same for a specific directory) is automatically removed for the RewriteRule pattern matching and automatically added after any relative (not starting with a slash or protocol name) substitution encounters the end of a rule set. See the R EWRITE BASE directive for more information regarding what prefix will be added back to relative substitutions. • If you wish to match against the full URL-path in a per-directory (htaccess) RewriteRule, use the %{REQUEST URI} variable in a R EWRITE C OND. • The removed prefix always ends with a slash, meaning the matching occurs against a string which never has a leading slash. Therefore, a Pattern with ˆ/ never matches in per-directory context. • Although rewrite rules are syntactically permitted in and sections (including their regular expression counterparts), this should never be necessary and is unsupported. A likely feature to break in these contexts is relative substitutions. For some hints on regular expressions, see the mod rewrite Introduction (p. 147) . In mod rewrite, the NOT character (’!’) is also available as a possible pattern prefix. This enables you to negate a pattern; to say, for instance: “if the current URL does NOT match this pattern”. This can be used for exceptional cases, where it is easier to match the negative pattern, or as a last default rule. =⇒Note When using the NOT character to negate a pattern, you cannot include grouped wildcard parts in that pattern. This is because, when the pattern does NOT match (ie, the negation matches), there are no contents for the groups. Thus, if negated patterns are used, you cannot use $N in the substitution string! The Substitution of a rewrite rule is the string that replaces the original URL-path that was matched by Pattern. The Substitution may be a: file-system path Designates the location on the file-system of the resource to be delivered to the client. Substitutions are only treated as a file-system path when the rule is configured in server (virtualhost) context and the first component of the path in the substitution exists in the file-system URL-path A D OCUMENT ROOT-relative path to the resource to be served. Note that MOD REWRITE tries to guess whether you have specified a file-system path or a URL-path by checking to see if the first segment of the path exists at the root of the file-system. For example, if you specify a Substitution string of /www/file.html, then this will be treated as a URL-path unless a directory named www exists at the root or your file-system (or, in the case of using rewrites in a .htaccess file, relative to your document root), in which case it will be treated as a file-system path. If you wish other URL-mapping directives (such as A LIAS) to be applied to the resulting URL-path, use the [PT] flag as described below. Absolute URL If an absolute URL is specified, MOD REWRITE checks to see whether the hostname matches the current host. If it does, the scheme and hostname are stripped out and the resulting path is treated as a URLpath. Otherwise, an external redirect is performed for the given URL. To force an external redirect back to the current host, see the [R] flag below. 878 CHAPTER 10. APACHE MODULES - (dash) A dash indicates that no substitution should be performed (the existing path is passed through untouched). This is used when a flag (see below) needs to be applied without changing the path. In addition to plain text, the Substitution string can include 1. back-references ($N) to the RewriteRule pattern 2. back-references (%N) to the last matched RewriteCond pattern 3. server-variables as in rule condition test-strings (%{VARNAME}) 4. mapping-function calls (${mapname:key|default}) Back-references are identifiers of the form $N (N=0..9), which will be replaced by the contents of the Nth group of the matched Pattern. The server-variables are the same as for the TestString of a R EWRITE C OND directive. The mapping-functions come from the R EWRITE M AP directive and are explained there. These three types of variables are expanded in the order above. Rewrite rules are applied to the results of previous rewrite rules, in the order in which they are defined in the config file. The URL-path or file-system path (see "What is matched?", above) is completely replaced by the Substitution and the rewriting process continues until all rules have been applied, or it is explicitly terminated by an L flag (p. 178) , or other flag which implies immediate termination, such as END or F. =⇒Modifying the Query String By default, the query string is passed through unchanged. You can, however, create URLs in the substitution string containing a query string part. Simply use a question mark inside the substitution string to indicate that the following text should be re-injected into the query string. When you want to erase an existing query string, end the substitution string with just a question mark. To combine new and old query strings, use the [QSA] flag. Additionally you can set special actions to be performed by appending [flags] as the third argument to the R EWRITE RULE directive. Flags is a comma-separated list, surround by square brackets, of any of the flags in the following table. More details, and examples, for each flag, are available in the Rewrite Flags document (p. 178) . Flag and syntax Function B Escape non-alphanumeric characters in backreferences before applying the transformation. details ... (p. 178) If backreferences are being escaped, spaces should be escaped to %20 instead of +. Useful when the backreference will be used in the path component rather than the query string.details ... (p. 178) Rule is chained to the following rule. If the rule fails, the rule(s) chained to it will be skipped. details ... (p. 178) Sets a cookie in the client browser. Full syntax is: CO=NAME:VAL:domain[:lifetime[:path[:secure[:httponly]]]] details ... (p. 178) Causes the PATH INFO portion of the rewritten URI to be discarded. details ... (p. 178) Stop the rewriting process immediately and don’t apply any more rules. Also prevents further execution of rewrite rules in per-directory and .htaccess context. (Available in 2.3.9 and later) details ... (p. 178) Causes an environment variable VAR to be set (to the value VAL if provided). The form !VAR causes the environment variable VAR to be unset. details ... (p. 178) Returns a 403 FORBIDDEN response to the client browser. details ... (p. 178) backrefnoplus—BNP chain—C cookie—CO=NAME:VAL discardpath—DPI END env—E=[!]VAR[:VAL] forbidden—F 10.100. APACHE MODULE MOD REWRITE gone—G Handler—H=Content-handler last—L next—N nocase—NC noescape—NE nosubreq—NS proxy—P passthrough—PT qsappend—QSA qsdiscard—QSD qslast—QSL redirect—R[=code] skip—S=num type—T=MIME-type 879 Returns a 410 GONE response to the client browser. details ... (p. 178) Causes the resulting URI to be sent to the specified Contenthandler for processing. details ... (p. 178) Stop the rewriting process immediately and don’t apply any more rules. Especially note caveats for per-directory and .htaccess context (see also the END flag). details ... (p. 178) Re-run the rewriting process, starting again with the first rule, using the result of the ruleset so far as a starting point. details ... (p. 178) Makes the pattern comparison case-insensitive. details ... (p. 178) Prevent mod rewrite from applying hexcode escaping of special characters in the result of the rewrite. details ... (p. 178) Causes a rule to be skipped if the current request is an internal sub-request. details ... (p. 178) Force the substitution URL to be internally sent as a proxy request. details ... (p. 178) Forces the resulting URI to be passed back to the URL mapping engine for processing of other URI-to-filename translators, such as Alias or Redirect. details ... (p. 178) Appends any query string from the original request URL to any query string created in the rewrite target.details ... (p. 178) Discard any query string attached to the incoming URI. details ... (p. 178) Interpret the last (right-most) question mark as the query string delimeter, instead of the first (left-most) as normally used. Available in 2.4.19 and later. details ... (p. 178) Forces an external redirect, optionally with the specified HTTP status code. details ... (p. 178) Tells the rewriting engine to skip the next num rules if the current rule matches. details ... (p. 178) Force the MIME-type of the target file to be the specified type. details ... (p. 178) =⇒Home directory expansion When the substitution string begins with a string resembling "/˜user" (via explicit text or backreferences), mod rewrite performs home directory expansion independent of the presence or configuration of MOD USERDIR. This expansion does not occur when the PT flag is used on the R EWRITE RULE directive. Here are all possible substitution combinations and their meanings: Inside per-server configuration (httpd.conf) for request “GET /somepath/pathinfo”: 880 CHAPTER 10. APACHE MODULES Given Rule Resulting Substitution ˆ/somepath(.*) otherpath$1 ˆ/somepath(.*) otherpath$1 [R] ˆ/somepath(.*) otherpath$1 [P] ˆ/somepath(.*) /otherpath$1 ˆ/somepath(.*) /otherpath$1 [R] ˆ/somepath(.*) /otherpath$1 [P] ˆ/somepath(.*) http://thishost/otherpath$1 ˆ/somepath(.*) http://thishost/otherpath$1 [R] ˆ/somepath(.*) http://thishost/otherpath$1 [P] ˆ/somepath(.*) http://otherhost/otherpath$1 ˆ/somepath(.*) http://otherhost/otherpath$1 [R] invalid, not supported invalid, not supported invalid, not supported /otherpath/pathinfo http://thishost/otherpath/pathinfo via external redirection doesn’t make sense, not supported /otherpath/pathinfo http://thishost/otherpath/pathinfo via external redirection doesn’t make sense, not supported http://otherhost/otherpath/pathinfo via external redirection http://otherhost/otherpath/pathinfo via external redirection (the [R] flag is redundant) http://otherhost/otherpath/pathinfo via internal proxy ˆ/somepath(.*) http://otherhost/otherpath$1 [P] Inside per-directory configuration for /somepath (/physical/path/to/somepath/.htaccess, with RewriteBase "/somepath") for request “GET /somepath/localpath/pathinfo”: Given Rule Resulting Substitution ˆlocalpath(.*) otherpath$1 ˆlocalpath(.*) otherpath$1 [R] /somepath/otherpath/pathinfo http://thishost/somepath/otherpath/pathinfo via external redirection doesn’t make sense, not supported /otherpath/pathinfo http://thishost/otherpath/pathinfo via external redirection doesn’t make sense, not supported /otherpath/pathinfo http://thishost/otherpath/pathinfo via external redirection doesn’t make sense, not supported http://otherhost/otherpath/pathinfo via external redirection http://otherhost/otherpath/pathinfo via external redirection (the [R] flag is redundant) http://otherhost/otherpath/pathinfo via internal proxy ˆlocalpath(.*) otherpath$1 [P] ˆlocalpath(.*) /otherpath$1 ˆlocalpath(.*) /otherpath$1 [R] ˆlocalpath(.*) /otherpath$1 [P] ˆlocalpath(.*) http://thishost/otherpath$1 ˆlocalpath(.*) http://thishost/otherpath$1 [R] ˆlocalpath(.*) http://thishost/otherpath$1 [P] ˆlocalpath(.*) http://otherhost/otherpath$1 ˆlocalpath(.*) http://otherhost/otherpath$1 [R] ˆlocalpath(.*) http://otherhost/otherpath$1 [P] 10.101. APACHE MODULE MOD SED 10.101 881 Apache Module mod sed Description: Status: ModuleIdentifier: SourceFile: Compatibility: Filter Input (request) and Output (response) content using sed syntax Experimental sed module mod sed.c sed0.c sed1.c regexp.c regexp.h sed.h Available in Apache 2.3 and later Summary MOD SED is an in-process content filter. The MOD SED filter implements the sed editing commands implemented by the Solaris 10 sed program as described in the manual page80 . However, unlike sed, MOD SED doesn’t take data from standard input. Instead, the filter acts on the entity data sent between client and server. MOD SED can be used as an input or output filter. MOD SED is a content filter, which means that it cannot be used to modify client or server http headers. The MOD SED output filter accepts a chunk of data, executes the sed scripts on the data, and generates the output which is passed to the next filter in the chain. The MOD SED input filter reads the data from the next filter in the chain, executes the sed scripts, and returns the generated data to the caller filter in the filter chain. Both the input and output filters only process the data if newline characters are seen in the content. At the end of the data, the rest of the data is treated as the last line. A tutorial article on MOD SED, and why it is more powerful than simple string or regular expression search and replace, is available on the author’s blog81 . Directives • InputSed • OutputSed Sample Configuration Adding an output filter # In the following example, the sed filter will change the string # "monday" to "MON" and the string "sunday" to SUN in html documents # before sending to the client. AddOutputFilter Sed html OutputSed "s/monday/MON/g" OutputSed "s/sunday/SUN/g" 80 http://www.gnu.org/software/sed/manual/sed.txt 81 https://blogs.oracle.com/basant/entry/using mod sed to filter 882 CHAPTER 10. APACHE MODULES Adding an input filter # In the following example, the sed filter will change the string # "monday" to "MON" and the string "sunday" to SUN in the POST data # sent to PHP. AddInputFilter Sed php InputSed "s/monday/MON/g" InputSed "s/sunday/SUN/g" Sed Commands Complete details of the sed command can be found from the sed manual page82 . b Branch to the label specified (similar to goto). h Copy the current line to the hold buffer. H Append the current line to the hold buffer. g Copy the hold buffer to the current line. G Append the hold buffer to the current line. x Swap the contents of the hold buffer and the current line. InputSed Directive Description: Syntax: Context: Status: Module: Sed command to filter request data (typically POST data) InputSed sed-command directory, .htaccess Experimental mod sed The I NPUT S ED directive specifies the sed command to execute on the request data e.g., POST data. OutputSed Directive Description: Syntax: Context: Status: Module: Sed command for filtering response content OutputSed sed-command directory, .htaccess Experimental mod sed The O UTPUT S ED directive specifies the sed command to execute on the response. 82 http://www.gnu.org/software/sed/manual/sed.txt 10.102. APACHE MODULE MOD SESSION 10.102 883 Apache Module mod session Description: Status: ModuleIdentifier: SourceFile: Compatibility: Session support Extension session module mod session.c Available in Apache 2.3 and later Summary ! Warning The session modules make use of HTTP cookies, and as such can fall victim to Cross Site Scripting attacks, or expose potentially private information to clients. Please ensure that the relevant risks have been taken into account before enabling the session functionality on your server. This module provides support for a server wide per user session interface. Sessions can be used for keeping track of whether a user has been logged in, or for other per user information that should be kept available across requests. Sessions may be stored on the server, or may be stored on the browser. Sessions may also be optionally encrypted for added security. These features are divided into several modules in addition to MOD SESSION; MOD SESSION CRYPTO, MOD SESSION COOKIE and MOD SESSION DBD . Depending on the server requirements, load the appropriate modules into the server (either statically at compile time or dynamically via the L OAD M ODULE directive). Sessions may be manipulated from other modules that depend on the session, or the session may be read from and written to using environment variables and HTTP headers, as appropriate. Directives • Session • SessionEnv • SessionExclude • SessionExpiryUpdateInterval • SessionHeader • SessionInclude • SessionMaxAge See also • MOD SESSION COOKIE • MOD SESSION CRYPTO • MOD SESSION DBD What is a session? At the core of the session interface is a table of key and value pairs that are made accessible across browser requests. These pairs can be set to any valid string, as needed by the application making use of the session. The "session" is a application/x-www-form-urlencoded string containing these key value pairs, as defined by the HTML specification83 . 83 http://www.w3.org/TR/html4/ 884 CHAPTER 10. APACHE MODULES The session can optionally be encrypted and base64 encoded before being written to the storage mechanism, as defined by the administrator. Who can use a session? The session interface is primarily developed for the use by other server modules, such as MOD AUTH FORM, however CGI based applications can optionally be granted access to the contents of the session via the HTTP SESSION environment variable. Sessions have the option to be modified and/or updated by inserting an HTTP response header containing the new session parameters. Keeping sessions on the server Apache can be configured to keep track of per user sessions stored on a particular server or group of servers. This functionality is similar to the sessions available in typical application servers. If configured, sessions are tracked through the use of a session ID that is stored inside a cookie, or extracted from the parameters embedded within the URL query string, as found in a typical GET request. As the contents of the session are stored exclusively on the server, there is an expectation of privacy of the contents of the session. This does have performance and resource implications should a large number of sessions be present, or where a large number of webservers have to share sessions with one another. The MOD SESSION DBD module allows the storage of user sessions within a SQL database via MOD DBD. Keeping sessions on the browser In high traffic environments where keeping track of a session on a server is too resource intensive or inconvenient, the option exists to store the contents of the session within a cookie on the client browser instead. This has the advantage that minimal resources are required on the server to keep track of sessions, and multiple servers within a server farm have no need to share session information. The contents of the session however are exposed to the client, with a corresponding risk of a loss of privacy. The MOD SESSION CRYPTO module can be configured to encrypt the contents of the session before writing the session to the client. The MOD SESSION COOKIE allows the storage of user sessions on the browser within an HTTP cookie. Basic Examples Creating a session is as simple as turning the session on, and deciding where the session will be stored. In this example, the session will be stored on the browser, in a cookie called session. Browser based session Session On SessionCookieName session path=/ The session is not useful unless it can be written to or read from. The following example shows how values can be injected into the session through the use of a predetermined HTTP response header called X-Replace-Session. Writing to a session Session On SessionCookieName session path=/ SessionHeader X-Replace-Session 10.102. APACHE MODULE MOD SESSION 885 The header should contain name value pairs expressed in the same format as a query string in a URL, as in the example below. Setting a key to the empty string has the effect of removing that key from the session. CGI to write to a session #!/bin/bash echo "Content-Type: text/plain" echo "X-Replace-Session: key1=foo&key2=&key3=bar" echo env If configured, the session can be read back from the HTTP SESSION environment variable. By default, the session is kept private, so this has to be explicitly turned on with the S ESSION E NV directive. Read from a session Session On SessionEnv On SessionCookieName session path=/ SessionHeader X-Replace-Session Once read, the CGI variable HTTP SESSION should contain the value key1=foo&key3=bar. Session Privacy Using the "show cookies" feature of your browser, you would have seen a clear text representation of the session. This could potentially be a problem should the end user need to be kept unaware of the contents of the session, or where a third party could gain unauthorised access to the data within the session. The contents of the session can be optionally encrypted before being placed on the browser using the MOD SESSION CRYPTO module. Browser based encrypted session Session On SessionCryptoPassphrase secret SessionCookieName session path=/ The session will be automatically decrypted on load, and encrypted on save by Apache, the underlying application using the session need have no knowledge that encryption is taking place. Sessions stored on the server rather than on the browser can also be encrypted as needed, offering privacy where potentially sensitive information is being shared between webservers in a server farm using the MOD SESSION DBD module. Cookie Privacy The HTTP cookie mechanism also offers privacy features, such as the ability to restrict cookie transport to SSL protected pages only, or to prevent browser based javascript from gaining access to the contents of the cookie. ! Warning Some of the HTTP cookie privacy features are either non-standard, or are not implemented consistently across browsers. The session modules allow you to set cookie parameters, but it makes no guarantee that privacy will be respected by the browser. If security is a concern, use the MOD SESSION CRYPTO to encrypt the contents of the session, or store the session on the server using the MOD SESSION DBD module. 886 CHAPTER 10. APACHE MODULES Standard cookie parameters can be specified after the name of the cookie, as in the example below. Setting cookie parameters Session On SessionCryptoPassphrase secret SessionCookieName session path=/private;domain=example.com;httponly;secure; In cases where the Apache server forms the frontend for backend origin servers, it is possible to have the session cookies removed from the incoming HTTP headers using the S ESSION C OOKIE R EMOVE directive. This keeps the contents of the session cookies from becoming accessible from the backend server. Session Support for Authentication As is possible within many application servers, authentication modules can use a session for storing the username and password after login. The MOD AUTH FORM saves the user’s login name and password within the session. Form based authentication Session On SessionCryptoPassphrase secret SessionCookieName session path=/ AuthFormProvider file AuthUserFile "conf/passwd" AuthType form AuthName "realm" #... See the MOD AUTH FORM module for documentation and complete examples. Integrating Sessions with External Applications In order for sessions to be useful, it must be possible to share the contents of a session with external applications, and it must be possible for an external application to write a session of its own. A typical example might be an application that changes a user’s password set by MOD AUTH FORM. This application would need to read the current username and password from the session, make the required changes to the user’s password, and then write the new password to the session in order to provide a seamless transition to the new password. A second example might involve an application that registers a new user for the first time. When registration is complete, the username and password is written to the session, providing a seamless transition to being logged in. Apache modules Modules within the server that need access to the session can use the mod session.h API in order to read from and write to the session. This mechanism is used by modules like MOD AUTH FORM. CGI programs and scripting languages Applications that run within the webserver can optionally retrieve the value of the session from the HTTP SESSION environment variable. The session should be encoded as a application/x-www-form-urlencoded string as described by the HTML specification84 . The environment variable is controlled by the setting of the S ESSION E NV directive. The session can be written to by the script by returning a application/x-www-form-urlencoded response header with a name set by the S ESSION H EADER directive. In both cases, any encryption or decryption, and the reading the session from or writing the session to the chosen storage mechanism is handled by the MOD SESSION modules and corresponding configuration. 84 http://www.w3.org/TR/html4/ 10.102. APACHE MODULE MOD SESSION 887 Applications behind MOD PROXY If the S ESSION H EADER directive is used to define an HTTP request header, the session, encoded as a application/x-www-form-urlencoded string, will be made available to the application. If the same header is provided in the response, the value of this response header will be used to replace the session. As above, any encryption or decryption, and the reading the session from or writing the session to the chosen storage mechanism is handled by the MOD SESSION modules and corresponding configuration. Standalone applications Applications might choose to manipulate the session outside the control of the Apache HTTP server. In this case, it is the responsibility of the application to read the session from the chosen storage mechanism, decrypt the session, update the session, encrypt the session and write the session to the chosen storage mechanism, as appropriate. Session Directive Description: Syntax: Default: Context: Override: Status: Module: Enables a session for the current directory or location Session On|Off Session Off server config, virtual host, directory, .htaccess AuthConfig Extension mod session The S ESSION directive enables a session for the directory or location container. Further directives control where the session will be stored and how privacy is maintained. SessionEnv Directive Description: Syntax: Default: Context: Override: Status: Module: Control whether the contents of the session are written to the HTTP SESSION environment variable SessionEnv On|Off SessionEnv Off server config, virtual host, directory, .htaccess AuthConfig Extension mod session If set to On, the S ESSION E NV directive causes the contents of the session to be written to a CGI environment variable called HTTP SESSION. The string is written in the URL query format, for example: key1=foo&key3=bar SessionExclude Directive Description: Syntax: Default: Context: Status: Module: Define URL prefixes for which a session is ignored SessionExclude path none server config, virtual host, directory, .htaccess Extension mod session The S ESSION E XCLUDE directive allows sessions to be disabled relative to URL prefixes only. This can be used to make a website more efficient, by targeting a more precise URL space for which a session should be maintained. By 888 CHAPTER 10. APACHE MODULES default, all URLs within the directory or location are included in the session. The S ESSION E XCLUDE directive takes precedence over the S ESSION I NCLUDE directive. ! Warning This directive has a similar purpose to the path attribute in HTTP cookies, but should not be confused with this attribute. This directive does not set the path attribute, which must be configured separately. SessionExpiryUpdateInterval Directive Description: Syntax: Default: Context: Status: Module: Define the number of seconds a session’s expiry may change without the session being updated SessionExpiryUpdateInterval interval SessionExpiryUpdateInterval 0 (always update) server config, virtual host, directory, .htaccess Extension mod session The S ESSION E XPIRY U PDATE I NTERVAL directive allows sessions to avoid the cost associated with writing the session each request when only the expiry time has changed. This can be used to make a website more efficient or reduce load on a database when using MOD SESSION DBD. The session is always written if the data stored in the session has changed or the expiry has changed by more than the configured interval. Setting the interval to zero disables this directive, and the session expiry is refreshed for each request. This directive only has an effect when combined with S ESSION M AX AGE to enable session expiry. Sessions without an expiry are only written when the data stored in the session has changed. ! Warning Because the session expiry may not be refreshed with each request, it’s possible for sessions to expire up to interval seconds early. Using a small interval usually provides sufficient savings while having a minimal effect on expiry resolution. SessionHeader Directive Description: Syntax: Default: Context: Override: Status: Module: Import session updates from a given HTTP response header SessionHeader header none server config, virtual host, directory, .htaccess AuthConfig Extension mod session The S ESSION H EADER directive defines the name of an HTTP response header which, if present, will be parsed and written to the current session. The header value is expected to be in the URL query format, for example: key1=foo&key2=&key3=bar Where a key is set to the empty string, that key will be removed from the session. 10.102. APACHE MODULE MOD SESSION 889 SessionInclude Directive Description: Syntax: Default: Context: Override: Status: Module: Define URL prefixes for which a session is valid SessionInclude path all URLs server config, virtual host, directory, .htaccess AuthConfig Extension mod session The S ESSION I NCLUDE directive allows sessions to be made valid for specific URL prefixes only. This can be used to make a website more efficient, by targeting a more precise URL space for which a session should be maintained. By default, all URLs within the directory or location are included in the session. ! Warning This directive has a similar purpose to the path attribute in HTTP cookies, but should not be confused with this attribute. This directive does not set the path attribute, which must be configured separately. SessionMaxAge Directive Description: Syntax: Default: Context: Override: Status: Module: Define a maximum age in seconds for a session SessionMaxAge maxage SessionMaxAge 0 server config, virtual host, directory, .htaccess AuthConfig Extension mod session The S ESSION M AX AGE directive defines a time limit for which a session will remain valid. When a session is saved, this time limit is reset and an existing session can be continued. If a session becomes older than this limit without a request to the server to refresh the session, the session will time out and be removed. Where a session is used to stored user login details, this has the effect of logging the user out automatically after the given time. Setting the maxage to zero disables session expiry. 890 CHAPTER 10. APACHE MODULES 10.103 Apache Module mod session cookie Description: Status: ModuleIdentifier: SourceFile: Compatibility: Cookie based session support Extension session cookie module mod session cookie.c Available in Apache 2.3 and later Summary ! Warning The session modules make use of HTTP cookies, and as such can fall victim to Cross Site Scripting attacks, or expose potentially private information to clients. Please ensure that the relevant risks have been taken into account before enabling the session functionality on your server. This submodule of MOD SESSION provides support for the storage of user sessions on the remote browser within HTTP cookies. Using cookies to store a session removes the need for the server or a group of servers to store the session locally, or collaborate to share a session, and can be useful for high traffic environments where a server based session might be too resource intensive. If session privacy is required, the MOD SESSION CRYPTO module can be used to encrypt the contents of the session before writing the session to the client. For more details on the session interface, see the documentation for the MOD SESSION module. Directives • SessionCookieName • SessionCookieName2 • SessionCookieRemove See also • MOD SESSION • MOD SESSION CRYPTO • MOD SESSION DBD Basic Examples To create a simple session and store it in a cookie called session, configure the session as follows: Browser based session Session On SessionCookieName session path=/ For more examples on how the session can be configured to be read from and written to by a CGI application, see the MOD SESSION examples section. For documentation on how the session can be used to store username and password details, see the MOD AUTH FORM module. 10.103. APACHE MODULE MOD SESSION COOKIE 891 SessionCookieName Directive Description: Syntax: Default: Context: Status: Module: Name and attributes for the RFC2109 cookie storing the session SessionCookieName name attributes none server config, virtual host, directory, .htaccess Extension mod session cookie The S ESSION C OOKIE NAME directive specifies the name and optional attributes of an RFC2109 compliant cookie inside which the session will be stored. RFC2109 cookies are set using the Set-Cookie HTTP header. An optional list of cookie attributes can be specified, as per the example below. These attributes are inserted into the cookie as is, and are not interpreted by Apache. Ensure that your attributes are defined correctly as per the cookie specification. Cookie with attributes Session On SessionCookieName session path=/private;domain=example.com;httponly;secure;version=1; SessionCookieName2 Directive Description: Syntax: Default: Context: Status: Module: Name and attributes for the RFC2965 cookie storing the session SessionCookieName2 name attributes none server config, virtual host, directory, .htaccess Extension mod session cookie The S ESSION C OOKIE NAME 2 directive specifies the name and optional attributes of an RFC2965 compliant cookie inside which the session will be stored. RFC2965 cookies are set using the Set-Cookie2 HTTP header. An optional list of cookie attributes can be specified, as per the example below. These attributes are inserted into the cookie as is, and are not interpreted by Apache. Ensure that your attributes are defined correctly as per the cookie specification. Cookie2 with attributes Session On SessionCookieName2 session path=/private;domain=example.com;httponly;secure;version=1; SessionCookieRemove Directive Description: Syntax: Default: Context: Status: Module: Control for whether session cookies should be removed from incoming HTTP headers SessionCookieRemove On|Off SessionCookieRemove Off server config, virtual host, directory, .htaccess Extension mod session cookie The S ESSION C OOKIE R EMOVE flag controls whether the cookies containing the session will be removed from the headers during request processing. 892 CHAPTER 10. APACHE MODULES In a reverse proxy situation where the Apache server acts as a server frontend for a backend origin server, revealing the contents of the session cookie to the backend could be a potential privacy violation. When set to on, the session cookie will be removed from the incoming HTTP headers. 10.104. APACHE MODULE MOD SESSION CRYPTO 10.104 893 Apache Module mod session crypto Description: Status: ModuleIdentifier: SourceFile: Compatibility: Session encryption support Experimental session crypto module mod session crypto.c Available in Apache 2.3 and later Summary ! Warning The session modules make use of HTTP cookies, and as such can fall victim to Cross Site Scripting attacks, or expose potentially private information to clients. Please ensure that the relevant risks have been taken into account before enabling the session functionality on your server. This submodule of MOD SESSION provides support for the encryption of user sessions before being written to a local database, or written to a remote browser via an HTTP cookie. This can help provide privacy to user sessions where the contents of the session should be kept private from the user, or where protection is needed against the effects of cross site scripting attacks. For more details on the session interface, see the documentation for the MOD SESSION module. Directives • SessionCryptoCipher • SessionCryptoDriver • SessionCryptoPassphrase • SessionCryptoPassphraseFile See also • MOD SESSION • MOD SESSION COOKIE • MOD SESSION DBD Basic Usage To create a simple encrypted session and store it in a cookie called session, configure the session as follows: Browser based encrypted session Session On SessionCookieName session path=/ SessionCryptoPassphrase secret The session will be encrypted with the given key. Different servers can be configured to share sessions by ensuring the same encryption key is used on each server. If the encryption key is changed, sessions will be invalidated automatically. For documentation on how the session can be used to store username and password details, see the MOD AUTH FORM module. 894 CHAPTER 10. APACHE MODULES SessionCryptoCipher Directive Description: Syntax: Default: Context: Status: Module: Compatibility: The crypto cipher to be used to encrypt the session SessionCryptoCipher name aes256 server config, virtual host, directory, .htaccess Experimental mod session crypto Available in Apache 2.3.0 and later The S ESSION C RYPTO C IPHER directive allows the cipher to be used during encryption. If not specified, the cipher defaults to aes256. Possible values depend on the crypto driver in use, and could be one of: • 3des192 • aes128 • aes192 • aes256 SessionCryptoDriver Directive Description: Syntax: Default: Context: Status: Module: Compatibility: The crypto driver to be used to encrypt the session SessionCryptoDriver name [param[=value]] none server config Experimental mod session crypto Available in Apache 2.3.0 and later The S ESSION C RYPTO D RIVER directive specifies the name of the crypto driver to be used for encryption. If not specified, the driver defaults to the recommended driver compiled into APR-util. The NSS crypto driver requires some parameters for configuration, which are specified as parameters with optional values after the driver name. NSS without a certificate database SessionCryptoDriver nss NSS with certificate database SessionCryptoDriver nss dir=certs NSS with certificate database and parameters SessionCryptoDriver nss dir=certs key3=key3.db cert7=cert7.db secmod=secmod NSS with paths containing spaces SessionCryptoDriver nss "dir=My Certs" key3=key3.db cert7=cert7.db secmod=secmod 10.104. APACHE MODULE MOD SESSION CRYPTO 895 The NSS crypto driver might have already been configured by another part of the server, for example from mod nss or MOD LDAP. If found to have already been configured, a warning will be logged, and the existing configuration will have taken affect. To avoid this warning, use the noinit parameter as follows. NSS with certificate database SessionCryptoDriver nss noinit To prevent confusion, ensure that all modules requiring NSS are configured with identical parameters. The openssl crypto driver supports an optional parameter to specify the engine to be used for encryption. OpenSSL with engine support SessionCryptoDriver openssl engine=name SessionCryptoPassphrase Directive Description: Syntax: Default: Context: Status: Module: Compatibility: The key used to encrypt the session SessionCryptoPassphrase secret [ secret ... none server config, virtual host, directory, .htaccess Experimental mod session crypto Available in Apache 2.3.0 and later ] The S ESSION C RYPTO PASSPHRASE directive specifies the keys to be used to enable symmetrical encryption on the contents of the session before writing the session, or decrypting the contents of the session after reading the session. Keys are more secure when they are long, and consist of truly random characters. Changing the key on a server has the effect of invalidating all existing sessions. Multiple keys can be specified in order to support key rotation. The first key listed will be used for encryption, while all keys listed will be attempted for decryption. To rotate keys across multiple servers over a period of time, add a new secret to the end of the list, and once rolled out completely to all servers, remove the first key from the start of the list. As of version 2.4.7 if the value begins with exec: the resulting command will be executed and the first line returned to standard output by the program will be used as the key. #key used as-is SessionCryptoPassphrase secret #Run /path/to/program to get key SessionCryptoPassphrase exec:/path/to/program #Run /path/to/otherProgram and provide arguments SessionCryptoPassphrase "exec:/path/to/otherProgram argument1" 896 CHAPTER 10. APACHE MODULES SessionCryptoPassphraseFile Directive Description: Syntax: Default: Context: Status: Module: Compatibility: File containing keys used to encrypt the session SessionCryptoPassphraseFile filename none server config, virtual host, directory Experimental mod session crypto Available in Apache 2.3.0 and later The S ESSION C RYPTO PASSPHRASE F ILE directive specifies the name of a configuration file containing the keys to use for encrypting or decrypting the session, specified one per line. The file is read on server start, and a graceful restart will be necessary for httpd to pick up changes to the keys. Unlike the S ESSION C RYPTO PASSPHRASE directive, the keys are not exposed within the httpd configuration and can be hidden by protecting the file appropriately. Multiple keys can be specified in order to support key rotation. The first key listed will be used for encryption, while all keys listed will be attempted for decryption. To rotate keys across multiple servers over a period of time, add a new secret to the end of the list, and once rolled out completely to all servers, remove the first key from the start of the list. 10.105. APACHE MODULE MOD SESSION DBD 10.105 897 Apache Module mod session dbd Description: Status: ModuleIdentifier: SourceFile: Compatibility: DBD/SQL based session support Extension session dbd module mod session dbd.c Available in Apache 2.3 and later Summary ! Warning The session modules make use of HTTP cookies, and as such can fall victim to Cross Site Scripting attacks, or expose potentially private information to clients. Please ensure that the relevant risks have been taken into account before enabling the session functionality on your server. This submodule of MOD SESSION provides support for the storage of user sessions within a SQL database using the MOD DBD module. Sessions can either be anonymous, where the session is keyed by a unique UUID string stored on the browser in a cookie, or per user, where the session is keyed against the userid of the logged in user. SQL based sessions are hidden from the browser, and so offer a measure of privacy without the need for encryption. Different webservers within a server farm may choose to share a database, and so share sessions with one another. For more details on the session interface, see the documentation for the MOD SESSION module. Directives • SessionDBDCookieName • SessionDBDCookieName2 • SessionDBDCookieRemove • SessionDBDDeleteLabel • SessionDBDInsertLabel • SessionDBDPerUser • SessionDBDSelectLabel • SessionDBDUpdateLabel See also • MOD SESSION • MOD SESSION CRYPTO • MOD SESSION COOKIE • MOD DBD DBD Configuration Before the MOD SESSION DBD module can be configured to maintain a session, the MOD DBD module must be configured to make the various database queries available to the server. 898 CHAPTER 10. APACHE MODULES There are four queries required to keep a session maintained, to select an existing session, to update an existing session, to insert a new session, and to delete an expired or empty session. These queries are configured as per the example below. Sample DBD configuration DBDriver pgsql DBDParams "dbname=apachesession user=apache password=xxxxx host=localhost" DBDPrepareSQL "delete from session where key = %s" deletesession DBDPrepareSQL "update session set value = %s, expiry = %lld, key = %s where key = %s" update DBDPrepareSQL "insert into session (value, expiry, key) values (%s, %lld, %s)" insertsession DBDPrepareSQL "select value from session where key = %s and (expiry = 0 or expiry > %lld)" s DBDPrepareSQL "delete from session where expiry != 0 and expiry < %lld" cleansession Anonymous Sessions Anonymous sessions are keyed against a unique UUID, and stored on the browser within an HTTP cookie. This method is similar to that used by most application servers to store session information. To create a simple anonymous session and store it in a postgres database table called apachesession, and save the session ID in a cookie called session, configure the session as follows: SQL based anonymous session Session On SessionDBDCookieName session path=/ For more examples on how the session can be configured to be read from and written to by a CGI application, see the MOD SESSION examples section. For documentation on how the session can be used to store username and password details, see the MOD AUTH FORM module. Per User Sessions Per user sessions are keyed against the username of a successfully authenticated user. It offers the most privacy, as no external handle to the session exists outside of the authenticated realm. Per user sessions work within a correctly configured authenticated environment, be that using basic authentication, digest authentication or SSL client certificates. Due to the limitations of who came first, the chicken or the egg, per user sessions cannot be used to store authentication credentials from a module like MOD AUTH FORM. To create a simple per user session and store it in a postgres database table called apachesession, and with the session keyed to the userid, configure the session as follows: SQL based per user session Session On SessionDBDPerUser On 10.105. APACHE MODULE MOD SESSION DBD 899 Database Housekeeping Over the course of time, the database can be expected to start accumulating expired sessions. At this point, the MOD SESSION DBD module is not yet able to handle session expiry automatically. ! Warning The administrator will need to set up an external process via cron to clean out expired sessions. SessionDBDCookieName Directive Description: Syntax: Default: Context: Status: Module: Name and attributes for the RFC2109 cookie storing the session ID SessionDBDCookieName name attributes none server config, virtual host, directory, .htaccess Extension mod session dbd The S ESSION DBDC OOKIE NAME directive specifies the name and optional attributes of an RFC2109 compliant cookie inside which the session ID will be stored. RFC2109 cookies are set using the Set-Cookie HTTP header. An optional list of cookie attributes can be specified, as per the example below. These attributes are inserted into the cookie as is, and are not interpreted by Apache. Ensure that your attributes are defined correctly as per the cookie specification. Cookie with attributes Session On SessionDBDCookieName session path=/private;domain=example.com;httponly;secure;version=1; SessionDBDCookieName2 Directive Description: Syntax: Default: Context: Status: Module: Name and attributes for the RFC2965 cookie storing the session ID SessionDBDCookieName2 name attributes none server config, virtual host, directory, .htaccess Extension mod session dbd The S ESSION DBDC OOKIE NAME 2 directive specifies the name and optional attributes of an RFC2965 compliant cookie inside which the session ID will be stored. RFC2965 cookies are set using the Set-Cookie2 HTTP header. An optional list of cookie attributes can be specified, as per the example below. These attributes are inserted into the cookie as is, and are not interpreted by Apache. Ensure that your attributes are defined correctly as per the cookie specification. Cookie2 with attributes Session On SessionDBDCookieName2 session path=/private;domain=example.com;httponly;secure;version=1; 900 CHAPTER 10. APACHE MODULES SessionDBDCookieRemove Directive Description: Syntax: Default: Context: Status: Module: Control for whether session ID cookies should be removed from incoming HTTP headers SessionDBDCookieRemove On|Off SessionDBDCookieRemove On server config, virtual host, directory, .htaccess Extension mod session dbd The S ESSION DBDC OOKIE R EMOVE flag controls whether the cookies containing the session ID will be removed from the headers during request processing. In a reverse proxy situation where the Apache server acts as a server frontend for a backend origin server, revealing the contents of the session ID cookie to the backend could be a potential privacy violation. When set to on, the session ID cookie will be removed from the incoming HTTP headers. SessionDBDDeleteLabel Directive Description: Syntax: Default: Context: Status: Module: The SQL query to use to remove sessions from the database SessionDBDDeleteLabel label SessionDBDDeleteLabel deletesession server config, virtual host, directory, .htaccess Extension mod session dbd The S ESSION DBDD ELETE L ABEL directive sets the default delete query label to be used to delete an expired or empty session. This label must have been previously defined using the DBDP REPARE SQL directive. SessionDBDInsertLabel Directive Description: Syntax: Default: Context: Status: Module: The SQL query to use to insert sessions into the database SessionDBDInsertLabel label SessionDBDInsertLabel insertsession server config, virtual host, directory, .htaccess Extension mod session dbd The S ESSION DBDI NSERT L ABEL directive sets the default insert query label to be used to load in a session. This label must have been previously defined using the DBDP REPARE SQL directive. If an attempt to update the session affects no rows, this query will be called to insert the session into the database. SessionDBDPerUser Directive Description: Syntax: Default: Context: Status: Module: Enable a per user session SessionDBDPerUser On|Off SessionDBDPerUser Off server config, virtual host, directory, .htaccess Extension mod session dbd The S ESSION DBDP ERU SER flag enables a per user session keyed against the user’s login name. If the user is not logged in, this directive will be ignored. 10.105. APACHE MODULE MOD SESSION DBD 901 SessionDBDSelectLabel Directive Description: Syntax: Default: Context: Status: Module: The SQL query to use to select sessions from the database SessionDBDSelectLabel label SessionDBDSelectLabel selectsession server config, virtual host, directory, .htaccess Extension mod session dbd The S ESSION DBDS ELECT L ABEL directive sets the default select query label to be used to load in a session. This label must have been previously defined using the DBDP REPARE SQL directive. SessionDBDUpdateLabel Directive Description: Syntax: Default: Context: Status: Module: The SQL query to use to update existing sessions in the database SessionDBDUpdateLabel label SessionDBDUpdateLabel updatesession server config, virtual host, directory, .htaccess Extension mod session dbd The S ESSION DBDU PDATE L ABEL directive sets the default update query label to be used to load in a session. This label must have been previously defined using the DBDP REPARE SQL directive. If an attempt to update the session affects no rows, the insert query will be called to insert the session into the database. If the database supports InsertOrUpdate, override this query to perform the update in one query instead of two. 902 CHAPTER 10. APACHE MODULES 10.106 Apache Module mod setenvif Description: Status: ModuleIdentifier: SourceFile: Allows the setting of environment variables based on characteristics of the request Base setenvif module mod setenvif.c Summary The MOD SETENVIF module allows you to set internal environment variables according to whether different aspects of the request match regular expressions you specify. These environment variables can be used by other parts of the server to make decisions about actions to be taken, as well as becoming available to CGI scripts and SSI pages. The directives are considered in the order they appear in the configuration files. So more complex sequences can be used, such as this example, which sets netscape if the browser is mozilla but not MSIE. BrowserMatch ˆMozilla netscape BrowserMatch MSIE !netscape When the server looks up a path via an internal subrequest such as looking for a D IRECTORY I NDEX or generating a directory listing with MOD AUTOINDEX, per-request environment variables are not inherited in the subrequest. Additionally, S ET E NV I F directives are not separately evaluated in the subrequest due to the API phases MOD SETENVIF takes action in. Directives • BrowserMatch • BrowserMatchNoCase • SetEnvIf • SetEnvIfExpr • SetEnvIfNoCase See also • Environment Variables in Apache HTTP Server (p. 92) BrowserMatch Directive Description: Syntax: Context: Override: Status: Module: Sets environment variables conditional on HTTP User-Agent BrowserMatch regex [!]env-variable[=value] [[!]env-variable[=value]] ... server config, virtual host, directory, .htaccess FileInfo Base mod setenvif The B ROWSER M ATCH is a special cases of the S ET E NV I F directive that sets environment variables conditional on the User-Agent HTTP request header. The following two lines have the same effect: BrowserMatch Robot is_a_robot SetEnvIf User-Agent Robot is_a_robot 10.106. APACHE MODULE MOD SETENVIF 903 Some additional examples: BrowserMatch ˆMozilla forms jpeg=yes browser=netscape BrowserMatch "ˆMozilla/[2-3]" tables agif frames javascript BrowserMatch MSIE !javascript BrowserMatchNoCase Directive Description: Syntax: Context: Override: Status: Module: Sets environment variables conditional on User-Agent without respect to case BrowserMatchNoCase regex [!]env-variable[=value] [[!]env-variable[=value]] ... server config, virtual host, directory, .htaccess FileInfo Base mod setenvif The B ROWSER M ATCH N O C ASE directive is semantically identical to the B ROWSER M ATCH directive. However, it provides for case-insensitive matching. For example: BrowserMatchNoCase mac platform=macintosh BrowserMatchNoCase win platform=windows The B ROWSER M ATCH and B ROWSER M ATCH N O C ASE directives are special cases of the S ET E NV I F and S ET E NVI F N O C ASE directives. The following two lines have the same effect: BrowserMatchNoCase Robot is_a_robot SetEnvIfNoCase User-Agent Robot is_a_robot SetEnvIf Directive Description: Syntax: Context: Override: Status: Module: Sets environment variables based on attributes of the request SetEnvIf attribute regex [!]env-variable[=value] [[!]env-variable[=value]] ... server config, virtual host, directory, .htaccess FileInfo Base mod setenvif The S ET E NV I F directive defines environment variables based on attributes of the request. The attribute specified in the first argument can be one of four things: 1. An HTTP request header field (see RFC261685 for more information about these); for example: Host, User-Agent, Referer, and Accept-Language. A regular expression may be used to specify a set of request headers. 2. One of the following aspects of the request: • Remote Host - the hostname (if available) of the client making the request • Remote Addr - the IP address of the client making the request • Server Addr - the IP address of the server on which the request was received (only with versions later than 2.0.43) 85 http://www.rfc-editor.org/rfc/rfc2616.txt 904 CHAPTER 10. APACHE MODULES • Request Method - the name of the method being used (GET, POST, et cetera) • Request Protocol - the name and version of the protocol with which the request was made (e.g., "HTTP/0.9", "HTTP/1.1", etc.) • Request URI - the resource requested on the HTTP request line – generally the portion of the URL following the scheme and host portion without the query string. See the R EWRITE C OND directive of MOD REWRITE for extra information on how to match your query string. 3. The name of an environment variable in the list of those associated with the request. This allows S ET E N V I F directives to test against the result of prior matches. Only those environment variables defined by earlier SetEnvIf[NoCase] directives are available for testing in this manner. ’Earlier’ means that they were defined at a broader scope (such as server-wide) or previously in the current directive’s scope. Environment variables will be considered only if there was no match among request characteristics and a regular expression was not used for the attribute. The second argument (regex) is a regular expression. If the regex matches against the attribute, then the remainder of the arguments are evaluated. The rest of the arguments give the names of variables to set, and optionally values to which they should be set. These take the form of 1. varname, or 2. !varname, or 3. varname=value In the first form, the value will be set to "1". The second will remove the given variable if already defined, and the third will set the variable to the literal value given by value. Since version 2.0.51, Apache httpd will recognize occurrences of $1..$9 within value and replace them by parenthesized subexpressions of regex. $0 provides access to the whole string matched by that pattern. SetEnvIf Request_URI "\.gif$" object_is_image=gif SetEnvIf Request_URI "\.jpg$" object_is_image=jpg SetEnvIf Request_URI "\.xbm$" object_is_image=xbm SetEnvIf Referer www\.mydomain\.example\.com intra_site_referral SetEnvIf object_is_image xbm XBIT_PROCESSING=1 SetEnvIf Request_URI "\.(.*)$" EXTENSION=$1 SetEnvIf ˆTS ˆ[a-z] HAVE_TS The first three will set the environment variable object is image if the request was for an image file, and the fourth sets intra site referral if the referring page was somewhere on the www.mydomain.example.com Web site. The last example will set environment variable HAVE TS if the request contains any headers that begin with "TS" whose values begins with any character in the set [a-z]. See also • Environment Variables in Apache HTTP Server (p. 92) , for additional examples. 10.106. APACHE MODULE MOD SETENVIF 905 SetEnvIfExpr Directive Description: Syntax: Context: Override: Status: Module: Sets environment variables based on an ap expr expression SetEnvIfExpr expr [!]env-variable[=value] [[!]env-variable[=value]] ... server config, virtual host, directory, .htaccess FileInfo Base mod setenvif The S ET E NV I F E XPR directive defines environment variables based on an ap expr. These expressions will be evaluated at runtime, and applied env-variable in the same fashion as S ET E NV I F. SetEnvIfExpr "tolower(req(’X-Sendfile’)) == ’d:\images\very_big.iso’)" iso_delivered This would set the environment variable iso delivered every time our application attempts to send it via X-Sendfile A more useful example would be to set the variable rfc1918 if the remote IP address is a private address according to RFC 1918: SetEnvIfExpr "-R ’10.0.0.0/8’ || -R ’172.16.0.0/12’ || -R ’192.168.0.0/16’" rfc1918 See also • Expressions in Apache HTTP Server (p. 99) , for a complete reference and more examples. • can be used to achieve similar results. • MOD FILTER SetEnvIfNoCase Directive Description: Syntax: Context: Override: Status: Module: Sets environment variables based on attributes of the request without respect to case SetEnvIfNoCase attribute regex [!]env-variable[=value] [[!]env-variable[=value]] ... server config, virtual host, directory, .htaccess FileInfo Base mod setenvif The S ET E NV I F N O C ASE is semantically identical to the S ET E NV I F directive, and differs only in that the regular expression matching is performed in a case-insensitive manner. For example: SetEnvIfNoCase Host Example\.Org site=example This will cause the site environment variable to be set to "example" if the HTTP request header field Host: was included and contained Example.Org, example.org, or any other combination. 906 10.107 CHAPTER 10. APACHE MODULES Apache Module mod slotmem plain Description: Status: ModuleIdentifier: SourceFile: Slot-based shared memory provider. Extension slotmem plain module mod slotmem plain.c Summary mod slotmem plain is a memory provider which provides for creation and access to a plain memory segment in which the datasets are organized in "slots." If the memory needs to be shared between threads and processes, a better provider would be MOD SLOTMEM SHM. mod slotmem plain provides the following API functions: apr status t doall(ap slotmem instance t *s, ap slotmem callback fn t *func, void *data, apr pool t *pool) call the callback on all worker slots apr status t create(ap slotmem instance t **new, const char *name, apr size t item size, unsigned int item num, ap slotmem ty create a new slotmem with each item size is item size. apr status t attach(ap slotmem instance t **new, const char *name, apr size t *item size, unsigned int *item num, apr pool t * attach to an existing slotmem. apr status t dptr(ap slotmem instance t *s, unsigned int item id, void**mem) get the direct pointer to the memory associated with this worker slot. apr status t get(ap slotmem instance t *s, unsigned int item id, unsigned char *dest, apr size t dest len) get/read the memory from this slot to dest apr status t put(ap slotmem instance t *slot, unsigned int item id, unsigned char *src, apr size t src len) put/write the data from src to this slot unsigned int num slots(ap slotmem instance t *s) return the total number of slots in the segment apr size t slot size(ap slotmem instance t *s) return the total data size, in bytes, of a slot in the segment apr status t grab(ap slotmem instance t *s, unsigned int *item id); grab or allocate the first free slot and mark as in-use (does not do any data copying) apr status t fgrab(ap slotmem instance t *s, unsigned int item id); forced grab or allocate the specified slot and mark as in-use (does not do any data copying) apr status t release(ap slotmem instance t *s, unsigned int item id); release or free a slot and mark as not in-use (does not do any data copying) Directives This module provides no directives. 10.108. APACHE MODULE MOD SLOTMEM SHM 10.108 907 Apache Module mod slotmem shm Description: Status: ModuleIdentifier: SourceFile: Slot-based shared memory provider. Extension slotmem shm module mod slotmem shm.c Summary mod slotmem shm is a memory provider which provides for creation and access to a shared memory segment in which the datasets are organized in "slots." All shared memory is cleared and cleaned with each restart, whether graceful or not. The data itself is stored and restored within a file noted by the name parameter in the create and attach calls. If not specified with an absolute path, the file will be created relative to the path specified by the D EFAULT RUNTIME D IR directive. mod slotmem shm provides the following API functions: apr status t doall(ap slotmem instance t *s, ap slotmem callback fn t *func, void *data, apr pool t *pool) call the callback on all worker slots apr status t create(ap slotmem instance t **new, const char *name, apr size t item size, unsigned int item num, ap slotmem ty create a new slotmem with each item size is item size. name is used to generate a filename for the persistent store of the shared memory if configured. Values are: "none" Anonymous shared memory and no persistent store "file-name" [DefaultRuntimeDir]/file-name "/absolute-file-name" Absolute file name apr status t attach(ap slotmem instance t **new, const char *name, apr size t *item size, unsigned int *item num, apr pool t * attach to an existing slotmem. See create for description of name parameter. apr status t dptr(ap slotmem instance t *s, unsigned int item id, void**mem) get the direct pointer to the memory associated with this worker slot. apr status t get(ap slotmem instance t *s, unsigned int item id, unsigned char *dest, apr size t dest len) get/read the memory from this slot to dest apr status t put(ap slotmem instance t *slot, unsigned int item id, unsigned char *src, apr size t src len) put/write the data from src to this slot unsigned int num slots(ap slotmem instance t *s) return the total number of slots in the segment apr size t slot size(ap slotmem instance t *s) return the total data size, in bytes, of a slot in the segment apr status t grab(ap slotmem instance t *s, unsigned int *item id); grab or allocate the first free slot and mark as in-use (does not do any data copying) apr status t fgrab(ap slotmem instance t *s, unsigned int item id); forced grab or allocate the specified slot and mark as in-use (does not do any data copying) apr status t release(ap slotmem instance t *s, unsigned int item id); release or free a slot and mark as not in-use (does not do any data copying) Directives This module provides no directives. 908 CHAPTER 10. APACHE MODULES 10.109 Apache Module mod so Description: Status: ModuleIdentifier: SourceFile: Compatibility: Loading of executable code and modules into the server at start-up or restart time Extension so module mod so.c This is a Base module (always included) on Windows Summary On selected operating systems this module can be used to load modules into Apache HTTP Server at runtime via the Dynamic Shared Object (p. 68) (DSO) mechanism, rather than requiring a recompilation. On Unix, the loaded code typically comes from shared object files (usually with .so extension), on Windows this may either be the .so or .dll extension. ! Warning Modules built for one major version of the Apache HTTP Server will generally not work on another. (e.g. 1.3 vs. 2.0, or 2.0 vs. 2.2) There are usually API changes between one major version and another that require that modules be modified to work with the new version. Directives • LoadFile • LoadModule Creating Loadable Modules for Windows =⇒Note On Windows, where loadable files typically have a file extension of .dll, Apache httpd modules are called mod whatever.so, just as they are on other platforms. However, you may encounter third-party modules, such as PHP for example, that continue to use the .dll convention. While mod so still loads modules with ApacheModuleFoo.dll names, the new naming convention is preferred; if you are converting your loadable module for 2.0, please fix the name to this 2.0 convention. The Apache httpd module API is unchanged between the Unix and Windows versions. Many modules will run on Windows with no or little change from Unix, although others rely on aspects of the Unix architecture which are not present in Windows, and will not work. When a module does work, it can be added to the server in one of two ways. As with Unix, it can be compiled into the server. Because Apache httpd for Windows does not have the Configure program of Apache httpd for Unix, the module’s source file must be added to the ApacheCore project file, and its symbols must be added to the os\win32\modules.c file. The second way is to compile the module as a DLL, a shared library that can be loaded into the server at runtime, using the L OAD M ODULE directive. These module DLLs can be distributed and run on any Apache httpd for Windows installation, without recompilation of the server. To create a module DLL, a small change is necessary to the module’s source file: The module record must be exported from the DLL (which will be created later; see below). To do this, add the AP MODULE DECLARE DATA (defined in the Apache httpd header files) to your module’s module record definition. For example, if your module has: 10.109. APACHE MODULE MOD SO 909 module foo module; Replace the above with: module AP MODULE DECLARE DATA foo module; Note that this will only be activated on Windows, so the module can continue to be used, unchanged, with Unix if needed. Also, if you are familiar with .DEF files, you can export the module record with that method instead. Now, create a DLL containing your module. You will need to link this against the libhttpd.lib export library that is created when the libhttpd.dll shared library is compiled. You may also have to change the compiler settings to ensure that the Apache httpd header files are correctly located. You can find this library in your server root’s modules directory. It is best to grab an existing module .dsp file from the tree to assure the build environment is configured correctly, or alternately compare the compiler and link options to your .dsp. This should create a DLL version of your module. Now simply place it in the modules directory of your server root, and use the L OAD M ODULE directive to load it. LoadFile Directive Description: Syntax: Context: Status: Module: Link in the named object file or library LoadFile filename [filename] ... server config, virtual host Extension mod so The L OAD F ILE directive links in the named object files or libraries when the server is started or restarted; this is used to load additional code which may be required for some module to work. Filename is either an absolute path or relative to ServerRoot (p. 380) . For example: LoadFile "libexec/libxmlparse.so" LoadModule Directive Description: Syntax: Context: Status: Module: Links in the object file or library, and adds to the list of active modules LoadModule module filename server config, virtual host Extension mod so The L OAD M ODULE directive links in the object file or library filename and adds the module structure named module to the list of active modules. Module is the name of the external variable of type module in the file, and is listed as the Module Identifier (p. 376) in the module documentation. For example: LoadModule status_module "modules/mod_status.so" loads the named module from the modules subdirectory of the ServerRoot. 910 CHAPTER 10. APACHE MODULES 10.110 Apache Module mod socache dbm Description: Status: ModuleIdentifier: SourceFile: DBM based shared object cache provider. Extension socache dbm module mod socache dbm.c Summary mod socache dbm is a shared object cache provider which provides for creation and access to a cache backed by a DBM database. dbm:/path/to/datafile If the path is not absolute then it is assumed to be relative to the D EFAULT RUNTIME D IR. Details of other shared object cache providers can be found here (p. 114) . Directives This module provides no directives. 10.111. APACHE MODULE MOD SOCACHE DC 10.111 911 Apache Module mod socache dc Description: Status: ModuleIdentifier: SourceFile: Distcache based shared object cache provider. Extension socache dc module mod socache dc.c Summary MOD SOCACHE DC is a shared object cache provider which provides for creation and access to a cache backed by the distcache86 distributed session caching libraries. Details of other shared object cache providers can be found here (p. 114) . Directives This module provides no directives. 86 http://distcache.sourceforge.net/ 912 CHAPTER 10. APACHE MODULES 10.112 Apache Module mod socache memcache Description: Status: ModuleIdentifier: SourceFile: Memcache based shared object cache provider. Extension socache memcache module mod socache memcache.c Summary mod socache memcache is a shared object cache provider which provides for creation and access to a cache backed by the memcached87 high-performance, distributed memory object caching system. This shared object cache provider’s "create" method requires a comma separated list of memcached host/port specifications. If using this provider via another modules configuration (such as SSLS ESSION C ACHE), provide the list of servers as the optional "arg" parameter. SSLSessionCache memcache:memcache.example.com:12345,memcache2.example.com:12345 Details of other shared object cache providers can be found here (p. 114) . Directives • MemcacheConnTTL MemcacheConnTTL Directive Description: Syntax: Default: Context: Status: Module: Compatibility: Keepalive time for idle connections MemcacheConnTTL num[units] MemcacheConnTTL 15s server config, virtual host Extension mod socache memcache Available in Apache 2.4.17 and later Set the time to keep idle connections with the memcache server(s) alive (threaded platforms only). Valid values for M EMCACHE C ONN TTL are times up to one hour. 0 means no timeout. =⇒This timeout defaults to units of seconds, but accepts suffixes for milliseconds (ms), seconds (s), minutes (min), and hours (h). Before Apache 2.4.17, this timeout was hardcoded and its value was 600 usec. So, the closest configuration to match the legacy behaviour is to set M EMCACHE C ONN TTL to 1ms. # Set a timeout MemcacheConnTTL # Set a timeout MemcacheConnTTL 87 http://memcached.org/ of 10 minutes 10min of 60 seconds 60 10.113. APACHE MODULE MOD SOCACHE SHMCB 10.113 913 Apache Module mod socache shmcb Description: Status: ModuleIdentifier: SourceFile: shmcb based shared object cache provider. Extension socache shmcb module mod socache shmcb.c Summary mod socache shmcb is a shared object cache provider which provides for creation and access to a cache backed by a high-performance cyclic buffer inside a shared memory segment. shmcb:/path/to/datafile(512000) If the path is not absolute then it is assumed to be relative to the D EFAULT RUNTIME D IR. Details of other shared object cache providers can be found here (p. 114) . Directives This module provides no directives. 914 CHAPTER 10. APACHE MODULES 10.114 Apache Module mod speling Description: Status: ModuleIdentifier: SourceFile: Attempts to correct mistaken URLs by ignoring capitalization, or attempting to correct various minor misspellings. Extension speling module mod speling.c Summary Requests to documents sometimes cannot be served by the core apache server because the request was misspelled or miscapitalized. This module addresses this problem by trying to find a matching document, even after all other modules gave up. It does its work by comparing each document name in the requested directory against the requested document name without regard to case, and allowing up to one misspelling (character insertion / omission / transposition or wrong character). A list is built with all document names which were matched using this strategy. If, after scanning the directory, • no matching document was found, Apache will proceed as usual and return a "document not found" error. • only one document is found that "almost" matches the request, then it is returned in the form of a redirection response. • more than one document with a close match was found, then the list of the matches is returned to the client, and the client can select the correct candidate. Directives • CheckBasenameMatch • CheckCaseOnly • CheckSpelling CheckBasenameMatch Directive Description: Syntax: Default: Context: Override: Status: Module: Also match files with differing file name extensions. CheckBasenameMatch on|off CheckBasenameMatch Off server config, virtual host, directory, .htaccess Options Extension mod speling When set, this directive extends the action of the spelling correction to the file name extension. For example a file foo.gif will match a request for foo or foo.jpg. This can be particulary useful in conjunction with MultiViews (p. 78) . 10.114. APACHE MODULE MOD SPELING 915 CheckCaseOnly Directive Description: Syntax: Default: Context: Override: Status: Module: Limits the action of the speling module to case corrections CheckCaseOnly on|off CheckCaseOnly Off server config, virtual host, directory, .htaccess Options Extension mod speling When set, this directive limits the action of the spelling correction to lower/upper case changes. Other potential corrections are not performed, except when C HECK BASENAME M ATCH is also set. CheckSpelling Directive Description: Syntax: Default: Context: Override: Status: Module: Enables the spelling module CheckSpelling on|off CheckSpelling Off server config, virtual host, directory, .htaccess Options Extension mod speling This directive enables or disables the spelling module. When enabled, keep in mind that • the directory scan which is necessary for the spelling correction will have an impact on the server’s performance when many spelling corrections have to be performed at the same time. • the document trees should not contain sensitive files which could be matched inadvertently by a spelling "correction". • the module is unable to correct misspelled user names (as in http://my.host/˜apahce/), just file names or directory names. • spelling corrections apply strictly to existing files, so a request for the may get incorrectly treated as the negotiated file "/stats.html". mod speling should not be enabled in DAV (p. 589) enabled directories, because it will try to "spell fix" newly created resource names against existing filenames, e.g., when trying to upload a new document doc43.html it might redirect to an existing document doc34.html, which is not what was intended. 916 CHAPTER 10. APACHE MODULES 10.115 Apache Module mod ssl Description: Status: ModuleIdentifier: SourceFile: Strong cryptography using the Secure Sockets Layer (SSL) and Transport Layer Security (TLS) protocols Extension ssl module mod ssl.c Summary This module provides SSL v3 and TLS v1.x support for the Apache HTTP Server. SSL v2 is no longer supported. This module relies on OpenSSL88 to provide the cryptography engine. Further details, discussion, and examples are provided in the SSL documentation (p. 192) . Directives • SSLCACertificateFile • SSLCACertificatePath • SSLCADNRequestFile • SSLCADNRequestPath • SSLCARevocationCheck • SSLCARevocationFile • SSLCARevocationPath • SSLCertificateChainFile • SSLCertificateFile • SSLCertificateKeyFile • SSLCipherSuite • SSLCompression • SSLCryptoDevice • SSLEngine • SSLFIPS • SSLHonorCipherOrder • SSLInsecureRenegotiation • SSLOCSPDefaultResponder • SSLOCSPEnable • SSLOCSPOverrideResponder • SSLOCSPProxyURL • SSLOCSPResponderTimeout • SSLOCSPResponseMaxAge • SSLOCSPResponseTimeSkew • SSLOCSPUseRequestNonce • SSLOpenSSLConfCmd 88 http://www.openssl.org/ 10.115. APACHE MODULE MOD SSL • SSLOptions • SSLPassPhraseDialog • SSLProtocol • SSLProxyCACertificateFile • SSLProxyCACertificatePath • SSLProxyCARevocationCheck • SSLProxyCARevocationFile • SSLProxyCARevocationPath • SSLProxyCheckPeerCN • SSLProxyCheckPeerExpire • SSLProxyCheckPeerName • SSLProxyCipherSuite • SSLProxyEngine • SSLProxyMachineCertificateChainFile • SSLProxyMachineCertificateFile • SSLProxyMachineCertificatePath • SSLProxyProtocol • SSLProxyVerify • SSLProxyVerifyDepth • SSLRandomSeed • SSLRenegBufferSize • SSLRequire • SSLRequireSSL • SSLSessionCache • SSLSessionCacheTimeout • SSLSessionTicketKeyFile • SSLSessionTickets • SSLSRPUnknownUserSeed • SSLSRPVerifierFile • SSLStaplingCache • SSLStaplingErrorCacheTimeout • SSLStaplingFakeTryLater • SSLStaplingForceURL • SSLStaplingResponderTimeout • SSLStaplingResponseMaxAge • SSLStaplingResponseTimeSkew • SSLStaplingReturnResponderErrors • SSLStaplingStandardCacheTimeout • SSLStrictSNIVHostCheck • SSLUserName • SSLUseStapling • SSLVerifyClient • SSLVerifyDepth 917 918 CHAPTER 10. APACHE MODULES Environment Variables This module can be configured to provide several items of SSL information as additional environment variables to the SSI and CGI namespace. This information is not provided by default for performance reasons. (See SSLO PTIONS StdEnvVars, below.) The generated variables are listed in the table below. For backward compatibility the information can be made available under different names, too. Look in the Compatibility (p. 202) chapter for details on the compatibility variables. Variable Name: Value Type: Description: HTTPS SSL PROTOCOL SSL SESSION ID SSL SESSION RESUMED flag string string string SSL SSL SSL SSL SSL SSL SSL SSL SSL SSL SSL SSL SSL string string string number number string string string string string string string string HTTPS is being used. The SSL protocol version (SSLv3, TLSv1, TLSv1.1, TLSv1.2) The hex-encoded SSL session id Initial or Resumed SSL Session. Note: multiple requests may be served over the same (Initial or Resumed) SSL session if HTTP KeepAlive is in use true if secure renegotiation is supported, else false The cipher specification name true if cipher is an export cipher Number of cipher bits (actually used) Number of cipher bits (possible) SSL compression method negotiated The mod ssl program version The OpenSSL program version The version of the client certificate The serial of the client certificate Subject DN in client’s certificate Component of client’s Subject DN Client certificate’s subjectAltName extension entries of type rfc822Name Client certificate’s subjectAltName extension entries of type dNSName Client certificate’s subjectAltName extension entries of type otherName, Microsoft User Principal Name form (OID 1.3.6.1.4.1.311.20.2.3) Issuer DN of client’s certificate Component of client’s Issuer DN Validity of client’s certificate (start time) Validity of client’s certificate (end time) Number of days until client’s certificate expires Algorithm used for the signature of client’s certificate Algorithm used for the public key of client’s certificate PEM-encoded client certificate PEM-encoded certificates in client certificate chain Serial number and issuer of the certificate. The format matches that of the CertificateExactAssertion in RFC4523 NONE, SUCCESS, GENEROUS or FAILED:reason The version of the server certificate The serial of the server certificate Subject DN in server’s certificate Server certificate’s subjectAltName extension entries of type rfc822Name Server certificate’s subjectAltName extension entries of type dNSName Server certificate’s subjectAltName extension entries of type otherName, SRVName form (OID 1.3.6.1.5.5.7.8.7, RFC 4985) SECURE RENEG CIPHER CIPHER EXPORT CIPHER USEKEYSIZE CIPHER ALGKEYSIZE COMPRESS METHOD VERSION INTERFACE VERSION LIBRARY CLIENT M VERSION CLIENT M SERIAL CLIENT S DN CLIENT S DN x509 CLIENT SAN Email n SSL CLIENT SAN DNS n string SSL CLIENT SAN OTHER msUPN n string SSL SSL SSL SSL SSL SSL SSL SSL SSL SSL CLIENT CLIENT CLIENT CLIENT CLIENT CLIENT CLIENT CLIENT CLIENT CLIENT I DN I DN x509 V START V END V REMAIN A SIG A KEY CERT CERT CHAIN n CERT RFC4523 CEA string string string string string string string string string string SSL SSL SSL SSL SSL CLIENT SERVER SERVER SERVER SERVER VERIFY M VERSION M SERIAL S DN SAN Email n string string string string string SSL SERVER SAN DNS n string SSL SERVER SAN OTHER dnsSRV n string 10.115. APACHE MODULE MOD SSL SSL SSL SSL SSL SSL SSL SSL SSL SSL SSL SSL SERVER S DN x509 SERVER I DN SERVER I DN x509 SERVER V START SERVER V END SERVER A SIG SERVER A KEY SERVER CERT SRP USER SRP USERINFO TLS SNI 919 string string string string string string string string string string string Component of server’s Subject DN Issuer DN of server’s certificate Component of server’s Issuer DN Validity of server’s certificate (start time) Validity of server’s certificate (end time) Algorithm used for the signature of server’s certificate Algorithm used for the public key of server’s certificate PEM-encoded server certificate SRP username SRP user info Contents of the SNI TLS extension (if supplied with ClientHello) x509 specifies a component of an X.509 DN; one of C,ST,L,O,OU,CN,T,I,G,S,D,UID,Email. In Apache 2.1 and later, x509 may also include a numeric n suffix. If the DN in question contains multiple attributes of the same name, this suffix is used as a zero-based index to select a particular attribute. For example, where the server certificate subject DN included two OU attributes, SSL SERVER S DN OU 0 and SSL SERVER S DN OU 1 could be used to reference each. A variable name without a n suffix is equivalent to that name with a 0 suffix; the first (or only) attribute. When the environment table is populated using the StdEnvVars option of the SSLO PTIONS directive, the first (or only) attribute of any DN is added only under a non-suffixed name; i.e. no 0 suffixed entries are added. The format of the * DN variables has changed in Apache HTTPD 2.3.11. See the LegacyDNStringFormat option for SSLO PTIONS for details. SSL CLIENT V REMAIN is only available in version 2.1 and later. A number of additional environment variables can also be used in SSLR EQUIRE expressions, or in custom log formats: =⇒ HTTP_USER_AGENT HTTP_REFERER HTTP_COOKIE HTTP_FORWARDED HTTP_HOST HTTP_PROXY_CONNECTION HTTP_ACCEPT THE_REQUEST REQUEST_FILENAME REQUEST_METHOD REQUEST_SCHEME REQUEST_URI PATH_INFO QUERY_STRING REMOTE_HOST REMOTE_IDENT IS_SUBREQ DOCUMENT_ROOT SERVER_ADMIN SERVER_NAME SERVER_PORT SERVER_PROTOCOL REMOTE_ADDR REMOTE_USER AUTH_TYPE SERVER_SOFTWARE API_VERSION TIME_YEAR TIME_MON TIME_DAY TIME_HOUR TIME_MIN TIME_SEC TIME_WDAY TIME In these contexts, two special formats can also be used: ENV:variablename This will expand to the standard environment variable variablename. HTTP:headername This will expand to the value of the request header with name headername. Custom Log Formats When MOD SSL is built into Apache or at least loaded (under DSO situation) additional functions exist for the Custom Log Format (p. 705) of MOD LOG CONFIG. First there is an additional “%{varname}x” eXtension format function which can be used to expand any variables provided by any module, especially those provided by mod ssl which can you find in the above table. 920 CHAPTER 10. APACHE MODULES For backward compatibility there is additionally a special “%{name}c” cryptography format function provided. Information about this function is provided in the Compatibility (p. 202) chapter. Example CustomLog "logs/ssl_request_log" "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b" These formats even work without setting the StdEnvVars option of the SSLO PTIONS directive. Request Notes MOD SSL sets "notes" for the request which can be used in logging with the %{name}n format string in MOD LOG CONFIG . The notes supported are as follows: ssl-access-forbidden This note is set to the value 1 if access was denied due to an SSLR EQUIRE or SSLR E QUIRE SSL directive. ssl-secure-reneg If MOD SSL is built against a version of OpenSSL which supports the secure renegotiation extension, this note is set to the value 1 if SSL is in used for the current connection, and the client also supports the secure renegotiation extension. If the client does not support the secure renegotiation extension, the note is set to the value 0. If MOD SSL is not built against a version of OpenSSL which supports secure renegotiation, or if SSL is not in use for the current connection, the note is not set. Expression Parser Extension When MOD SSL is built into Apache or at least loaded (under DSO situation) any variables provided by MOD SSL can be used in expressions for the ap expr Expression Parser (p. 99) . The variables can be referenced using the syntax “%{varname}”. Starting with version 2.4.18 one can also use the MOD REWRITE style syntax “%{SSL:varname}” or the function style syntax “ssl(varname)”. Example (using MOD HEADERS) Header set X-SSL-PROTOCOL "expr=%{SSL_PROTOCOL}" Header set X-SSL-CIPHER "expr=%{SSL:SSL_CIPHER}" This feature even works without setting the StdEnvVars option of the SSLO PTIONS directive. Authorization providers for use with Require MOD SSL provides a few authentication providers for use with MOD AUTHZ CORE’s R EQUIRE directive. Require ssl The ssl provider denies access if a connection is not encrypted with SSL. This is similar to the SSLR EQUIRE SSL directive. Require ssl 10.115. APACHE MODULE MOD SSL 921 Require ssl-verify-client The ssl provider allows access if the user is authenticated with a valid client certificate. This is only useful if SSLVerifyClient optional is in effect. The following example grants access if the user is authenticated either with a client certificate or by username and password. Require ssl-verify-client Require valid-user SSLCACertificateFile Directive Description: Syntax: Context: Status: Module: File of concatenated PEM-encoded CA Certificates for Client Auth SSLCACertificateFile file-path server config, virtual host Extension mod ssl This directive sets the all-in-one file where you can assemble the Certificates of Certification Authorities (CA) whose clients you deal with. These are used for Client Authentication. Such a file is simply the concatenation of the various PEM-encoded Certificate files, in order of preference. This can be used alternatively and/or additionally to SSLCACERTIFICATE PATH . Example SSLCACertificateFile /usr/local/apache2/conf/ssl.crt/ca-bundle-client.crt SSLCACertificatePath Directive Description: Syntax: Context: Status: Module: Directory of PEM-encoded CA Certificates for Client Auth SSLCACertificatePath directory-path server config, virtual host Extension mod ssl This directive sets the directory where you keep the Certificates of Certification Authorities (CAs) whose clients you deal with. These are used to verify the client certificate on Client Authentication. The files in this directory have to be PEM-encoded and are accessed through hash filenames. So usually you can’t just place the Certificate files there: you also have to create symbolic links named hash-value.N. And you should always make sure this directory contains the appropriate symbolic links. Example SSLCACertificatePath /usr/local/apache2/conf/ssl.crt/ SSLCADNRequestFile Directive Description: Syntax: Context: Status: Module: File of concatenated PEM-encoded CA Certificates for defining acceptable CA names SSLCADNRequestFile file-path server config, virtual host Extension mod ssl 922 CHAPTER 10. APACHE MODULES When a client certificate is requested by mod ssl, a list of acceptable Certificate Authority names is sent to the client in the SSL handshake. These CA names can be used by the client to select an appropriate client certificate out of those it has available. If neither of the directives SSLCADNR EQUEST PATH or SSLCADNR EQUEST F ILE are given, then the set of acceptable CA names sent to the client is the names of all the CA certificates given by the SSLCAC ERTIFICATE F ILE and SSLCAC ERTIFICATE PATH directives; in other words, the names of the CAs which will actually be used to verify the client certificate. In some circumstances, it is useful to be able to send a set of acceptable CA names which differs from the actual CAs used to verify the client certificate - for example, if the client certificates are signed by intermediate CAs. In such cases, SSLCADNR EQUEST PATH and/or SSLCADNR EQUEST F ILE can be used; the acceptable CA names are then taken from the complete set of certificates in the directory and/or file specified by this pair of directives. SSLCADNR EQUEST F ILE must specify an all-in-one file containing a concatenation of PEM-encoded CA certificates. Example SSLCADNRequestFile /usr/local/apache2/conf/ca-names.crt SSLCADNRequestPath Directive Description: Syntax: Context: Status: Module: Directory of PEM-encoded CA Certificates for defining acceptable CA names SSLCADNRequestPath directory-path server config, virtual host Extension mod ssl This optional directive can be used to specify the set of acceptable CA names which will be sent to the client when a client certificate is requested. See the SSLCADNR EQUEST F ILE directive for more details. The files in this directory have to be PEM-encoded and are accessed through hash filenames. So usually you can’t just place the Certificate files there: you also have to create symbolic links named hash-value.N. And you should always make sure this directory contains the appropriate symbolic links. Example SSLCADNRequestPath /usr/local/apache2/conf/ca-names.crt/ SSLCARevocationCheck Directive Description: Syntax: Default: Context: Status: Module: Compatibility: Enable CRL-based revocation checking SSLCARevocationCheck chain|leaf|none flags SSLCARevocationCheck none server config, virtual host Extension mod ssl Optional flags available in httpd 2.5-dev or later Enables certificate revocation list (CRL) checking. At least one of SSLCAR EVOCATION F ILE or SSLCAR EVOCA TION PATH must be configured. When set to chain (recommended setting), CRL checks are applied to all certificates in the chain, while setting it to leaf limits the checks to the end-entity cert. The available flags are: 10.115. APACHE MODULE MOD SSL 923 • no crl for cert ok Prior to version 2.3.15, CRL checking in mod ssl also succeeded when no CRL(s) for the checked certificate(s) were found in any of the locations configured with SSLCAR EVOCATION F ILE or SSLCAR EVOCATION PATH. With the introduction of SSLCAR EVOCATION F ILE, the behavior has been changed: by default with chain or leaf, CRLs must be present for the validation to succeed - otherwise it will fail with an "unable to get certificate CRL" error. The flag no crl for cert ok allows to restore previous behaviour. Example SSLCARevocationCheck chain Compatibility with versions 2.2 SSLCARevocationCheck chain no_crl_for_cert_ok SSLCARevocationFile Directive Description: Syntax: Context: Status: Module: File of concatenated PEM-encoded CA CRLs for Client Auth SSLCARevocationFile file-path server config, virtual host Extension mod ssl This directive sets the all-in-one file where you can assemble the Certificate Revocation Lists (CRL) of Certification Authorities (CA) whose clients you deal with. These are used for Client Authentication. Such a file is simply the concatenation of the various PEM-encoded CRL files, in order of preference. This can be used alternatively and/or additionally to SSLCAR EVOCATION PATH. Example SSLCARevocationFile /usr/local/apache2/conf/ssl.crl/ca-bundle-client.crl SSLCARevocationPath Directive Description: Syntax: Context: Status: Module: Directory of PEM-encoded CA CRLs for Client Auth SSLCARevocationPath directory-path server config, virtual host Extension mod ssl This directive sets the directory where you keep the Certificate Revocation Lists (CRL) of Certification Authorities (CAs) whose clients you deal with. These are used to revoke the client certificate on Client Authentication. The files in this directory have to be PEM-encoded and are accessed through hash filenames. So usually you have not only to place the CRL files there. Additionally you have to create symbolic links named hash-value.rN. And you should always make sure this directory contains the appropriate symbolic links. Example SSLCARevocationPath /usr/local/apache2/conf/ssl.crl/ 924 CHAPTER 10. APACHE MODULES SSLCertificateChainFile Directive Description: Syntax: Context: Status: Module: File of PEM-encoded Server CA Certificates SSLCertificateChainFile file-path server config, virtual host Extension mod ssl =⇒SSLCertificateChainFile is deprecated SSLCertificateChainFile became obsolete with version 2.4.8, when SSLC CATE F ILE ERTIFI was extended to also load intermediate CA certificates from the server certificate file. This directive sets the optional all-in-one file where you can assemble the certificates of Certification Authorities (CA) which form the certificate chain of the server certificate. This starts with the issuing CA certificate of the server certificate and can range up to the root CA certificate. Such a file is simply the concatenation of the various PEMencoded CA Certificate files, usually in certificate chain order. This should be used alternatively and/or additionally to SSLCAC ERTIFICATE PATH for explicitly constructing the server certificate chain which is sent to the browser in addition to the server certificate. It is especially useful to avoid conflicts with CA certificates when using client authentication. Because although placing a CA certificate of the server certificate chain into SSLCAC ERTIFICATE PATH has the same effect for the certificate chain construction, it has the side-effect that client certificates issued by this same CA certificate are also accepted on client authentication. But be careful: Providing the certificate chain works only if you are using a single RSA or DSA based server certificate. If you are using a coupled RSA+DSA certificate pair, this will work only if actually both certificates use the same certificate chain. Else the browsers will be confused in this situation. Example SSLCertificateChainFile /usr/local/apache2/conf/ssl.crt/ca.crt SSLCertificateFile Directive Description: Syntax: Context: Status: Module: Server PEM-encoded X.509 certificate data file SSLCertificateFile file-path server config, virtual host Extension mod ssl This directive points to a file with certificate data in PEM format. At a minimum, the file must include an end-entity (leaf) certificate. The directive can be used multiple times (referencing different filenames) to support multiple algorithms for server authentication - typically RSA, DSA, and ECC. The number of supported algorithms depends on the OpenSSL version being used for mod ssl: with version 1.0.0 or later, openssl list-public-key-algorithms will output a list of supported algorithms, see also the note below about limitations of OpenSSL versions prior to 1.0.2 and the ways to work around them. The files may also include intermediate CA certificates, sorted from leaf to root. This is supported with version 2.4.8 and later, and obsoletes SSLC ERTIFICATE C HAIN F ILE. When running with OpenSSL 1.0.2 or later, this allows to configure the intermediate CA chain on a per-certificate basis. Custom DH parameters and an EC curve name for ephemeral keys, can also be added to end of the first file configured using SSLC ERTIFICATE F ILE. This is supported in version 2.4.7 or later. Such parameters can be generated using the commands openssl dhparam and openssl ecparam. The parameters can be added as-is to the end of the first certificate file. Only the first file can be used for custom parameters, as they are applied independently of the authentication algorithm type. 10.115. APACHE MODULE MOD SSL 925 Finally the end-entity certificate’s private key can also be added to the certificate file instead of using a separate SSLC ERTIFICATE K EY F ILE directive. This practice is highly discouraged. If it is used, the certificate files using such an embedded key must be configured after the certificates using a separate key file. If the private key is encrypted, the pass phrase dialog is forced at startup time. =⇒DH parameter interoperability with primes > 1024 bit Beginning with version 2.4.7, mod ssl makes use of standardized DH parameters with prime lengths of 2048, 3072 and 4096 bits and with additional prime lengths of 6144 and 8192 bits beginning with version 2.4.10 (from RFC 3526a ), and hands them out to clients based on the length of the certificate’s RSA/DSA key. With Java-based clients in particular (Java 7 or earlier), this may lead to handshake failures - see this FAQ answer (p. 212) for working around such issues. a http://www.ietf.org/rfc/rfc3526.txt =⇒Default DH parameters when using multiple certificates and OpenSSL versions prior to 1.0.2 When using multiple certificates to support different authentication algorithms (like RSA, DSA, but mainly ECC) and OpenSSL prior to 1.0.2, it is recommended to either use custom DH parameters (preferably) by adding them to the first certificate file (as described above), or to order the SSLC ERTIFICATE F ILE directives such that RSA/DSA certificates are placed after the ECC one. This is due to a limitation in older versions of OpenSSL which don’t let the Apache HTTP Server determine the currently selected certificate at handshake time (when the DH parameters must be sent to the peer) but instead always provide the last configured certificate. Consequently, the server may select default DH parameters based on the length of the wrong certificate’s key (ECC keys are much smaller than RSA/DSA ones and their length is not relevant for selecting DH primes). Since custom DH parameters always take precedence over the default ones, this issue can be avoided by creating and configuring them (as described above), thus using a custom/suitable length. Example SSLCertificateFile /usr/local/apache2/conf/ssl.crt/server.crt SSLCertificateKeyFile Directive Description: Syntax: Context: Status: Module: Server PEM-encoded private key file SSLCertificateKeyFile file-path server config, virtual host Extension mod ssl This directive points to the PEM-encoded private key file for the server. If the contained private key is encrypted, the pass phrase dialog is forced at startup time. The directive can be used multiple times (referencing different filenames) to support multiple algorithms for server authentication. For each SSLC ERTIFICATE K EY F ILE directive, there must be a matching SSLC ERTIFICATE F ILE directive. The private key may also be combined with the certificate in the file given by SSLC ERTIFICATE F ILE, but this practice is highly discouraged. If it is used, the certificate files using such an embedded key must be configured after the certificates using a separate key file. 926 CHAPTER 10. APACHE MODULES Example SSLCertificateKeyFile /usr/local/apache2/conf/ssl.key/server.key SSLCipherSuite Directive Description: Syntax: Default: Context: Override: Status: Module: Cipher Suite available for negotiation in SSL handshake SSLCipherSuite cipher-spec SSLCipherSuite DEFAULT (depends on OpenSSL version) server config, virtual host, directory, .htaccess AuthConfig Extension mod ssl This complex directive uses a colon-separated cipher-spec string consisting of OpenSSL cipher specifications to configure the Cipher Suite the client is permitted to negotiate in the SSL handshake phase. Notice that this directive can be used both in per-server and per-directory context. In per-server context it applies to the standard SSL handshake when a connection is established. In per-directory context it forces a SSL renegotiation with the reconfigured Cipher Suite after the HTTP request was read but before the HTTP response is sent. An SSL cipher specification in cipher-spec is composed of 4 major attributes plus a few extra minor ones: • Key Exchange Algorithm: RSA, Diffie-Hellman, Elliptic Curve Diffie-Hellman, Secure Remote Password • Authentication Algorithm: RSA, Diffie-Hellman, DSS, ECDSA, or none. • Cipher/Encryption Algorithm: AES, DES, Triple-DES, RC4, RC2, IDEA, etc. • MAC Digest Algorithm: MD5, SHA or SHA1, SHA256, SHA384. An SSL cipher can also be an export cipher. SSLv2 ciphers are no longer supported. To specify which ciphers to use, one can either specify all the Ciphers, one at a time, or use aliases to specify the preference and order for the ciphers (see Table 1). The actually available ciphers and aliases depends on the used openssl version. Newer openssl versions may include additional ciphers. Tag Key Exchange Algorithm: kRSA kDHr kDHd kEDH kSRP Authentication Algorithm: aNULL aRSA aDSS aDH Cipher Encoding Algorithm: eNULL NULL AES Description RSA key exchange Diffie-Hellman key exchange with RSA key Diffie-Hellman key exchange with DSA key Ephemeral (temp.key) Diffie-Hellman key exchange (no cert) Secure Remote Password (SRP) key exchange No authentication RSA authentication DSS authentication Diffie-Hellman authentication No encryption alias for eNULL AES encryption 10.115. APACHE MODULE MOD SSL DES 3DES RC4 RC2 IDEA MAC Digest Algorithm: MD5 SHA1 SHA SHA256 SHA384 Aliases: SSLv3 TLSv1 EXP EXPORT40 EXPORT56 LOW MEDIUM HIGH RSA DH EDH ECDH ADH AECDH SRP DSS ECDSA aNULL 927 DES encryption Triple-DES encryption RC4 encryption RC2 encryption IDEA encryption MD5 hash function SHA1 hash function alias for SHA1 SHA256 hash function SHA384 hash function all SSL version 3.0 ciphers all TLS version 1.0 ciphers all export ciphers all 40-bit export ciphers only all 56-bit export ciphers only all low strength ciphers (no export, single DES) all ciphers with 128 bit encryption all ciphers using Triple-DES all ciphers using RSA key exchange all ciphers using Diffie-Hellman key exchange all ciphers using Ephemeral Diffie-Hellman key exchange Elliptic Curve Diffie-Hellman key exchange all ciphers using Anonymous Diffie-Hellman key exchange all ciphers using Anonymous Elliptic Curve Diffie-Hellman key exchange all ciphers using Secure Remote Password (SRP) key exchange all ciphers using DSS authentication all ciphers using ECDSA authentication all ciphers using no authentication Now where this becomes interesting is that these can be put together to specify the order and ciphers you wish to use. To speed this up there are also aliases (SSLv3, TLSv1, EXP, LOW, MEDIUM, HIGH) for certain groups of ciphers. These tags can be joined together with prefixes to form the cipher-spec. Available prefixes are: • none: add cipher to list • +: move matching ciphers to the current location in list • -: remove cipher from list (can be added later again) • !: kill cipher from list completely (can not be added later again) =⇒aNULL, eNULL and EXP ciphers are always disabled Beginning with version 2.4.7, null and export-grade ciphers are always disabled, as mod ssl unconditionally adds !aNULL:!eNULL:!EXP to any cipher string at initialization. A simpler way to look at all of this is to use the “openssl ciphers -v” command which provides a nice way to successively create the correct cipher-spec string. The default cipher-spec string depends on the version of the OpenSSL libraries used. Let’s suppose it is “RC4-SHA:AES128-SHA:HIGH:MEDIUM:!aNULL:!MD5” which means the following: Put RC4-SHA and AES128-SHA at the beginning. We do this, because these ciphers offer a 928 CHAPTER 10. APACHE MODULES good compromise between speed and security. Next, include high and medium security ciphers. Finally, remove all ciphers which do not authenticate, i.e. for SSL the Anonymous Diffie-Hellman ciphers, as well as all ciphers which use MD5 as hash algorithm, because it has been proven insufficient. $ openssl ciphers -v ’RC4-SHA:AES128-SHA:HIGH:MEDIUM:!aNULL:!MD5’ RC4-SHA SSLv3 Kx=RSA Au=RSA Enc=RC4(128) Mac=SHA1 AES128-SHA SSLv3 Kx=RSA Au=RSA Enc=AES(128) Mac=SHA1 DHE-RSA-AES256-SHA SSLv3 Kx=DH Au=RSA Enc=AES(256) Mac=SHA1 ... ... ... ... ... SEED-SHA SSLv3 Kx=RSA Au=RSA Enc=SEED(128) Mac=SHA1 PSK-RC4-SHA SSLv3 Kx=PSK Au=PSK Enc=RC4(128) Mac=SHA1 KRB5-RC4-SHA SSLv3 Kx=KRB5 Au=KRB5 Enc=RC4(128) Mac=SHA1 The complete list of particular RSA & DH ciphers for SSL is given in Table 2. Example SSLCipherSuite RSA:!EXP:!NULL:+HIGH:+MEDIUM:-LOW Cipher-Tag RSA Ciphers: DES-CBC3-SHA IDEA-CBC-SHA RC4-SHA RC4-MD5 DES-CBC-SHA EXP-DES-CBC-SHA EXP-RC2-CBC-MD5 EXP-RC4-MD5 NULL-SHA NULL-MD5 Diffie-Hellman Ciphers: ADH-DES-CBC3-SHA ADH-DES-CBC-SHA ADH-RC4-MD5 EDH-RSA-DES-CBC3-SHA EDH-DSS-DES-CBC3-SHA EDH-RSA-DES-CBC-SHA EDH-DSS-DES-CBC-SHA EXP-EDH-RSA-DES-CBC-SHA EXP-EDH-DSS-DES-CBC-SHA EXP-ADH-DES-CBC-SHA EXP-ADH-RC4-MD5 Protocol Key Ex. Auth. Enc. MAC SSLv3 SSLv3 SSLv3 SSLv3 SSLv3 SSLv3 SSLv3 SSLv3 SSLv3 SSLv3 RSA RSA RSA RSA RSA RSA(512) RSA(512) RSA(512) RSA RSA RSA RSA RSA RSA RSA RSA RSA RSA RSA RSA 3DES(168) IDEA(128) RC4(128) RC4(128) DES(56) DES(40) RC2(40) RC4(40) None None SHA1 SHA1 SHA1 MD5 SHA1 SHA1 MD5 MD5 SHA1 MD5 SSLv3 SSLv3 SSLv3 SSLv3 SSLv3 SSLv3 SSLv3 SSLv3 SSLv3 SSLv3 SSLv3 DH DH DH DH DH DH DH DH(512) DH(512) DH(512) DH(512) None None None RSA DSS RSA DSS RSA DSS None None 3DES(168) DES(56) RC4(128) 3DES(168) 3DES(168) DES(56) DES(56) DES(40) DES(40) DES(40) RC4(40) SHA1 SHA1 MD5 SHA1 SHA1 SHA1 SHA1 SHA1 SHA1 SHA1 MD5 Type export export export export export export export 10.115. APACHE MODULE MOD SSL 929 SSLCompression Directive Description: Syntax: Default: Context: Status: Module: Compatibility: Enable compression on the SSL level SSLCompression on|off SSLCompression off server config, virtual host Extension mod ssl Available in httpd 2.4.3 and later, if using OpenSSL 0.9.8 or later; virtual host scope available if using OpenSSL 1.0.0 or later. The default used to be on in version 2.4.3. This directive allows to enable compression on the SSL level. ! Enabling compression causes security issues in most setups (the so called CRIME attack). SSLCryptoDevice Directive Description: Syntax: Default: Context: Status: Module: Enable use of a cryptographic hardware accelerator SSLCryptoDevice engine SSLCryptoDevice builtin server config Extension mod ssl This directive enables use of a cryptographic hardware accelerator board to offload some of the SSL processing overhead. This directive can only be used if the SSL toolkit is built with "engine" support; OpenSSL 0.9.7 and later releases have "engine" support by default, the separate "-engine" releases of OpenSSL 0.9.6 must be used. To discover which engine names are supported, run the command "openssl engine". Example # For a Broadcom accelerator: SSLCryptoDevice ubsec SSLEngine Directive Description: Syntax: Default: Context: Status: Module: SSL Engine Operation Switch SSLEngine on|off|optional SSLEngine off server config, virtual host Extension mod ssl This directive toggles the usage of the SSL/TLS Protocol Engine. This is should be used inside a section to enable SSL/TLS for a that virtual host. By default the SSL/TLS Protocol Engine is disabled for both the main server and all configured virtual hosts. Example SSLEngine on #... 930 CHAPTER 10. APACHE MODULES In Apache 2.1 and later, SSLE NGINE can be set to optional. This enables support for RFC 281789 , Upgrading to TLS Within HTTP/1.1. At this time no web browsers support RFC 2817. SSLFIPS Directive Description: Syntax: Default: Context: Status: Module: SSL FIPS mode Switch SSLFIPS on|off SSLFIPS off server config Extension mod ssl This directive toggles the usage of the SSL library FIPS mode flag. It must be set in the global server context and cannot be configured with conflicting settings (SSLFIPS on followed by SSLFIPS off or similar). The mode applies to all SSL library operations. If httpd was compiled against an SSL library which did not support the FIPS mode flag, SSLFIPS on will fail. Refer to the FIPS 140-2 Security Policy document of the SSL provider library for specific requirements to use mod ssl in a FIPS 140-2 approved mode of operation; note that mod ssl itself is not validated, but may be described as using FIPS 140-2 validated cryptographic module, when all components are assembled and operated under the guidelines imposed by the applicable Security Policy. SSLHonorCipherOrder Directive Description: Syntax: Default: Context: Status: Module: Option to prefer the server’s cipher preference order SSLHonorCipherOrder on|off SSLHonorCipherOrder off server config, virtual host Extension mod ssl When choosing a cipher during an SSLv3 or TLSv1 handshake, normally the client’s preference is used. If this directive is enabled, the server’s preference will be used instead. Example SSLHonorCipherOrder on SSLInsecureRenegotiation Directive Description: Syntax: Default: Context: Status: Module: Compatibility: Option to enable support for insecure renegotiation SSLInsecureRenegotiation on|off SSLInsecureRenegotiation off server config, virtual host Extension mod ssl Available if using OpenSSL 0.9.8m or later As originally specified, all versions of the SSL and TLS protocols (up to and including TLS/1.2) were vulnerable to a Man-in-the-Middle attack (CVE-2009-355590 ) during a renegotiation. This vulnerability allowed an attacker to 89 http://www.ietf.org/rfc/rfc2817.txt 90 http://cve.mitre.org/cgi-bin/cvename.cgi?name=CAN-2009-3555 10.115. APACHE MODULE MOD SSL 931 "prefix" a chosen plaintext to the HTTP request as seen by the web server. A protocol extension was developed which fixed this vulnerability if supported by both client and server. If MOD SSL is linked against OpenSSL version 0.9.8m or later, by default renegotiation is only supported with clients supporting the new protocol extension. If this directive is enabled, renegotiation will be allowed with old (unpatched) clients, albeit insecurely. ! Security warning If this directive is enabled, SSL connections will be vulnerable to the Man-in-the-Middle prefix attack as described in CVE-2009-3555a . a http://cve.mitre.org/cgi-bin/cvename.cgi?name=CAN-2009-3555 Example SSLInsecureRenegotiation on The SSL SECURE RENEG environment variable can be used from an SSI or CGI script to determine whether secure renegotiation is supported for a given SSL connection. SSLOCSPDefaultResponder Directive Description: Syntax: Context: Status: Module: Set the default responder URI for OCSP validation SSLOCSDefaultResponder uri server config, virtual host Extension mod ssl This option sets the default OCSP responder to use. If SSLOCSPOVERRIDE R ESPONDER is not enabled, the URI given will be used only if no responder URI is specified in the certificate being verified. SSLOCSPEnable Directive Description: Syntax: Default: Context: Status: Module: Enable OCSP validation of the client certificate chain SSLOCSPEnable on|off SSLOCSPEnable off server config, virtual host Extension mod ssl This option enables OCSP validation of the client certificate chain. If this option is enabled, certificates in the client’s certificate chain will be validated against an OCSP responder after normal verification (including CRL checks) have taken place. The OCSP responder used is either extracted from the certificate itself, or derived by configuration; see the SSLOCSPD EFAULT R ESPONDER and SSLOCSPOVERRIDE R ESPONDER directives. Example SSLVerifyClient on SSLOCSPEnable on SSLOCSPDefaultResponder http://responder.example.com:8888/responder SSLOCSPOverrideResponder on 932 CHAPTER 10. APACHE MODULES SSLOCSPOverrideResponder Directive Description: Syntax: Default: Context: Status: Module: Force use of the default responder URI for OCSP validation SSLOCSPOverrideResponder on|off SSLOCSPOverrideResponder off server config, virtual host Extension mod ssl This option forces the configured default OCSP responder to be used during OCSP certificate validation, regardless of whether the certificate being validated references an OCSP responder. SSLOCSPProxyURL Directive Description: Syntax: Context: Status: Module: Compatibility: Proxy URL to use for OCSP requests SSLOCSPProxyURL url server config, virtual host Extension mod ssl Available in httpd 2.4.19 and later This option allows to set the URL of a HTTP proxy that should be used for all queries to OCSP responders. SSLOCSPResponderTimeout Directive Description: Syntax: Default: Context: Status: Module: Timeout for OCSP queries SSLOCSPResponderTimeout seconds SSLOCSPResponderTimeout 10 server config, virtual host Extension mod ssl This option sets the timeout for queries to OCSP responders, when SSLOCSPE NABLE is turned on. SSLOCSPResponseMaxAge Directive Description: Syntax: Default: Context: Status: Module: Maximum allowable age for OCSP responses SSLOCSPResponseMaxAge seconds SSLOCSPResponseMaxAge -1 server config, virtual host Extension mod ssl This option sets the maximum allowable age ("freshness") for OCSP responses. The default value (-1) does not enforce a maximum age, which means that OCSP responses are considered valid as long as their nextUpdate field is in the future. 10.115. APACHE MODULE MOD SSL 933 SSLOCSPResponseTimeSkew Directive Description: Syntax: Default: Context: Status: Module: Maximum allowable time skew for OCSP response validation SSLOCSPResponseTimeSkew seconds SSLOCSPResponseTimeSkew 300 server config, virtual host Extension mod ssl This option sets the maximum allowable time skew for OCSP responses (when checking their thisUpdate and nextUpdate fields). SSLOCSPUseRequestNonce Directive Description: Syntax: Default: Context: Status: Module: Compatibility: Use a nonce within OCSP queries SSLOCSPUseRequestNonce on|off SSLOCSPUseRequestNonce on server config, virtual host Extension mod ssl Available in httpd 2.4.10 and later This option determines whether queries to OCSP responders should contain a nonce or not. By default, a query nonce is always used and checked against the response’s one. When the responder does not use nonces (e.g. Microsoft OCSP Responder), this option should be turned off. SSLOpenSSLConfCmd Directive Description: Syntax: Context: Status: Module: Compatibility: Configure OpenSSL parameters through its SSL CONF API SSLOpenSSLConfCmd command-name command-value server config, virtual host Extension mod ssl Available in httpd 2.4.8 and later, if using OpenSSL 1.0.2 or later This directive exposes OpenSSL’s SSL CONF API to mod ssl, allowing a flexible configuration of OpenSSL parameters without the need of implementing additional MOD SSL directives when new features are added to OpenSSL. The set of available SSLO PEN SSLC ONF C MD commands depends on the OpenSSL version being used for MOD SSL (at least version 1.0.2 is required). For a list of supported command names, see the section Supported configuration file commands in the SSL CONF cmd(3)91 manual page for OpenSSL. Some of the SSLO PEN SSLC ONF C MD commands can be used as an alternative to existing directives (such as SSLC IPHER S UITE or SSLP ROTOCOL), though it should be noted that the syntax / allowable values for the parameters may sometimes differ. Examples SSLOpenSSLConfCmd SSLOpenSSLConfCmd SSLOpenSSLConfCmd SSLOpenSSLConfCmd SSLOpenSSLConfCmd Options -SessionTicket,ServerPreference ECDHParameters brainpoolP256r1 ServerInfoFile /usr/local/apache2/conf/server-info.pem Protocol "-ALL, TLSv1.2" SignatureAlgorithms RSA+SHA384:ECDSA+SHA256 91 http://www.openssl.org/docs/man1.0.2/ssl/SSL CONF cmd.html#SUPPORTED-CONFIGURATION-FILE-COMMANDS 934 CHAPTER 10. APACHE MODULES SSLOptions Directive Description: Syntax: Context: Override: Status: Module: Configure various SSL engine run-time options SSLOptions [+|-]option ... server config, virtual host, directory, .htaccess Options Extension mod ssl This directive can be used to control various run-time options on a per-directory basis. Normally, if multiple SSLOptions could apply to a directory, then the most specific one is taken completely; the options are not merged. However if all the options on the SSLOptions directive are preceded by a plus (+) or minus (-) symbol, the options are merged. Any options preceded by a + are added to the options currently in force, and any options preceded by a are removed from the options currently in force. The available options are: • StdEnvVars When this option is enabled, the standard set of SSL related CGI/SSI environment variables are created. This per default is disabled for performance reasons, because the information extraction step is a rather expensive operation. So one usually enables this option for CGI and SSI requests only. • ExportCertData When this option is enabled, additional CGI/SSI environment variables are created: SSL SERVER CERT, SSL CLIENT CERT and SSL CLIENT CERT CHAIN n (with n = 0,1,2,..). These contain the PEM-encoded X.509 Certificates of server and client for the current HTTPS connection and can be used by CGI scripts for deeper Certificate checking. Additionally all other certificates of the client certificate chain are provided, too. This bloats up the environment a little bit which is why you have to use this option to enable it on demand. • FakeBasicAuth When this option is enabled, the Subject Distinguished Name (DN) of the Client X509 Certificate is translated into a HTTP Basic Authorization username. This means that the standard Apache authentication methods can be used for access control. The user name is just the Subject of the Client’s X509 Certificate (can be determined by running OpenSSL’s openssl x509 command: openssl x509 -noout -subject -in certificate.crt). The optional SSLU SER NAME directive can be used to specify which part of the certificate Subject is embedded in the username. Note that no password is obtained from the user. Every entry in the user file needs this password: “xxj31ZMTZzkVA”, which is the DES-encrypted version of the word ‘password”. Those who live under MD5-based encryption (for instance under FreeBSD or BSD/OS, etc.) should use the following MD5 hash of the same word: “$1$OXLyS...$Owx8s2/m9/gfkcRVXzgoE/”. Note that the AUTH BASIC FAKE directive within MOD AUTH BASIC can be used as a more general mechanism for faking basic authentication, giving control over the structure of both the username and password. • StrictRequire This forces forbidden access when SSLRequireSSL or SSLRequire successfully decided that access should be forbidden. Usually the default is that in the case where a “Satisfy any” directive is used, and other access restrictions are passed, denial of access due to SSLRequireSSL or SSLRequire is overridden (because that’s how the Apache Satisfy mechanism should work.) But for strict access restriction you can use SSLRequireSSL and/or SSLRequire in combination with an “SSLOptions +StrictRequire”. Then an additional “Satisfy Any” has no chance once mod ssl has decided to deny access. • OptRenegotiate This enables optimized SSL connection renegotiation handling when SSL directives are used in per-directory context. By default a strict scheme is enabled where every per-directory reconfiguration of SSL parameters causes a full SSL renegotiation handshake. When this option is used mod ssl tries to avoid unnecessary handshakes by doing more granular (but still safe) parameter checks. Nevertheless these granular checks sometimes may not be what the user expects, so enable this on a per-directory basis only, please. 10.115. APACHE MODULE MOD SSL 935 • LegacyDNStringFormat This option influences how values of the SSL {CLIENT,SERVER} {I,S} DN variables are formatted. Since version 2.3.11, Apache HTTPD uses a RFC 2253 compatible format by default. This uses commas as delimiters between the attributes, allows the use of non-ASCII characters (which are converted to UTF8), escapes various special characters with backslashes, and sorts the attributes with the "C" attribute last. If LegacyDNStringFormat is set, the old format will be used which sorts the "C" attribute first, uses slashes as separators, and does not handle non-ASCII and special characters in any consistent way. Example SSLOptions +FakeBasicAuth -StrictRequire SSLOptions +StdEnvVars -ExportCertData SSLPassPhraseDialog Directive Description: Syntax: Default: Context: Status: Module: Type of pass phrase dialog for encrypted private keys SSLPassPhraseDialog type SSLPassPhraseDialog builtin server config Extension mod ssl When Apache starts up it has to read the various Certificate (see SSLC ERTIFICATE F ILE) and Private Key (see SSLC ERTIFICATE K EY F ILE) files of the SSL-enabled virtual servers. Because for security reasons the Private Key files are usually encrypted, mod ssl needs to query the administrator for a Pass Phrase in order to decrypt those files. This query can be done in two ways which can be configured by type: • builtin This is the default where an interactive terminal dialog occurs at startup time just before Apache detaches from the terminal. Here the administrator has to manually enter the Pass Phrase for each encrypted Private Key file. Because a lot of SSL-enabled virtual hosts can be configured, the following reuse-scheme is used to minimize the dialog: When a Private Key file is encrypted, all known Pass Phrases (at the beginning there are none, of course) are tried. If one of those known Pass Phrases succeeds no dialog pops up for this particular Private Key file. If none succeeded, another Pass Phrase is queried on the terminal and remembered for the next round (where it perhaps can be reused). This scheme allows mod ssl to be maximally flexible (because for N encrypted Private Key files you can use N different Pass Phrases - but then you have to enter all of them, of course) while minimizing the terminal dialog (i.e. when you use a single Pass Phrase for all N Private Key files this Pass Phrase is queried only once). • |/path/to/program [args...] This mode allows an external program to be used which acts as a pipe to a particular input device; the program is sent the standard prompt text used for the builtin mode on stdin, and is expected to write password strings on stdout. If several passwords are needed (or an incorrect password is entered), additional prompt text will be written subsequent to the first password being returned, and more passwords must then be written back. • exec:/path/to/program Here an external program is configured which is called at startup for each encrypted Private Key file. It is called with one argument, a string of the form “servername:portnumber:index” (with index being a zerobased sequence number), which indicates for which server, TCP port and certificate number it has to print the 936 CHAPTER 10. APACHE MODULES corresponding Pass Phrase to stdout. The intent is that this external program first runs security checks to make sure that the system is not compromised by an attacker, and only when these checks were passed successfully it provides the Pass Phrase. Both these security checks, and the way the Pass Phrase is determined, can be as complex as you like. Mod ssl just defines the interface: an executable program which provides the Pass Phrase on stdout. Nothing more or less! So, if you’re really paranoid about security, here is your interface. Anything else has to be left as an exercise to the administrator, because local security requirements are so different. The reuse-algorithm above is used here, too. In other words: The external program is called only once per unique Pass Phrase. Example SSLPassPhraseDialog exec:/usr/local/apache/sbin/pp-filter SSLProtocol Directive Description: Syntax: Default: Context: Status: Module: Configure usable SSL/TLS protocol versions SSLProtocol [+|-]protocol ... SSLProtocol all -SSLv3 server config, virtual host Extension mod ssl This directive can be used to control which versions of the SSL/TLS protocol will be accepted in new connections. The available (case-insensitive) protocols are: • SSLv3 This is the Secure Sockets Layer (SSL) protocol, version 3.0, from the Netscape Corporation. It is the successor to SSLv2 and the predecessor to TLSv1, but is deprecated in RFC 756892 . • TLSv1 This is the Transport Layer Security (TLS) protocol, version 1.0. It is the successor to SSLv3 and is defined in RFC 224693 . It is supported by nearly every client. • TLSv1.1 (when using OpenSSL 1.0.1 and later) A revision of the TLS 1.0 protocol, as defined in RFC 434694 . • TLSv1.2 (when using OpenSSL 1.0.1 and later) A revision of the TLS 1.1 protocol, as defined in RFC 524695 . • all This is a shortcut for “+SSLv3 +TLSv1” or - when using OpenSSL 1.0.1 and later - “+SSLv3 +TLSv1 +TLSv1.1 +TLSv1.2”, respectively (except for OpenSSL versions compiled with the “no-ssl3” configuration option, where all does not include +SSLv3). Example SSLProtocol TLSv1 92 http://www.ietf.org/rfc/rfc7568.txt 93 http://www.ietf.org/rfc/rfc2246.txt 94 http://www.ietf.org/rfc/rfc4346.txt 95 http://www.ietf.org/rfc/rfc5246.txt 10.115. APACHE MODULE MOD SSL 937 SSLProxyCACertificateFile Directive Description: Syntax: Context: Override: Status: Module: File of concatenated PEM-encoded CA Certificates for Remote Server Auth SSLProxyCACertificateFile file-path server config, virtual host, proxy section Not applicable Extension mod ssl This directive sets the all-in-one file where you can assemble the Certificates of Certification Authorities (CA) whose remote servers you deal with. These are used for Remote Server Authentication. Such a file is simply the concatenation of the various PEM-encoded Certificate files, in order of preference. This can be used alternatively and/or additionally to SSLP ROXY CAC ERTIFICATE PATH. Example SSLProxyCACertificateFile /usr/local/apache2/conf/ssl.crt/ca-bundle-remote-server.crt SSLProxyCACertificatePath Directive Description: Syntax: Context: Override: Status: Module: Directory of PEM-encoded CA Certificates for Remote Server Auth SSLProxyCACertificatePath directory-path server config, virtual host, proxy section Not applicable Extension mod ssl This directive sets the directory where you keep the Certificates of Certification Authorities (CAs) whose remote servers you deal with. These are used to verify the remote server certificate on Remote Server Authentication. The files in this directory have to be PEM-encoded and are accessed through hash filenames. So usually you can’t just place the Certificate files there: you also have to create symbolic links named hash-value.N. And you should always make sure this directory contains the appropriate symbolic links. Example SSLProxyCACertificatePath /usr/local/apache2/conf/ssl.crt/ SSLProxyCARevocationCheck Directive Description: Syntax: Default: Context: Override: Status: Module: Enable CRL-based revocation checking for Remote Server Auth SSLProxyCARevocationCheck chain|leaf|none SSLProxyCARevocationCheck none server config, virtual host, proxy section Not applicable Extension mod ssl Enables certificate revocation list (CRL) checking for the remote servers you deal with. At least one of SSLP ROX Y CAR EVOCATION F ILE or SSLP ROXY CAR EVOCATION PATH must be configured. When set to chain (recommended setting), CRL checks are applied to all certificates in the chain, while setting it to leaf limits the checks to the end-entity cert. 938 CHAPTER 10. APACHE MODULES =⇒When set to chain or leaf, CRLs must be available for successful validation Prior to version 2.3.15, CRL checking in mod ssl also succeeded when no CRL(s) were found in any of the locations configured with SSLP ROXY CAR EVOCATION F ILE or SSLP ROXYCAR EVOCATION PATH. With the introduction of this directive, the behavior has been changed: when checking is enabled, CRLs must be present for the validation to succeed - otherwise it will fail with an "unable to get certificate CRL" error. Example SSLProxyCARevocationCheck chain SSLProxyCARevocationFile Directive Description: Syntax: Context: Override: Status: Module: File of concatenated PEM-encoded CA CRLs for Remote Server Auth SSLProxyCARevocationFile file-path server config, virtual host, proxy section Not applicable Extension mod ssl This directive sets the all-in-one file where you can assemble the Certificate Revocation Lists (CRL) of Certification Authorities (CA) whose remote servers you deal with. These are used for Remote Server Authentication. Such a file is simply the concatenation of the various PEM-encoded CRL files, in order of preference. This can be used alternatively and/or additionally to SSLP ROXY CAR EVOCATION PATH. Example SSLProxyCARevocationFile /usr/local/apache2/conf/ssl.crl/ca-bundle-remote-server.crl SSLProxyCARevocationPath Directive Description: Syntax: Context: Override: Status: Module: Directory of PEM-encoded CA CRLs for Remote Server Auth SSLProxyCARevocationPath directory-path server config, virtual host, proxy section Not applicable Extension mod ssl This directive sets the directory where you keep the Certificate Revocation Lists (CRL) of Certification Authorities (CAs) whose remote servers you deal with. These are used to revoke the remote server certificate on Remote Server Authentication. The files in this directory have to be PEM-encoded and are accessed through hash filenames. So usually you have not only to place the CRL files there. Additionally you have to create symbolic links named hash-value.rN. And you should always make sure this directory contains the appropriate symbolic links. Example SSLProxyCARevocationPath /usr/local/apache2/conf/ssl.crl/ 10.115. APACHE MODULE MOD SSL 939 SSLProxyCheckPeerCN Directive Description: Syntax: Default: Context: Override: Status: Module: Whether to check the remote server certificate’s CN field SSLProxyCheckPeerCN on|off SSLProxyCheckPeerCN on server config, virtual host, proxy section Not applicable Extension mod ssl This directive sets whether the remote server certificate’s CN field is compared against the hostname of the request URL. If both are not equal a 502 status code (Bad Gateway) is sent. In 2.4.5 and later, SSLProxyCheckPeerCN has been superseded by SSLP ROXY C HECK P EER NAME, and its setting is only taken into account when SSLProxyCheckPeerName off is specified at the same time. Example SSLProxyCheckPeerCN on SSLProxyCheckPeerExpire Directive Description: Syntax: Default: Context: Override: Status: Module: Whether to check if remote server certificate is expired SSLProxyCheckPeerExpire on|off SSLProxyCheckPeerExpire on server config, virtual host, proxy section Not applicable Extension mod ssl This directive sets whether it is checked if the remote server certificate is expired or not. If the check fails a 502 status code (Bad Gateway) is sent. Example SSLProxyCheckPeerExpire on SSLProxyCheckPeerName Directive Description: Syntax: Default: Context: Override: Status: Module: Compatibility: Configure host name checking for remote server certificates SSLProxyCheckPeerName on|off SSLProxyCheckPeerName on server config, virtual host, proxy section Not applicable Extension mod ssl Apache HTTP Server 2.4.5 and later This directive configures host name checking for server certificates when mod ssl is acting as an SSL client. The check will succeed if the host name from the request URI is found in either the subjectAltName extension or (one of) the CN attribute(s) in the certificate’s subject. If the check fails, the SSL request is aborted and a 502 status code (Bad Gateway) is returned. The directive supersedes SSLP ROXY C HECK P EER CN, which only checks for the expected host name in the first CN attribute. 940 CHAPTER 10. APACHE MODULES Wildcard matching is supported in one specific flavor: subjectAltName entries of type dNSName or CN attributes starting with *. will match for any DNS name with the same number of labels and the same suffix (i.e., *.example.org matches for foo.example.org, but not for foo.bar.example.org). SSLProxyCipherSuite Directive Description: Syntax: Default: Context: Override: Status: Module: Cipher Suite available for negotiation in SSL proxy handshake SSLProxyCipherSuite cipher-spec SSLProxyCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+EXP server config, virtual host, proxy section Not applicable Extension mod ssl Equivalent to SSLCipherSuite, but for the proxy connection. Please refer to SSLC IPHER S UITE for additional information. SSLProxyEngine Directive Description: Syntax: Default: Context: Override: Status: Module: SSL Proxy Engine Operation Switch SSLProxyEngine on|off SSLProxyEngine off server config, virtual host, proxy section Not applicable Extension mod ssl This directive toggles the usage of the SSL/TLS Protocol Engine for proxy. This is usually used inside a section to enable SSL/TLS for proxy usage in a particular virtual host. By default the SSL/TLS Protocol Engine is disabled for proxy both for the main server and all configured virtual hosts. Note that the SSLProxyEngine directive should not, in general, be included in a virtual host that will be acting as a forward proxy (using or directives. SSLProxyEngine is not required to enable a forward proxy server to proxy SSL/TLS requests. Example SSLProxyEngine on #... SSLProxyMachineCertificateChainFile Directive Description: Syntax: Context: Override: Status: Module: File of concatenated PEM-encoded CA certificates to be used by the proxy for choosing a certificate SSLProxyMachineCertificateChainFile filename server config, virtual host, proxy section Not applicable Extension mod ssl 10.115. APACHE MODULE MOD SSL 941 This directive sets the all-in-one file where you keep the certificate chain for all of the client certs in use. This directive will be needed if the remote server presents a list of CA certificates that are not direct signers of one of the configured client certificates. This referenced file is simply the concatenation of the various PEM-encoded certificate files. Upon startup, each client certificate configured will be examined and a chain of trust will be constructed. ! Security warning If this directive is enabled, all of the certificates in the file will be trusted as if they were also in SSLP ROXY CAC ERTIFICATE F ILE. Example SSLProxyMachineCertificateChainFile /usr/local/apache2/conf/ssl.crt/proxyCA.pem SSLProxyMachineCertificateFile Directive Description: Syntax: Context: Override: Status: Module: File of concatenated PEM-encoded client certificates and keys to be used by the proxy SSLProxyMachineCertificateFile filename server config, virtual host, proxy section Not applicable Extension mod ssl This directive sets the all-in-one file where you keep the certificates and keys used for authentication of the proxy server to remote servers. This referenced file is simply the concatenation of the various PEM-encoded certificate files, in order of preference. Use this directive alternatively or additionally to SSLProxyMachineCertificatePath. ! Currently there is no support for encrypted private keys Example SSLProxyMachineCertificateFile /usr/local/apache2/conf/ssl.crt/proxy.pem SSLProxyMachineCertificatePath Directive Description: Syntax: Context: Override: Status: Module: Directory of PEM-encoded client certificates and keys to be used by the proxy SSLProxyMachineCertificatePath directory server config, virtual host, proxy section Not applicable Extension mod ssl This directive sets the directory where you keep the certificates and keys used for authentication of the proxy server to remote servers. The files in this directory must be PEM-encoded and are accessed through hash filenames. Additionally, you must create symbolic links named hash-value.N. And you should always make sure this directory contains the appropriate symbolic links. 942 ! CHAPTER 10. APACHE MODULES Currently there is no support for encrypted private keys Example SSLProxyMachineCertificatePath /usr/local/apache2/conf/proxy.crt/ SSLProxyProtocol Directive Description: Syntax: Default: Context: Override: Status: Module: Configure usable SSL protocol flavors for proxy usage SSLProxyProtocol [+|-]protocol ... SSLProxyProtocol all -SSLv3 server config, virtual host, proxy section Not applicable Extension mod ssl This directive can be used to control the SSL protocol flavors mod ssl should use when establishing its server environment for proxy . It will only connect to servers using one of the provided protocols. Please refer to SSLP ROTOCOL for additional information. SSLProxyVerify Directive Description: Syntax: Default: Context: Override: Status: Module: Type of remote server Certificate verification SSLProxyVerify level SSLProxyVerify none server config, virtual host, proxy section Not applicable Extension mod ssl When a proxy is configured to forward requests to a remote SSL server, this directive can be used to configure certificate verification of the remote server. The following levels are available for level: • none: no remote server Certificate is required at all • optional: the remote server may present a valid Certificate • require: the remote server has to present a valid Certificate • optional no ca: the remote server may present a valid Certificate but it need not to be (successfully) verifiable. In practice only levels none and require are really interesting, because level optional doesn’t work with all servers and level optional no ca is actually against the idea of authentication (but can be used to establish SSL test pages, etc.) Example SSLProxyVerify require 10.115. APACHE MODULE MOD SSL 943 SSLProxyVerifyDepth Directive Description: Syntax: Default: Context: Override: Status: Module: Maximum depth of CA Certificates in Remote Server Certificate verification SSLProxyVerifyDepth number SSLProxyVerifyDepth 1 server config, virtual host, proxy section Not applicable Extension mod ssl This directive sets how deeply mod ssl should verify before deciding that the remote server does not have a valid certificate. The depth actually is the maximum number of intermediate certificate issuers, i.e. the number of CA certificates which are max allowed to be followed while verifying the remote server certificate. A depth of 0 means that selfsigned remote server certificates are accepted only, the default depth of 1 means the remote server certificate can be self-signed or has to be signed by a CA which is directly known to the server (i.e. the CA’s certificate is under SSLP ROXY CAC ERTIFICATE PATH), etc. Example SSLProxyVerifyDepth 10 SSLRandomSeed Directive Description: Syntax: Context: Status: Module: Pseudo Random Number Generator (PRNG) seeding source SSLRandomSeed context source [bytes] server config Extension mod ssl This configures one or more sources for seeding the Pseudo Random Number Generator (PRNG) in OpenSSL at startup time (context is startup) and/or just before a new SSL connection is established (context is connect). This directive can only be used in the global server context because the PRNG is a global facility. The following source variants are available: • builtin This is the always available builtin seeding source. Its usage consumes minimum CPU cycles under runtime and hence can be always used without drawbacks. The source used for seeding the PRNG contains of the current time, the current process id and (when applicable) a randomly chosen 1KB extract of the interprocess scoreboard structure of Apache. The drawback is that this is not really a strong source and at startup time (where the scoreboard is still not available) this source just produces a few bytes of entropy. So you should always, at least for the startup, use an additional seeding source. • file:/path/to/source This variant uses an external file /path/to/source as the source for seeding the PRNG. When bytes is specified, only the first bytes number of bytes of the file form the entropy (and bytes is given to /path/to/source as the first argument). When bytes is not specified the whole file forms the entropy (and 0 is given to /path/to/source as the first argument). Use this especially at startup time, for instance with an available /dev/random and/or /dev/urandom devices (which usually exist on modern Unix derivatives like FreeBSD and Linux). But be careful: Usually /dev/random provides only as much entropy data as it actually has, i.e. when you request 512 bytes of entropy, but the device currently has only 100 bytes available two things can happen: On some platforms you receive only the 100 bytes while on other platforms the read blocks until enough bytes 944 CHAPTER 10. APACHE MODULES are available (which can take a long time). Here using an existing /dev/urandom is better, because it never blocks and actually gives the amount of requested data. The drawback is just that the quality of the received data may not be the best. • exec:/path/to/program This variant uses an external executable /path/to/program as the source for seeding the PRNG. When bytes is specified, only the first bytes number of bytes of its stdout contents form the entropy. When bytes is not specified, the entirety of the data produced on stdout form the entropy. Use this only at startup time when you need a very strong seeding with the help of an external program (for instance as in the example above with the truerand utility you can find in the mod ssl distribution which is based on the AT&T truerand library). Using this in the connection context slows down the server too dramatically, of course. So usually you should avoid using external programs in that context. • egd:/path/to/egd-socket (Unix only) This variant uses the Unix domain socket of the external Entropy Gathering Daemon (EGD) (see http://www.lothar.com/tech /crypto/96 ) to seed the PRNG. Use this if no random device exists on your platform. Example SSLRandomSeed SSLRandomSeed SSLRandomSeed SSLRandomSeed SSLRandomSeed SSLRandomSeed SSLRandomSeed startup startup startup startup connect connect connect builtin file:/dev/random file:/dev/urandom 1024 exec:/usr/local/bin/truerand 16 builtin file:/dev/random file:/dev/urandom 1024 SSLRenegBufferSize Directive Description: Syntax: Default: Context: Override: Status: Module: Set the size for the SSL renegotiation buffer SSLRenegBufferSize bytes SSLRenegBufferSize 131072 directory, .htaccess AuthConfig Extension mod ssl If an SSL renegotiation is required in per-location context, for example, any use of SSLV ERIFY C LIENT in a Directory or Location block, then MOD SSL must buffer any HTTP request body into memory until the new SSL handshake can be performed. This directive can be used to set the amount of memory that will be used for this buffer. ! Note that in many configurations, the client sending the request body will be untrusted so a denial of service attack by consumption of memory must be considered when changing this configuration setting. Example SSLRenegBufferSize 262144 96 http://www.lothar.com/tech/crypto/ 10.115. APACHE MODULE MOD SSL 945 SSLRequire Directive Description: Syntax: Context: Override: Status: Module: Allow access only when an arbitrarily complex boolean expression is true SSLRequire expression directory, .htaccess AuthConfig Extension mod ssl =⇒SSLRequire is deprecated SSLRequire is deprecated and should in general be replaced by Require expr (p. 519) . The so called ap expr (p. 99) syntax of Require expr is a superset of the syntax of SSLRequire, with the following exception: In SSLRequire, the comparison operators <, <=, ... are completely equivalent to the operators lt, le, ... and work in a somewhat peculiar way that first compares the length of two strings and then the lexical order. On the other hand, ap expr (p. 99) has two sets of comparison operators: The operators <, <=, ... do lexical string comparison, while the operators -lt, -le, ... do integer comparison. For the latter, there are also aliases without the leading dashes: lt, le, ... This directive specifies a general access requirement which has to be fulfilled in order to allow access. It is a very powerful directive because the requirement specification is an arbitrarily complex boolean expression containing any number of access checks. The expression must match the following syntax (given as a BNF grammar notation): expr comp ::= "true" | "false" | "!" expr | expr "&&" expr | expr "||" expr | "(" expr ")" | comp ::= | | | | | | | | | word word word word word word word word word word "==" "!=" "<" "<=" ">" ">=" "in" "in" "=˜" "!˜" word | word "eq" word word | word "ne" word word | word "lt" word word | word "le" word word | word "gt" word word | word "ge" word "{" wordlist "}" "PeerExtList(" word ")" regex regex wordlist ::= word | wordlist "," word word ::= | | | digit cstring variable function digit ::= [0-9]+ cstring ::= "..." variable ::= "%{" varname "}" 946 CHAPTER 10. APACHE MODULES function ::= funcname "(" funcargs ")" For varname any of the variables described in Environment Variables can be used. For funcname the available functions are listed in the ap expr documentation (p. 99) . The expression is parsed into an internal machine representation when the configuration is loaded, and then evaluated during request processing. In .htaccess context, the expression is both parsed and executed each time the .htaccess file is encountered during request processing. Example SSLRequire ( %{SSL_CIPHER} !˜ m/ˆ(EXP|NULL)-/ and %{SSL_CLIENT_S_DN_O} eq "Snake Oil, Ltd." and %{SSL_CLIENT_S_DN_OU} in {"Staff", "CA", "Dev"} and %{TIME_WDAY} -ge 1 and %{TIME_WDAY} -le 5 and %{TIME_HOUR} -ge 8 and %{TIME_HOUR} -le 20 or %{REMOTE_ADDR} =˜ m/ˆ192\.76\.162\.[0-9]+$/ \ \ \ \ ) \ The PeerExtList(object-ID) function expects to find zero or more instances of the X.509 certificate extension identified by the given object ID (OID) in the client certificate. The expression evaluates to true if the left-hand side string matches exactly against the value of an extension identified with this OID. (If multiple extensions with the same OID are present, at least one extension must match). Example SSLRequire "foobar" in PeerExtList("1.2.3.4.5.6") =⇒Notes on the PeerExtList function • The object ID can be specified either as a descriptive name recognized by the SSL library, such as "nsComment", or as a numeric OID, such as "1.2.3.4.5.6". • Expressions with types known to the SSL library are rendered to a string before comparison. For an extension with a type not recognized by the SSL library, mod ssl will parse the value if it is one of the primitive ASN.1 types UTF8String, IA5String, VisibleString, or BMPString. For an extension of one of these types, the string value will be converted to UTF-8 if necessary, then compared against the left-hand-side expression. See also • Environment Variables in Apache HTTP Server (p. 92) , for additional examples. • Require expr (p. 519) • Generic expression syntax in Apache HTTP Server (p. 99) SSLRequireSSL Directive Description: Syntax: Context: Override: Status: Module: Deny access when SSL is not used for the HTTP request SSLRequireSSL directory, .htaccess AuthConfig Extension mod ssl 10.115. APACHE MODULE MOD SSL 947 This directive forbids access unless HTTP over SSL (i.e. HTTPS) is enabled for the current connection. This is very handy inside the SSL-enabled virtual host or directories for defending against configuration errors that expose stuff that should be protected. When this directive is present all requests are denied which are not using SSL. Example SSLRequireSSL SSLSessionCache Directive Description: Syntax: Default: Context: Status: Module: Type of the global/inter-process SSL Session Cache SSLSessionCache type SSLSessionCache none server config Extension mod ssl This configures the storage type of the global/inter-process SSL Session Cache. This cache is an optional facility which speeds up parallel request processing. For requests to the same server process (via HTTP keep-alive), OpenSSL already caches the SSL session information locally. But because modern clients request inlined images and other data via parallel requests (usually up to four parallel requests are common) those requests are served by different pre-forked server processes. Here an inter-process cache helps to avoid unnecessary session handshakes. The following five storage types are currently supported: • none This disables the global/inter-process Session Cache. This will incur a noticeable speed penalty and may cause problems if using certain browsers, particularly if client certificates are enabled. This setting is not recommended. • nonenotnull This disables any global/inter-process Session Cache. However it does force OpenSSL to send a non-null session ID to accommodate buggy clients that require one. • dbm:/path/to/datafile This makes use of a DBM hashfile on the local disk to synchronize the local OpenSSL memory caches of the server processes. This session cache may suffer reliability issues under high load. To use this, ensure that MOD SOCACHE DBM is loaded. • shmcb:/path/to/datafile[(size)] This makes use of a high-performance cyclic buffer (approx. size bytes in size) inside a shared memory segment in RAM (established via /path/to/datafile) to synchronize the local OpenSSL memory caches of the server processes. This is the recommended session cache. To use this, ensure that MOD SOCACHE SHMCB is loaded. • dc:UNIX:/path/to/socket This makes use of the distcache97 distributed session caching libraries. The argument should specify the location of the server or proxy to be used using the distcache address syntax; for example, UNIX:/path/to/socket specifies a UNIX domain socket (typically a local dc client proxy); IP:server.example.com:9001 specifies an IP address. To use this, ensure that MOD SOCACHE DC is loaded. 97 http://distcache.sourceforge.net/ 948 CHAPTER 10. APACHE MODULES Examples SSLSessionCache dbm:/usr/local/apache/logs/ssl_gcache_data SSLSessionCache shmcb:/usr/local/apache/logs/ssl_gcache_data(512000) The ssl-cache mutex is used to serialize access to the session cache to prevent corruption. This mutex can be configured using the M UTEX directive. SSLSessionCacheTimeout Directive Description: Syntax: Default: Context: Status: Module: Compatibility: Number of seconds before an SSL session expires in the Session Cache SSLSessionCacheTimeout seconds SSLSessionCacheTimeout 300 server config, virtual host Extension mod ssl Applies also to RFC 5077 TLS session resumption in Apache 2.4.10 and later This directive sets the timeout in seconds for the information stored in the global/inter-process SSL Session Cache, the OpenSSL internal memory cache and for sessions resumed by TLS session resumption (RFC 5077). It can be set as low as 15 for testing, but should be set to higher values like 300 in real life. Example SSLSessionCacheTimeout 600 SSLSessionTicketKeyFile Directive Description: Syntax: Context: Status: Module: Compatibility: Persistent encryption/decryption key for TLS session tickets SSLSessionTicketKeyFile file-path server config, virtual host Extension mod ssl Available in httpd 2.4.0 and later, if using OpenSSL 0.9.8h or later Optionally configures a secret key for encrypting and decrypting TLS session tickets, as defined in RFC 507798 . Primarily suitable for clustered environments where TLS sessions information should be shared between multiple nodes. For single-instance httpd setups, it is recommended to not configure a ticket key file, but to rely on (random) keys generated by mod ssl at startup, instead. The ticket key file must contain 48 bytes of random data, preferrably created from a high-entropy source. On a Unix-based system, a ticket key file can be created as follows: dd if=/dev/random of=/path/to/file.tkey bs=1 count=48 Ticket keys should be rotated (replaced) on a frequent basis, as this is the only way to invalidate an existing session ticket - OpenSSL currently doesn’t allow to specify a limit for ticket lifetimes. A new ticket key only gets used after restarting the web server. All existing session tickets become invalid after a restart. ! The ticket key file contains sensitive keying material and should be protected with file permissions similar to those used for SSLC ERTIFICATE K EY F ILE. 98 http://www.ietf.org/rfc/rfc5077.txt 10.115. APACHE MODULE MOD SSL 949 SSLSessionTickets Directive Description: Syntax: Default: Context: Status: Module: Compatibility: Enable or disable use of TLS session tickets SSLSessionTickets on|off SSLSessionTickets on server config, virtual host Extension mod ssl Available in httpd 2.4.11 and later, if using OpenSSL 0.9.8f or later. This directive allows to enable or disable the use of TLS session tickets (RFC 5077). ! TLS session tickets are enabled by default. Using them without restarting the web server with an appropriate frequency (e.g. daily) compromises perfect forward secrecy. SSLSRPUnknownUserSeed Directive Description: Syntax: Context: Status: Module: Compatibility: SRP unknown user seed SSLSRPUnknownUserSeed secret-string server config, virtual host Extension mod ssl Available in httpd 2.4.4 and later, if using OpenSSL 1.0.1 or later This directive sets the seed used to fake SRP user parameters for unknown users, to avoid leaking whether a given user exists. Specify a secret string. If this directive is not used, then Apache will return the UNKNOWN PSK IDENTITY alert to clients who specify an unknown username. Example SSLSRPUnknownUserSeed "secret" SSLSRPVerifierFile Directive Description: Syntax: Context: Status: Module: Compatibility: Path to SRP verifier file SSLSRPVerifierFile file-path server config, virtual host Extension mod ssl Available in httpd 2.4.4 and later, if using OpenSSL 1.0.1 or later This directive enables TLS-SRP and sets the path to the OpenSSL SRP (Secure Remote Password) verifier file containing TLS-SRP usernames, verifiers, salts, and group parameters. Example SSLSRPVerifierFile "/path/to/file.srpv" The verifier file can be created with the openssl command line utility: Creating the SRP verifier file openssl srp -srpvfile passwd.srpv -userinfo "some info" -add username The value given with the optional -userinfo parameter is avalable in the SSL SRP USERINFO request environment variable. 950 CHAPTER 10. APACHE MODULES SSLStaplingCache Directive Description: Syntax: Context: Status: Module: Compatibility: Configures the OCSP stapling cache SSLStaplingCache type server config Extension mod ssl Available if using OpenSSL 0.9.8h or later Configures the cache used to store OCSP responses which get included in the TLS handshake if SSLU SE S TAPLING is enabled. Configuration of a cache is mandatory for OCSP stapling. With the exception of none and nonenotnull, the same storage types are supported as with SSLS ESSION C ACHE. SSLStaplingErrorCacheTimeout Directive Description: Syntax: Default: Context: Status: Module: Compatibility: Number of seconds before expiring invalid responses in the OCSP stapling cache SSLStaplingErrorCacheTimeout seconds SSLStaplingErrorCacheTimeout 600 server config, virtual host Extension mod ssl Available if using OpenSSL 0.9.8h or later Sets the timeout in seconds before invalid responses in the OCSP stapling cache (configured through SSLS TAPLING C ACHE) will expire. To set the cache timeout for valid responses, see SSLS TAPLING S TANDARD C ACHE T IMEOUT. SSLStaplingFakeTryLater Directive Description: Syntax: Default: Context: Status: Module: Compatibility: Synthesize "tryLater" responses for failed OCSP stapling queries SSLStaplingFakeTryLater on|off SSLStaplingFakeTryLater on server config, virtual host Extension mod ssl Available if using OpenSSL 0.9.8h or later When enabled and a query to an OCSP responder for stapling purposes fails, mod ssl will synthesize a "tryLater" response for the client. Only effective if SSLS TAPLING R ETURN R ESPONDER E RRORS is also enabled. SSLStaplingForceURL Directive Description: Syntax: Context: Status: Module: Compatibility: Override the OCSP responder URI specified in the certificate’s AIA extension SSLStaplingForceURL uri server config, virtual host Extension mod ssl Available if using OpenSSL 0.9.8h or later This directive overrides the URI of an OCSP responder as obtained from the authorityInfoAccess (AIA) extension of the certificate. One potential use is when a proxy is used for retrieving OCSP queries. 10.115. APACHE MODULE MOD SSL 951 SSLStaplingResponderTimeout Directive Description: Syntax: Default: Context: Status: Module: Compatibility: Timeout for OCSP stapling queries SSLStaplingResponderTimeout seconds SSLStaplingResponderTimeout 10 server config, virtual host Extension mod ssl Available if using OpenSSL 0.9.8h or later This option sets the timeout for queries to OCSP responders when SSLU SE S TAPLING is enabled and mod ssl is querying a responder for OCSP stapling purposes. SSLStaplingResponseMaxAge Directive Description: Syntax: Default: Context: Status: Module: Compatibility: Maximum allowable age for OCSP stapling responses SSLStaplingResponseMaxAge seconds SSLStaplingResponseMaxAge -1 server config, virtual host Extension mod ssl Available if using OpenSSL 0.9.8h or later This option sets the maximum allowable age ("freshness") when considering OCSP responses for stapling purposes, i.e. when SSLU SE S TAPLING is turned on. The default value (-1) does not enforce a maximum age, which means that OCSP responses are considered valid as long as their nextUpdate field is in the future. SSLStaplingResponseTimeSkew Directive Description: Syntax: Default: Context: Status: Module: Compatibility: Maximum allowable time skew for OCSP stapling response validation SSLStaplingResponseTimeSkew seconds SSLStaplingResponseTimeSkew 300 server config, virtual host Extension mod ssl Available if using OpenSSL 0.9.8h or later This option sets the maximum allowable time skew when mod ssl checks the thisUpdate and nextUpdate fields of OCSP responses which get included in the TLS handshake (OCSP stapling). Only applicable if SSLU SE S TAPLING is turned on. SSLStaplingReturnResponderErrors Directive Description: Syntax: Default: Context: Status: Module: Compatibility: Pass stapling related OCSP errors on to client SSLStaplingReturnResponderErrors on|off SSLStaplingReturnResponderErrors on server config, virtual host Extension mod ssl Available if using OpenSSL 0.9.8h or later When enabled, mod ssl will pass responses from unsuccessful stapling related OCSP queries (such as responses with an overall status other than "successful", responses with a certificate status other than "good", expired responses etc.) 952 CHAPTER 10. APACHE MODULES on to the client. If set to off, only responses indicating a certificate status of "good" will be included in the TLS handshake. SSLStaplingStandardCacheTimeout Directive Description: Syntax: Default: Context: Status: Module: Compatibility: Number of seconds before expiring responses in the OCSP stapling cache SSLStaplingStandardCacheTimeout seconds SSLStaplingStandardCacheTimeout 3600 server config, virtual host Extension mod ssl Available if using OpenSSL 0.9.8h or later Sets the timeout in seconds before responses in the OCSP stapling cache (configured through SSLS TAPLING C ACHE) will expire. This directive applies to valid responses, while SSLS TAPLING E RROR C ACHE T IMEOUT is used for controlling the timeout for invalid/unavailable responses. SSLStrictSNIVHostCheck Directive Description: Syntax: Default: Context: Status: Module: Whether to allow non-SNI clients to access a name-based virtual host. SSLStrictSNIVHostCheck on|off SSLStrictSNIVHostCheck off server config, virtual host Extension mod ssl This directive sets whether a non-SNI client is allowed to access a name-based virtual host. If set to on in the default name-based virtual host, clients that are SNI unaware will not be allowed to access any virtual host, belonging to this particular IP / port combination. If set to on in any other virtual host, SNI unaware clients are not allowed to access this particular virtual host. ! This option is only available if httpd was compiled against an SNI capable version of OpenSSL. Example SSLStrictSNIVHostCheck on SSLUserName Directive Description: Syntax: Context: Override: Status: Module: Variable name to determine user name SSLUserName varname server config, directory, .htaccess AuthConfig Extension mod ssl This directive sets the "user" field in the Apache request object. This is used by lower modules to identify the user with a character string. In particular, this may cause the environment variable REMOTE USER to be set. The varname can be any of the SSL environment variables. When the FakeBasicAuth option is enabled, this directive instead controls the value of the username embedded within the basic authentication header (see SSLOptions). 10.115. APACHE MODULE MOD SSL 953 Example SSLUserName SSL_CLIENT_S_DN_CN SSLUseStapling Directive Description: Syntax: Default: Context: Status: Module: Compatibility: Enable stapling of OCSP responses in the TLS handshake SSLUseStapling on|off SSLUseStapling off server config, virtual host Extension mod ssl Available if using OpenSSL 0.9.8h or later This option enables OCSP stapling, as defined by the "Certificate Status Request" TLS extension specified in RFC 6066. If enabled (and requested by the client), mod ssl will include an OCSP response for its own certificate in the TLS handshake. Configuring an SSLS TAPLING C ACHE is a prerequisite for enabling OCSP stapling. OCSP stapling relieves the client of querying the OCSP responder on its own, but it should be noted that with the RFC 6066 specification, the server’s CertificateStatus reply may only include an OCSP response for a single cert. For server certificates with intermediate CA certificates in their chain (the typical case nowadays), stapling in its current implementation therefore only partially achieves the stated goal of "saving roundtrips and resources" - see also RFC 696199 (TLS Multiple Certificate Status Extension). When OCSP stapling is enabled, the ssl-stapling mutex is used to control access to the OCSP stapling cache in order to prevent corruption, and the sss-stapling-refresh mutex is used to control refreshes of OCSP responses. These mutexes can be configured using the M UTEX directive. SSLVerifyClient Directive Description: Syntax: Default: Context: Override: Status: Module: Type of Client Certificate verification SSLVerifyClient level SSLVerifyClient none server config, virtual host, directory, .htaccess AuthConfig Extension mod ssl This directive sets the Certificate verification level for the Client Authentication. Notice that this directive can be used both in per-server and per-directory context. In per-server context it applies to the client authentication process used in the standard SSL handshake when a connection is established. In per-directory context it forces a SSL renegotiation with the reconfigured client verification level after the HTTP request was read but before the HTTP response is sent. The following levels are available for level: • none: no client Certificate is required at all • optional: the client may present a valid Certificate • require: the client has to present a valid Certificate • optional no ca: the client may present a valid Certificate but it need not to be (successfully) verifiable. 99 http://www.ietf.org/rfc/rfc6961.txt 954 CHAPTER 10. APACHE MODULES In practice only levels none and require are really interesting, because level optional doesn’t work with all browsers and level optional no ca is actually against the idea of authentication (but can be used to establish SSL test pages, etc.) Example SSLVerifyClient require SSLVerifyDepth Directive Description: Syntax: Default: Context: Override: Status: Module: Maximum depth of CA Certificates in Client Certificate verification SSLVerifyDepth number SSLVerifyDepth 1 server config, virtual host, directory, .htaccess AuthConfig Extension mod ssl This directive sets how deeply mod ssl should verify before deciding that the clients don’t have a valid certificate. Notice that this directive can be used both in per-server and per-directory context. In per-server context it applies to the client authentication process used in the standard SSL handshake when a connection is established. In per-directory context it forces a SSL renegotiation with the reconfigured client verification depth after the HTTP request was read but before the HTTP response is sent. The depth actually is the maximum number of intermediate certificate issuers, i.e. the number of CA certificates which are max allowed to be followed while verifying the client certificate. A depth of 0 means that self-signed client certificates are accepted only, the default depth of 1 means the client certificate can be self-signed or has to be signed by a CA which is directly known to the server (i.e. the CA’s certificate is under SSLCAC ERTIFICATE PATH), etc. Example SSLVerifyDepth 10 10.116. APACHE MODULE MOD SSL CT 10.116 955 Apache Module mod ssl ct Description: Status: ModuleIdentifier: SourceFile: Implementation of Certificate Transparency (RFC 6962) Extension ssl ct module mod ssl ct.c Summary This module provides an implementation of Certificate Transparency, in conjunction with MOD SSL and command-line tools from the certificate-transparency100 open source project. The goal of Certificate Transparency is to expose the use of server certificates which are trusted by browsers but were mistakenly or maliciously issued. More information about Certificate Transparency is available at http://www.certificate-transparency.org/101 . Key terminology used in this documentation: Certificate log A certificate log, referred to simply as log in this documentation, is a network service to which server certificates have been submitted. A user agent can confirm that the certificate of a server which it accesses has been submitted to a log which it trusts, and that the log itself has not been tampered with. Signed Certificate Timestamp (SCT) This is an acknowledgement from a log that it has accepted a valid certificate. It is signed with the log’s public key. One or more SCTs is passed to clients during the handshake, either in the ServerHello (TLS extension), certificate extension, or in a stapled OCSP response. This implementation for Apache httpd provides these features for TLS servers and proxies: • Signed Certificate Timestamps (SCTs) can be obtained from logs automatically and, in conjunction with any statically configured SCTs, sent to aware clients in the ServerHello (during the handshake). • SCTs can be received by the proxy from origin servers in the ServerHello, in a certificate extension, and/or within stapled OCSP responses; any SCTs received can be partially validated on-line and optionally queued for off-line audit. • The proxy can be configured to disallow communication with an origin server which does not provide an SCT which passes on-line validation. Configuration information about logs can be defined statically in the web server configuration or maintained in a SQLite3 database. In the latter case, MOD SSL CT will reload the database periodically, so any site-specific infrastructure for maintaining and propagating log configuration information does not have to also restart httpd to make it take effect. =⇒This module is experimental for the following reasons: • Insufficient test and review • Reliance on an unreleased version of OpenSSL (1.0.2, Beta 3 or later) for basic operation • Incomplete off-line audit capability Configuration mechanisms, format of data saved for off-line audit, and other characteristics are subject to change based on further feedback and testing. Directives • CTAuditStorage 100 https://code.google.com/p/certificate-transparency/ 101 http://www.certificate-transparency.org/ 956 CHAPTER 10. APACHE MODULES • CTLogClient • CTLogConfigDB • CTMaxSCTAge • CTProxyAwareness • CTSCTStorage • CTServerHelloSCTLimit • CTStaticLogConfig • CTStaticSCTs Server processing overview Servers need to send SCTs to their clients. SCTs in a certificate extension or stapled OCSP response will be sent without any special program logic. This module handles sending SCTs configured by the administrator or received from configured logs. The number of SCTs sent in the ServerHello (i.e., not including those in a certificate extension or stapled OCSP response) can be limited by the CTS ERVER H ELLO SCTL IMIT directive. For each server certificate, a daemon process maintains an SCT list to be sent in the ServerHello, created from statically configured SCTs as well as those received from logs. Logs marked as untrusted or with a maximum valid timestamp before the present time will be ignored. Periodically the daemon will submit certificates to a log as necessary (due to changed log configuration or age) and rebuild the concatenation of SCTs. The SCT list for a server certificate will be sent to any client that indicates awareness in the ClientHello when that particular server certificate is used. Proxy processing overview The proxy indicates Certificate Transparency awareness in the ClientHello by including the signed certificate timestamp extension. It can recognize SCTs received in the ServerHello, in an extension in the certificate for an origin server, or in a stapled OCSP response. On-line verification is attempted for each received SCT: • For any SCT, the timestamp can be checked to see if it is not yet valid based on the current time as well as any configured valid time interval for the log. • For an SCT from a log for which a public key is configured, the server signature will be checked. If verification fails for at least one SCT and verification was not successful for at least one SCT, the connection is aborted if CTP ROXYAWARENESS is set to require. Additionally, the server certificate chain and SCTs are stored for off-line verification if the CTAUDIT S TORAGE directive is configured. As an optimization, on-line verification and storing of data from the server is only performed the first time a web server child process receives the data. This saves some processing time as well as disk space. For typical reverse proxy setups, very little processing overhead will be required. Log configuration Servers and proxies use different information about logs for their processing. This log configuration can be set in two ways: 10.116. APACHE MODULE MOD SSL CT 957 • Create a log configuration database using ctlogconfig, and configure the path to that database using the CTL OG C ONFIG directive. This method of configuration supports dynamic updates; MOD SSL CT will re-read the database at intervals. Additionally, the off-line audit program ctauditscts can use this configuration to find the URL of logs. • Configure information about logs statically using the CTS TATIC L OG C ONFIG directive. As with all other directives, the server must be restarted in order to pick up changes to the directives. The information that can be configured about a log using either mechanism is described below: log id The log id is the SHA-256 hash of the log’s public key, and is part of every SCT. This is a convenient way to identify a particular log when configuring valid timestamp ranges or certain other information. public key of the log A proxy must have the public key of the log in order to check the signature in SCTs it receives which were obtained from the log. A server must have the public key of the log in order to submit certificates to it. general trust/distrust setting This is a mechanism to distrust or restore trust in a particular log, for whatever reason (including simply avoiding interaction with the log in situations where it is off-line). minimum and/or maximum valid timestamps When configured, the proxy will check that timestamps from SCTs are within the valid range. log URL The URL of the log (for its API) is required by a server in order to submit server certificates to the log. The server will submit each server certificate in order to obtain an SCT for each log with a configured URL, except when the log is also marked as distrusted or the current time is not within any configured valid timestamp range. The log URL is also needed by off-line auditing of SCTs received by a proxy. Generally, only a small subset of this information is configured for a particular log. Refer to the documentation for the CTS TATIC L OG C ONFIG directive and the ctlogconfig command for more specific information. Storing SCTs in a form consumable by mod ssl ct MOD SSL CT allows you to configure SCTs statically using the CTS TATIC SCT S directive. These must be in binary form, ready to send to a client. Sample code in the form of a Python script to build an SCT in the correct format from data received from a log can be found in Tom Ritter’s ct-tools repository102 . Refer to write-sct.py Logging CT status in the access log Proxy and server modes set the SSL CT PROXY STATUS and SSL CT CLIENT STATUS variables, respectively, to indicate if the corresponding peer is CT-aware. Proxy mode sets the SSL CT PROXY SCT SOURCES variable to indicate whether and where SCTs were obtained (ServerHello, certificate extension, etc.). These variables can be logged with the %{varname}e format of MOD LOG CONFIG. 102 https://github.com/tomrittervg/ct-tools 958 CHAPTER 10. APACHE MODULES Off-line audit for proxy Experimental support for this is implemented in the ctauditscts command, which itself relies on the verify single proof.py tool in the certificate-transparency open source project. ctauditscts can parse data for off-line audit (enabled with the CTAUDIT S TORAGE directive) and invoke verify single proof.py. Here are rough notes for using ctauditscts: • Create a virtualenv using the requirements.txt file from the certificate-transparency project and run the following steps with that virtualenv activated. • Set PYTHONPATH to include the python directory within the certificate-transparency tools. • Set PATH to include the python/ct/client/tools directory. • Run ctauditscts, passing the value of the CTAUDIT S TORAGE directive and, optionally, the path to the log configuration database. The latter will be used to look up log URLs by log id. The data saved for audit can also be used by other programs; refer to the ctauditscts source code for details on processing the data. CTAuditStorage Directive Description: Syntax: Default: Context: Status: Module: Existing directory where data for off-line audit will be stored CTAuditStorage directory none server config Extension mod ssl ct The CTAUDIT S TORAGE directive sets the name of a directory where data will be stored for off-line audit. If directory is not absolute then it is assumed to be relative to D EFAULT RUNTIME D IR. If this directive is not specified, data will not be stored for off-line audit. The directory will contain files named PID.tmp for active child processes and files named PID.out for exited child processes. These .out files are ready for off-line audit. The experimental command ctauditscts (in the httpd source tree, not currently installed) interfaces with certificate-transparency tools to perform the audit. CTLogClient Directive Description: Syntax: Default: Context: Status: Module: Location of certificate-transparency log client tool CTLogClient executable none server config Extension mod ssl ct executable is the full path to the log client tool, which is normally file cpp/client/ct (or ct.exe) within the source tree of the certificate-transparency103 open source project. An alternative implementation could be used to retrieve SCTs for a server certificate as long as the command-line interface is equivalent. If this directive is not configured, server certificates cannot be submitted to logs in order to obtain SCTs; thus, only admin-managed SCTs or SCTs in certificate extensions will be provided to clients. 103 https://code.google.com/p/certificate-transparency/ 10.116. APACHE MODULE MOD SSL CT 959 CTLogConfigDB Directive Description: Syntax: Default: Context: Status: Module: Log configuration database supporting dynamic updates CTLogConfigDB filename none server config Extension mod ssl ct The CTL OG C ONFIG DB directive sets the name of a database containing configuration about known logs. If filename is not absolute then it is assumed to be relative to S ERVER ROOT. Refer to the documentation for the ctlogconfig program, which manages the database. CTMaxSCTAge Directive Description: Syntax: Default: Context: Status: Module: Maximum age of SCT obtained from a log, before it will be refreshed CTMaxSCTAge num-seconds 1 day server config Extension mod ssl ct Server certificates with SCTs which are older than this maximum age will be resubmitted to configured logs. Generally the log will return the same SCT as before, but that is subject to log operation. SCTs will be refreshed as necessary during normal server operation, with new SCTs returned to clients as they become available. CTProxyAwareness Directive Description: Syntax: Default: Context: Status: Module: Level of CT awareness and enforcement for a proxy CTProxyAwareness oblivious|aware|require aware server config, virtual host Extension mod ssl ct This directive controls awareness and checks for valid SCTs for a proxy. Several options are available: oblivious The proxy will neither ask for nor examine SCTs. Certificate Transparency processing for the proxy is completely disabled. aware The proxy will perform all appropriate Certificate Transparency processing, such as asking for and examining SCTs. However, the proxy will not disallow communication if the origin server does not provide any valid SCTs. require The proxy will abort communication with the origin server if it does not provide at least one SCT which passes on-line validation. 960 CHAPTER 10. APACHE MODULES CTSCTStorage Directive Description: Syntax: Default: Context: Status: Module: Existing directory where SCTs are managed CTSCTStorage directory none server config Extension mod ssl ct The CTSCTS TORAGE directive sets the name of a directory where SCTs and SCT lists will be stored. If directory is not absolute then it is assumed to be relative to D EFAULT RUNTIME D IR. A subdirectory for each server certificate contains information relative to that certificate; the name of the subdirectory is the SHA-256 hash of the certificate. The certificate-specific directory contains SCTs retrieved from configured logs, SCT lists prepared from statically configured SCTs and retrieved SCTs, and other information used for managing SCTs. CTServerHelloSCTLimit Directive Description: Syntax: Default: Context: Status: Module: Limit on number of SCTs that can be returned in ServerHello CTServerHelloSCTLimit limit 100 server config Extension mod ssl ct This directive can be used to limit the number of SCTs which can be returned by a TLS server in ServerHello, in case the number of configured logs and statically-defined SCTs is relatively high. Typically only a few SCTs would be available, so this directive is only needed in special circumstances. The directive does not take into account SCTs which may be provided in certificate extensions or in stapled OCSP responses. CTStaticLogConfig Directive Description: Syntax: Default: Context: Status: Module: Static configuration of information about a log CTStaticLogConfig log-id|- public-key-file|- 1|0|min-timestamp|- max-timestamp|- log-URL|none server config Extension mod ssl ct This directive is used to configure information about a particular log. This directive is appropriate when configuration information changes rarely. If dynamic configuration updates must be supported, refer to the CTL OG C ONFIG DB directive. Each of the six fields must be specified, but usually only a small amount of information must be configured for each log; use - when no information is available for the field. For example, in support of a server-only configuration (i.e., no proxy), the administrator might configure only the log URL to be used when submitting server certificates and obtaining a Signed Certificate Timestamp. The fields are defined as follows: 10.116. APACHE MODULE MOD SSL CT 961 log-id This is the id of the log, which is the SHA-256 hash of the log’s public key, provided in hexadecimal format. This string is 64 characters in length. This field should be omitted when public-key-file is provided. public-key-file This is the name of a file containing the PEM encoding of the log’s public key. If the name is not absolute, then it is assumed to be relative to S ERVER ROOT. trust/distrust Set this field to 1 to distrust this log, or to otherwise avoid using it for server certificate submission. Set this to - or 0 (the default) to treat the log normally. min-timestamp and max-timestamp A timestamp is a time as expressed in the number of milliseconds since the epoch, ignoring leap seconds. This is the form of time used in Signed Certificate Timestamps. This must be provided as a decimal number. Specify - for one of the timestamps if it is unknown. For example, when configuring the minimum valid timestamp for a log which remains valid, specify - for max-timestamp. SCTs received from this log by the proxy are invalid if the timestamp is older than min-timestamp or newer than max-timestamp. log-URL This is the URL of the log, for use in submitting server certificates and in turn obtaining an SCT to be sent to clients. See also • Log configuration contains more general information about the fields which can be configured with this directive. CTStaticSCTs Directive Description: Syntax: Default: Context: Status: Module: Static configuration of one or more SCTs for a server certificate CTStaticSCTs certificate-pem-file sct-directory none server config Extension mod ssl ct This directive is used to statically define one or more SCTs corresponding to a server certificate. This mechanism can be used instead of or in addition to dynamically obtaining SCTs from configured logs. Any changes to the set of SCTs for a particular server certificate will be adopted dynamically without the need to restart the server. certificate-pem-file refers to the server certificate in PEM format. If the name is not absolute, then it is assumed to be relative to S ERVER ROOT. sct-directory should contain one or more files with extension .sct, representing one or more SCTs corresponding to the server certificate. If sct-directory is not absolute, then it is assumed to be relative to S ERVER ROOT. If sct-directory is empty, no error will be raised. This directive could be used to identify directories of SCTs maintained by other infrastructure, provided that they are saved in binary format with file extension .sct 962 CHAPTER 10. APACHE MODULES 10.117 Apache Module mod status Description: Status: ModuleIdentifier: SourceFile: Provides information on server activity and performance Base status module mod status.c Summary The Status module allows a server administrator to find out how well their server is performing. A HTML page is presented that gives the current server statistics in an easily readable form. If required this page can be made to automatically refresh (given a compatible browser). Another page gives a simple machine-readable list of the current server state. The details given are: • The number of worker serving requests • The number of idle worker • The status of each worker, the number of requests that worker has performed and the total number of bytes served by the worker (*) • A total number of accesses and byte count served (*) • The time the server was started/restarted and the time it has been running for • Averages giving the number of requests per second, the number of bytes served per second and the average number of bytes per request (*) • The current percentage CPU used by each worker and in total by all workers combined (*) • The current hosts and requests being processed (*) The lines marked "(*)" are only available if E XTENDED S TATUS is On. In version 2.3.6, loading mod status will toggle E XTENDED S TATUS On by default. Directives This module provides no directives. Enabling Status Support To enable status reports only for browsers from the example.com domain add this code to your httpd.conf configuration file SetHandler server-status Require host example.com You can now access server statistics by http://your.server.name/server-status using a Web browser to access the page Automatic Updates You can get the status page to update itself automatically if you have a browser that supports "refresh". Access the page http://your.server.name/server-status?refresh=N to refresh the page every N seconds. 10.117. APACHE MODULE MOD STATUS 963 Machine Readable Status File A machine-readable version of the status file is available by accessing the page http://your.server.name/server-status?auto. This is useful when automatically run, see the Perl program log server status, which you will find in the /support directory of your Apache HTTP Server installation. is loaded into the server, its handler capability is =⇒Itavailable should be noted that if in all configuration files, including per-directory files (e.g., .htaccess). This MOD STATUS may have security-related ramifications for your site. Using server-status to troubleshoot The server-status page may be used as a starting place for troubleshooting a situation where your server is consuming all available resources (CPU or memory), and you wish to identify which requests or clients are causing the problem. First, ensure that you have E XTENDED S TATUS set on, so that you can see the full request and client information for each child or thread. Now look in your process list (using top, or similar process viewing utility) to identify the specific processes that are the main culprits. Order the output of top by CPU usage, or memory usage, depending on what problem you’re trying to address. Reload the server-status page, and look for those process ids, and you’ll be able to see what request is being served by that process, for what client. Requests are transient, so you may need to try several times before you catch it in the act, so to speak. This process should give you some idea what client, or what type of requests, are primarily responsible for your load problems. Often you will identify a particular web application that is misbehaving, or a particular client that is attacking your site. 964 CHAPTER 10. APACHE MODULES 10.118 Apache Module mod substitute Description: Status: ModuleIdentifier: SourceFile: Perform search and replace operations on response bodies Extension substitute module mod substitute.c Summary MOD SUBSTITUTE provides a mechanism to perform both regular expression and fixed string substitutions on response bodies. Directives • Substitute • SubstituteInheritBefore • SubstituteMaxLineLength Substitute Directive Description: Syntax: Context: Override: Status: Module: Pattern to filter the response content Substitute s/pattern/substitution/[infq] directory, .htaccess FileInfo Extension mod substitute The S UBSTITUTE directive specifies a search and replace pattern to apply to the response body. The meaning of the pattern can be modified by using any combination of these flags: i Perform a case-insensitive match. n By default the pattern is treated as a regular expression. Using the n flag forces the pattern to be treated as a fixed string. f The f flag causes mod substitute to flatten the result of a substitution allowing for later substitutions to take place on the boundary of this one. This is the default. q The q flag causes mod substitute to not flatten the buckets after each substitution. This can result in much faster response and a decrease in memory utilization, but should only be used if there is no possibility that the result of one substitution will ever match a pattern or regex of a subsequent one. Example AddOutputFilterByType SUBSTITUTE text/html Substitute "s/foo/bar/ni" If either the pattern or the substitution contain a slash character then an alternative delimiter should be used: 10.118. APACHE MODULE MOD SUBSTITUTE 965 Example of using an alternate delimiter AddOutputFilterByType SUBSTITUTE text/html Substitute "s|
|
|i" Backreferences can be used in the comparison and in the substitution, when regular expressions are used, as illustrated in the following example: Example of using backreferences and captures AddOutputFilterByType SUBSTITUTE text/html # "foo=k,bar=k" -> "foo/bar=k" Substitute "s|foo=(\w+),bar=\1|foo/bar=$1" A common use scenario for mod substitute is the situation in which a front-end server proxies requests to a back-end server which returns HTML with hard-coded embedded URLs that refer to the back-end server. These URLs don’t work for the end-user, since the back-end server is unreachable. In this case, mod substitute can be used to rewrite those URLs into something that will work from the front end: Rewriting URLs embedded in proxied content ProxyPass "/blog/" "http://internal.blog.example.com" ProxyPassReverse "/blog/" "http://internal.blog.example.com/" Substitute "s|http://internal.blog.example.com/|http://www.example.com/blog/|i" P ROXY PASS R EVERSE modifies any Location (redirect) headers that are sent by the back-end server, and, in this example, S UBSTITUTE takes care of the rest of the problem by fixing up the HTML response as well. SubstituteInheritBefore Directive Description: Syntax: Default: Context: Override: Status: Module: Compatibility: Change the merge order of inherited patterns SubstituteInheritBefore on|off SubstituteInheritBefore on directory, .htaccess FileInfo Extension mod substitute Available in httpd 2.4.17 and later Whether to apply the inherited S UBSTITUTE patterns first (on), or after the ones of the current context (off). The latter was the default in versions 2.4 and earlier, but changed starting with 2.5, hence S UBSTITUTE I NHERIT B EFORE set to off allows to restore the legacy behaviour. S UBSTITUTE I NHERIT B EFORE is itself inherited, hence contexts that inherit it (those that don’t specify their own S UBSTITUTE I NHERIT B EFORE value) will apply the closest defined merge order. 966 CHAPTER 10. APACHE MODULES SubstituteMaxLineLength Directive Description: Syntax: Default: Context: Override: Status: Module: Compatibility: Set the maximum line size SubstituteMaxLineLength bytes(b|B|k|K|m|M|g|G) SubstituteMaxLineLength 1m directory, .htaccess FileInfo Extension mod substitute Available in httpd 2.4.11 and later The maximum line size handled by MOD SUBSTITUTE is limited to restrict memory use. The limit can be configured using S UBSTITUTE M AX L INE L ENGTH. The value can be given as the number of bytes and can be suffixed with a single letter b, B, k, K, m, M, g, G to provide the size in bytes, kilobytes, megabytes or gigabytes respectively. Example AddOutputFilterByType SUBSTITUTE text/html SubstituteMaxLineLength 10m Substitute "s/foo/bar/ni" 10.119. APACHE MODULE MOD SUEXEC 10.119 967 Apache Module mod suexec Description: Status: ModuleIdentifier: SourceFile: Allows CGI scripts to run as a specified user and Group Extension suexec module mod suexec.c Summary This module, in combination with the suexec support program allows CGI scripts to run as a specified user and Group. Directives • SuexecUserGroup See also • SuEXEC support (p. 115) SuexecUserGroup Directive Description: Syntax: Context: Status: Module: User and group for CGI programs to run as SuexecUserGroup User Group server config, virtual host Extension mod suexec The S UEXEC U SER G ROUP directive allows you to specify a user and group for CGI programs to run as. Non-CGI requests are still processed with the user specified in the U SER directive. Example SuexecUserGroup nobody nogroup Startup will fail if this directive is specified but the suEXEC feature is disabled. See also • S UEXEC 968 10.120 CHAPTER 10. APACHE MODULES Apache Module mod syslog Description: Status: ModuleIdentifier: SourceFile: Provides "syslog" ErrorLog provider Extension syslog module mod syslog.c Summary This module provides "syslog" ErrorLog provider. It allows logging error messages via syslogd(8). Directives This module provides no directives. Examples Using syslog in ErrorLog directive (see CORE) instead of a filename enables logging via syslogd(8) if the system supports it. The default is to use syslog facility local7, but you can override this by using the syslog:facility syntax where facility can be one of the names usually documented in syslog(1). The facility is effectively global, and if it is changed in individual virtual hosts, the final facility specified affects the entire server. ErrorLog syslog:user 10.121. APACHE MODULE MOD SYSTEMD 10.121 969 Apache Module mod systemd Description: Status: ModuleIdentifier: SourceFile: Provides better support for systemd integration Extension systemd module mod systemd.c Summary This module provides support for systemd integration. It allows starting httpd as a service with systemd Type=notify (see systemd.service(5) manual page for more information). It also provides statistics in systemctl status output and adds various directives useful for systemd integration. Directives • IdleShutdown IdleShutdown Directive Description: Syntax: Default: Context: Status: Module: Enable shutting down the httpd when it is idle for some time. IdleShutdown seconds IdleShutdown 0 server config Extension mod systemd The I DLE S HUTDOWN directive enables shutting down the httpd when it is idle for some time. The idleness is based on bytes served, so if there are no bytes sent for some time defined by this directive, httpd will shutdown. By default, IdleShutdown is set to 0 meaning this feature is disabled. This feature is useful in a combination with systemd socket activation (see systemd.socket(5) manual page). When httpd is started by systemd on some request, using this directive you can stop the httpd automatically when all the requests are served. ! Implementation warning Because of implementation details, idleness is checked only every 10 seconds. That means that if you specify IdleShutdown 14, httpd will stop itself after 20 seconds of idleness. 970 CHAPTER 10. APACHE MODULES 10.122 Apache Module mod unique id Description: Status: ModuleIdentifier: SourceFile: Provides an environment variable with a unique identifier for each request Extension unique id module mod unique id.c Summary This module provides a magic token for each request which is guaranteed to be unique across "all" requests under very specific conditions. The unique identifier is even unique across multiple machines in a properly configured cluster of machines. The environment variable UNIQUE ID is set to the identifier for each request. Unique identifiers are useful for various reasons which are beyond the scope of this document. Directives This module provides no directives. Theory First a brief recap of how the Apache server works on Unix machines. This feature currently isn’t supported on Windows NT. On Unix machines, Apache creates several children, the children process requests one at a time. Each child can serve multiple requests in its lifetime. For the purpose of this discussion, the children don’t share any data with each other. We’ll refer to the children as httpd processes. Your website has one or more machines under your administrative control, together we’ll call them a cluster of machines. Each machine can possibly run multiple instances of Apache. All of these collectively are considered "the universe", and with certain assumptions we’ll show that in this universe we can generate unique identifiers for each request, without extensive communication between machines in the cluster. The machines in your cluster should satisfy these requirements. (Even if you have only one machine you should synchronize its clock with NTP.) • The machines’ times are synchronized via NTP or other network time protocol. • The machines’ hostnames all differ, such that the module can do a hostname lookup on the hostname and receive a different IP address for each machine in the cluster. As far as operating system assumptions go, we assume that pids (process ids) fit in 32-bits. If the operating system uses more than 32-bits for a pid, the fix is trivial but must be performed in the code. Given those assumptions, at a single point in time we can identify any httpd process on any machine in the cluster from all other httpd processes. The machine’s IP address and the pid of the httpd process are sufficient to do this. A httpd process can handle multiple requests simultaneously if you use a multi-threaded MPM. In order to identify threads, we use a thread index Apache httpd uses internally. So in order to generate unique identifiers for requests we need only distinguish between different points in time. To distinguish time we will use a Unix timestamp (seconds since January 1, 1970 UTC), and a 16-bit counter. The timestamp has only one second granularity, so the counter is used to represent up to 65536 values during a single second. The quadruple ( ip addr, pid, time stamp, counter ) is sufficient to enumerate 65536 requests per second per httpd process. There are issues however with pid reuse over time, and the counter is used to alleviate this issue. When an httpd child is created, the counter is initialized with ( current microseconds divided by 10 ) modulo 65536 (this formula was chosen to eliminate some variance problems with the low order bits of the microsecond timers on some systems). When a unique identifier is generated, the time stamp used is the time the request arrived at the web server. The counter is incremented every time an identifier is generated (and allowed to roll over). 10.122. APACHE MODULE MOD UNIQUE ID 971 The kernel generates a pid for each process as it forks the process, and pids are allowed to roll over (they’re 16-bits on many Unixes, but newer systems have expanded to 32-bits). So over time the same pid will be reused. However unless it is reused within the same second, it does not destroy the uniqueness of our quadruple. That is, we assume the system does not spawn 65536 processes in a one second interval (it may even be 32768 processes on some Unixes, but even this isn’t likely to happen). Suppose that time repeats itself for some reason. That is, suppose that the system’s clock is screwed up and it revisits a past time (or it is too far forward, is reset correctly, and then revisits the future time). In this case we can easily show that we can get pid and time stamp reuse. The choice of initializer for the counter is intended to help defeat this. Note that we really want a random number to initialize the counter, but there aren’t any readily available numbers on most systems (i.e., you can’t use rand() because you need to seed the generator, and can’t seed it with the time because time, at least at one second resolution, has repeated itself). This is not a perfect defense. How good a defense is it? Suppose that one of your machines serves at most 500 requests per second (which is a very reasonable upper bound at this writing, because systems generally do more than just shovel out static files). To do that it will require a number of children which depends on how many concurrent clients you have. But we’ll be pessimistic and suppose that a single child is able to serve 500 requests per second. There are 1000 possible starting counter values such that two sequences of 500 requests overlap. So there is a 1.5% chance that if time (at one second resolution) repeats itself this child will repeat a counter value, and uniqueness will be broken. This was a very pessimistic example, and with real world values it’s even less likely to occur. If your system is such that it’s still likely to occur, then perhaps you should make the counter 32 bits (by editing the code). You may be concerned about the clock being "set back" during summer daylight savings. However this isn’t an issue because the times used here are UTC, which "always" go forward. Note that x86 based Unixes may need proper configuration for this to be true – they should be configured to assume that the motherboard clock is on UTC and compensate appropriately. But even still, if you’re running NTP then your UTC time will be correct very shortly after reboot. The UNIQUE ID environment variable is constructed by encoding the 144-bit (32-bit IP address, 32 bit pid, 32 bit time stamp, 16 bit counter, 32 bit thread index) quadruple using the alphabet [A-Za-z0-9@-] in a manner similar to MIME base64 encoding, producing 24 characters. The MIME base64 alphabet is actually [A-Za-z0-9+/] however + and / need to be specially encoded in URLs, which makes them less desirable. All values are encoded in network byte ordering so that the encoding is comparable across architectures of different byte ordering. The actual ordering of the encoding is: time stamp, IP address, pid, counter. This ordering has a purpose, but it should be emphasized that applications should not dissect the encoding. Applications should treat the entire encoded UNIQUE ID as an opaque token, which can be compared against other UNIQUE IDs for equality only. The ordering was chosen such that it’s possible to change the encoding in the future without worrying about collision with an existing database of UNIQUE IDs. The new encodings should also keep the time stamp as the first element, and can otherwise use the same alphabet and bit length. Since the time stamps are essentially an increasing sequence, it’s sufficient to have a flag second in which all machines in the cluster stop serving any request, and stop using the old encoding format. Afterwards they can resume requests and begin issuing the new encodings. This we believe is a relatively portable solution to this problem. The identifiers generated have essentially an infinite life-time because future identifiers can be made longer as required. Essentially no communication is required between machines in the cluster (only NTP synchronization is required, which is low overhead), and no communication between httpd processes is required (the communication is implicit in the pid value assigned by the kernel). In very specific situations the identifier can be shortened, but more information needs to be assumed (for example the 32-bit IP address is overkill for any site, but there is no portable shorter replacement for it). 972 CHAPTER 10. APACHE MODULES 10.123 Apache Module mod unixd Description: Status: ModuleIdentifier: SourceFile: Basic (required) security for Unix-family platforms. Base unixd module mod unixd.c Directives • ChrootDir • Group • Suexec • User See also • suEXEC support (p. 115) ChrootDir Directive Description: Syntax: Default: Context: Status: Module: Directory for apache to run chroot(8) after startup. ChrootDir /path/to/directory none server config Base MOD UNIXD This directive tells the server to chroot(8) to the specified directory after startup, but before accepting requests over the ’net. Note that running the server under chroot is not simple, and requires additional setup, particularly if you are running scripts such as CGI or PHP. Please make sure you are properly familiar with the operation of chroot before attempting to use this feature. Group Directive Description: Syntax: Default: Context: Status: Module: Group under which the server will answer requests Group unix-group Group #-1 server config Base mod unixd The G ROUP directive sets the group under which the server will answer requests. In order to use this directive, the server must be run initially as root. If you start the server as a non-root user, it will fail to change to the specified group, and will instead continue to run as the group of the original user. Unix-group is one of: A group name Refers to the given group by name. # followed by a group number. Refers to a group by its number. 10.123. APACHE MODULE MOD UNIXD 973 Example Group www-group It is recommended that you set up a new group specifically for running the server. Some admins use user nobody, but this is not always possible or desirable. ! Security Don’t set G ROUP (or U SER) to root unless you know exactly what you are doing, and what the dangers are. See also • VH OST G ROUP • S UEXEC U SER G ROUP Suexec Directive Description: Syntax: Default: Context: Status: Module: Enable or disable the suEXEC feature Suexec On|Off On if suexec binary exists with proper owner and mode, Off otherwise server config Base mod unixd When On, startup will fail if the suexec binary doesn’t exist or has an invalid owner or file mode. When Off, suEXEC will be disabled even if the suexec binary exists and has a valid owner and file mode. User Directive Description: Syntax: Default: Context: Status: Module: The userid under which the server will answer requests User unix-userid User #-1 server config Base mod unixd The U SER directive sets the user ID as which the server will answer requests. In order to use this directive, the server must be run initially as root. If you start the server as a non-root user, it will fail to change to the lesser privileged user, and will instead continue to run as that original user. If you do start the server as root, then it is normal for the parent process to remain running as root. Unix-userid is one of: A username Refers to the given user by name. # followed by a user number. Refers to a user by its number. The user should have no privileges that result in it being able to access files that are not intended to be visible to the outside world, and similarly, the user should not be able to execute code that is not meant for HTTP requests. It is recommended that you set up a new user and group specifically for running the server. Some admins use user nobody, but this is not always desirable, since the nobody user can have other uses on the system. 974 ! CHAPTER 10. APACHE MODULES Security Don’t set U SER (or G ROUP) to root unless you know exactly what you are doing, and what the dangers are. See also • VH OST U SER • S UEXEC U SER G ROUP 10.124. APACHE MODULE MOD USERDIR 10.124 975 Apache Module mod userdir Description: Status: ModuleIdentifier: SourceFile: User-specific directories Base userdir module mod userdir.c Summary This module allows user-specific directories to be accessed using the http://example.com/˜user/ syntax. Directives • UserDir See also • Mapping URLs to the Filesystem (p. 64) • public html tutorial (p. 258) UserDir Directive Description: Syntax: Context: Status: Module: Location of the user-specific directories UserDir directory-filename [directory-filename] ... server config, virtual host Base mod userdir The U SER D IR directive sets the real directory in a user’s home directory to use when a request for a document for a user is received. Directory-filename is one of the following: • The name of a directory or a pattern such as those shown below. • The keyword disabled. This turns off all username-to-directory translations except those explicitly named with the enabled keyword (see below). • The keyword disabled followed by a space-delimited list of usernames. Usernames that appear in such a list will never have directory translation performed, even if they appear in an enabled clause. • The keyword enabled followed by a space-delimited list of usernames. These usernames will have directory translation performed even if a global disable is in effect, but not if they also appear in a disabled clause. If neither the enabled nor the disabled keywords appear in the U SERDIR directive, the argument is treated as a filename pattern, and is used to turn the name into a directory specification. A request for http://www.example.com/˜bob/one/two.html will be translated to: UserDir directive used Translated path UserDir public html UserDir /usr/web UserDir /home/*/www ˜bob/public html/one/two.html /usr/web/bob/one/two.html /home/bob/www/one/two.html The following directives will send redirects to the client: UserDir directive used Translated path UserDir http://www.example.com/users UserDir http://www.example.com/*/usr UserDir http://www.example.com/˜*/ http://www.example.com/users/bob/one/two.html http://www.example.com/bob/usr/one/two.html http://www.example.com/˜bob/one/two.html 976 CHAPTER 10. APACHE MODULES =⇒"/˜root" Be careful when using this directive; for instance, "UserDir ./" would map to "/" - which is probably undesirable. It is strongly recommended that your configuration include a "UserDir disabled root" declaration. See also the D IRECTORY directive and the Security Tips (p. 364) page for more information. Additional examples: To allow a few users to have UserDir directories, but not anyone else, use the following: UserDir disabled UserDir enabled user1 user2 user3 To allow most users to have UserDir directories, but deny this to a few, use the following: UserDir disabled user4 user5 user6 It is also possible to specify alternative user directories. If you use a command like: UserDir "public_html" "/usr/web" "http://www.example.com/" With a request for http://www.example.com/˜bob/one/two.html, will try to find the page at ˜bob/public html/one/two.html first, then /usr/web/bob/one/two.html, and finally it will send a redirect to http://www.example.com/bob/one/two.html. If you add a redirect, it must be the last alternative in the list. Apache httpd cannot determine if the redirect succeeded or not, so if you have the redirect earlier in the list, that will always be the alternative that is used. User directory substitution is not active by default in versions 2.1.4 and later. In earlier versions, UserDir public html was assumed if no U SER D IR directive was present. =⇒Merging details Lists of specific enabled and disabled users are replaced, not merged, from global to virtual host scope See also • Per-user web directories tutorial (p. 258) 10.125. APACHE MODULE MOD USERTRACK 10.125 977 Apache Module mod usertrack Description: Status: ModuleIdentifier: SourceFile: Clickstream logging of user activity on a site Extension usertrack module mod usertrack.c Summary Provides tracking of a user through your website via browser cookies. Directives • CookieDomain • CookieExpires • CookieName • CookieStyle • CookieTracking Logging MOD USERTRACK sets a cookie which can be logged via MOD LOG CONFIG configurable logging formats: LogFormat "%{Apache}n %r %t" usertrack CustomLog "logs/clickstream.log" usertrack CookieDomain Directive Description: Syntax: Context: Override: Status: Module: The domain to which the tracking cookie applies CookieDomain domain server config, virtual host, directory, .htaccess FileInfo Extension mod usertrack This directive controls the setting of the domain to which the tracking cookie applies. If not present, no domain is included in the cookie header field. The domain string must begin with a dot, and must include at least one embedded dot. That is, .example.com is legal, but www.example.com and .com are not. =⇒Most browsers in use today will not allow cookies to be set for a two-part top level domain, such as .co.uk, although such a domain ostensibly fulfills the requirements above. These domains are equivalent to top level domains such as .com, and allowing such cookies may be a security risk. Thus, if you are under a two-part top level domain, you should still use your actual domain, as you would with any other top level domain (for example .example.co.uk). CookieDomain .example.com 978 CHAPTER 10. APACHE MODULES CookieExpires Directive Description: Syntax: Context: Override: Status: Module: Expiry time for the tracking cookie CookieExpires expiry-period server config, virtual host, directory, .htaccess FileInfo Extension mod usertrack When used, this directive sets an expiry time on the cookie generated by the usertrack module. The expiry-period can be given either as a number of seconds, or in the format such as "2 weeks 3 days 7 hours". Valid denominations are: years, months, weeks, days, hours, minutes and seconds. If the expiry time is in any format other than one number indicating the number of seconds, it must be enclosed by double quotes. If this directive is not used, cookies last only for the current browser session. CookieExpires "3 weeks" CookieName Directive Description: Syntax: Default: Context: Override: Status: Module: Name of the tracking cookie CookieName token CookieName Apache server config, virtual host, directory, .htaccess FileInfo Extension mod usertrack This directive allows you to change the name of the cookie this module uses for its tracking purposes. By default the cookie is named "Apache". You must specify a valid cookie name; results are unpredictable if you use a name containing unusual characters. Valid characters include A-Z, a-z, 0-9, " ", and "-". CookieName clicktrack CookieStyle Directive Description: Syntax: Default: Context: Override: Status: Module: Format of the cookie header field CookieStyle Netscape|Cookie|Cookie2|RFC2109|RFC2965 CookieStyle Netscape server config, virtual host, directory, .htaccess FileInfo Extension mod usertrack This directive controls the format of the cookie header field. The three formats allowed are: • Netscape, which is the original but now deprecated syntax. This is the default, and the syntax Apache has historically used. • Cookie or RFC2109, which is the syntax that superseded the Netscape syntax. • Cookie2 or RFC2965, which is the most current cookie syntax. 10.125. APACHE MODULE MOD USERTRACK 979 Not all clients can understand all of these formats, but you should use the newest one that is generally acceptable to your users’ browsers. At the time of writing, most browsers support all three of these formats, with Cookie2 being the preferred format. CookieStyle Cookie2 CookieTracking Directive Description: Syntax: Default: Context: Override: Status: Module: Enables tracking cookie CookieTracking on|off CookieTracking off server config, virtual host, directory, .htaccess FileInfo Extension mod usertrack When MOD USERTRACK is loaded, and CookieTracking on is set, Apache will send a user-tracking cookie for all new requests. This directive can be used to turn this behavior on or off on a per-server or per-directory basis. By default, enabling MOD USERTRACK will not activate cookies. CookieTracking on 980 CHAPTER 10. APACHE MODULES 10.126 Apache Module mod version Description: Status: ModuleIdentifier: SourceFile: Version dependent configuration Extension version module mod version.c Summary This module is designed for the use in test suites and large networks which have to deal with different httpd versions and different configurations. It provides a new container – , which allows a flexible version checking including numeric comparisons and regular expressions. Examples # current httpd version is exactly 2.4.2 = 2.5> # use really new features :-) See below for further possibilities. Directives • IfVersion Directive Description: Syntax: Context: Override: Status: Module: contains version dependent configuration ... server config, virtual host, directory, .htaccess All Extension mod version The section encloses configuration directives which are executed only if the httpd version matches the desired criteria. For normal (numeric) comparisons the version argument has the format major[.minor[.patch]], e.g. 2.1.0 or 2.2. minor and patch are optional. If these numbers are omitted, they are assumed to be zero. The following numerical operators are possible: operator description = or == > >= < <= httpd version is equal httpd version is greater than httpd version is greater or equal httpd version is less than httpd version is less or equal Example = 2.3> # this happens only in versions greater or # equal 2.3.0. 10.126. APACHE MODULE MOD VERSION 981 Besides the numerical comparison it is possible to match a regular expression against the httpd version. There are two ways to write it: operator description = or == ˜ version has the form /regex/ version has the form regex Example # e.g. workaround for buggy versions In order to reverse the meaning, all operators can be preceded by an exclamation mark (!): # not for those versions If the operator is omitted, it is assumed to be =. 982 CHAPTER 10. APACHE MODULES 10.127 Apache Module mod vhost alias Description: Status: ModuleIdentifier: SourceFile: Provides for dynamically configured mass virtual hosting Extension vhost alias module mod vhost alias.c Summary This module creates dynamically configured virtual hosts, by allowing the IP address and/or the Host: header of the HTTP request to be used as part of the pathname to determine what files to serve. This allows for easy use of a huge number of virtual hosts with similar configurations. =⇒Note If MOD ALIAS or MOD USERDIR are used for translating URIs to filenames, they will override the directives of MOD VHOST ALIAS described below. For example, the following configuration will map /cgi-bin/script.pl to /usr/local/apache2/cgi-bin/script.pl in all cases: ScriptAlias "/cgi-bin/" "/usr/local/apache2/cgi-bin/" VirtualScriptAlias "/never/found/%0/cgi-bin/" Directives • VirtualDocumentRoot • VirtualDocumentRootIP • VirtualScriptAlias • VirtualScriptAliasIP See also • U SE C ANONICAL NAME • Dynamically configured mass virtual hosting (p. 130) Directory Name Interpolation All the directives in this module interpolate a string into a pathname. The interpolated string (henceforth called the "name") may be either the server name (see the U SE C ANONICAL NAME directive for details on how this is determined) or the IP address of the virtual host on the server in dotted-quad format. The interpolation is controlled by specifiers inspired by printf which have a number of formats: %% %p %N.M insert a % insert the port number of the virtual host insert (part of) the name N and M are used to specify substrings of the name. N selects from the dot-separated components of the name, and M selects characters within whatever N has selected. M is optional and defaults to zero if it isn’t present; the dot must be present if and only if M is present. The interpretation is as follows: 10.127. APACHE MODULE MOD VHOST ALIAS 0 1 2 -1 -2 2+ -2+ 1+ and -1+ 983 the whole name the first part the second part the last part the penultimate part the second and all subsequent parts the penultimate and all preceding parts the same as 0 If N or M is greater than the number of parts available a single underscore is interpolated. Examples For simple name-based virtual hosts you might use the following directives in your server configuration file: UseCanonicalName Off VirtualDocumentRoot "/usr/local/apache/vhosts/%0" A request for http://www.example.com/directory/file.html will be satisfied by the file /usr/local/apache/vhosts/www.example.com/directory/file.html. For a very large number of virtual hosts it is a good idea to arrange the files to reduce the size of the vhosts directory. To do this you might use the following in your configuration file: UseCanonicalName Off VirtualDocumentRoot "/usr/local/apache/vhosts/%3+/%2.1/%2.2/%2.3/%2" A request for http://www.domain.example.com/directory/file.html will be satisfied by the file /usr/local/apache/vhosts/example.com/d/o/m/domain/directory/file.html. A more even spread of files can be achieved by hashing from the end of the name, for example: VirtualDocumentRoot "/usr/local/apache/vhosts/%3+/%2.-1/%2.-2/%2.-3/%2" The example request would come from /usr/local/apache/vhosts/example.com/n/i/a/domain/directory/file. Alternatively you might use: VirtualDocumentRoot "/usr/local/apache/vhosts/%3+/%2.1/%2.2/%2.3/%2.4+" The example request would come from /usr/local/apache/vhosts/example.com/d/o/m/ain/directory/file.htm A very common request by users is the ability to point multiple domains to multiple document roots without having to worry about the length or number of parts of the hostname being requested. If the requested hostname is sub.www.domain.example.com instead of simply www.domain.example.com, then using %3+ will result in the document root being /usr/local/apache/vhosts/domain.example.com/... instead of the intended example.com directory. In such cases, it can be beneficial to use the combination %-2.0.%-1.0, which will always yield the domain name and the tld, for example example.com regardless of the number of subdomains appended to the hostname. As such, one can make a configuration that will direct all first, second or third level subdomains to the same directory: VirtualDocumentRoot "/usr/local/apache/vhosts/%-2.0.%-1.0" 984 CHAPTER 10. APACHE MODULES In the example above, both www.example.com as well as www.sub.example.com or example.com will all point to /usr/local/apache/vhosts/example.com. For IP-based virtual hosting you might use the following in your configuration file: UseCanonicalName DNS VirtualDocumentRootIP "/usr/local/apache/vhosts/%1/%2/%3/%4/docs" VirtualScriptAliasIP "/usr/local/apache/vhosts/%1/%2/%3/%4/cgi-bin" A request for http://www.domain.example.com/directory/file.html would be satisfied by the file /usr/local/apache/vhosts/10/20/30/40/docs/directory/file.html if the IP address of www.domain.example.com were 10.20.30.40. A request for http://www.domain.example.com/cgi-bin/script.pl would be satisfied by executing the program /usr/local/apache/vhosts/10/20/30/40/cgi-bin/script.pl. If you want to include the . character in a VirtualDocumentRoot directive, but it clashes with a % directive, you can work around the problem in the following way: VirtualDocumentRoot "/usr/local/apache/vhosts/%2.0.%3.0" A request for http://www.domain.example.com/directory/file.html will be satisfied by the file /usr/local/apache/vhosts/domain.example/directory/file.html. The L OG F ORMAT directives %V and %A are useful in conjunction with this module. VirtualDocumentRoot Directive Description: Syntax: Default: Context: Status: Module: Dynamically configure the location of the document root for a given virtual host VirtualDocumentRoot interpolated-directory|none VirtualDocumentRoot none server config, virtual host Extension mod vhost alias The V IRTUAL D OCUMENT ROOT directive allows you to determine where Apache HTTP Server will find your documents based on the value of the server name. The result of expanding interpolated-directory is used as the root of the document tree in a similar manner to the D OCUMENT ROOT directive’s argument. If interpolated-directory is none then V IRTUAL D OCUMENT ROOT is turned off. This directive cannot be used in the same context as V IRTUAL D OCU MENT ROOT IP. ! Note V IRTUAL D OCUMENT ROOT will override any D OCUMENT ROOT directives you may have put in the same context or child contexts. Putting a V IRTUAL D OCUMENT ROOT in the global server scope will effectively override D OCUMENT ROOT directives in any virtual hosts defined later on, unless you set V IRTUAL D OCUMENT ROOT to None in each virtual host. VirtualDocumentRootIP Directive Description: Syntax: Default: Context: Status: Module: Dynamically configure the location of the document root for a given virtual host VirtualDocumentRootIP interpolated-directory|none VirtualDocumentRootIP none server config, virtual host Extension mod vhost alias 10.127. APACHE MODULE MOD VHOST ALIAS 985 The V IRTUAL D OCUMENT ROOT IP directive is like the V IRTUAL D OCUMENT ROOT directive, except that it uses the IP address of the server end of the connection for directory interpolation instead of the server name. VirtualScriptAlias Directive Description: Syntax: Default: Context: Status: Module: Dynamically configure the location of the CGI directory for a given virtual host VirtualScriptAlias interpolated-directory|none VirtualScriptAlias none server config, virtual host Extension mod vhost alias The V IRTUAL S CRIPTA LIAS directive allows you to determine where Apache httpd will find CGI scripts in a similar manner to V IRTUAL D OCUMENT ROOT does for other documents. It matches requests for URIs starting /cgi-bin/, much like S CRIPTA LIAS /cgi-bin/ would. VirtualScriptAliasIP Directive Description: Syntax: Default: Context: Status: Module: Dynamically configure the location of the CGI directory for a given virtual host VirtualScriptAliasIP interpolated-directory|none VirtualScriptAliasIP none server config, virtual host Extension mod vhost alias The V IRTUAL S CRIPTA LIAS IP directive is like the V IRTUAL S CRIPTA LIAS directive, except that it uses the IP address of the server end of the connection for directory interpolation instead of the server name. 986 CHAPTER 10. APACHE MODULES 10.128 Apache Module mod watchdog Description: Status: ModuleIdentifier: SourceFile: Compatibility: provides infrastructure for other modules to periodically run tasks Base watchdog module mod watchdog.c Available in Apache 2.3 and later Summary MOD WATCHDOG defines programmatic hooks for other modules to periodically run tasks. These modules can register handlers for MOD WATCHDOG hooks. Currently, the following modules in the Apache distribution use this functionality: • MOD HEARTBEAT • MOD HEARTMONITOR ! To allow a module to use MOD WATCHDOG functionality, MOD WATCHDOG itself must be statically linked to the server core or, if a dynamic module, be loaded before the calling module. Directives • WatchdogInterval WatchdogInterval Directive Description: Syntax: Default: Context: Status: Module: Watchdog interval in seconds WatchdogInterval number-of-seconds WatchdogInterval 1 server config Base mod watchdog Sets the interval at which the watchdog step hook runs. Default is to run every second. 10.129. APACHE MODULE MOD XML2ENC 10.129 987 Apache Module mod xml2enc Description: Status: ModuleIdentifier: SourceFile: Compatibility: Enhanced charset/internationalisation support for libxml2-based filter modules Base xml2enc module mod xml2enc.c Version 2.4 and later. Available as a third-party module for 2.2.x versions Summary This module provides enhanced internationalisation support for markup-aware filter modules such as MOD PROXY HTML . It can automatically detect the encoding of input data and ensure they are correctly processed by the libxml2104 parser, including converting to Unicode (UTF-8) where necessary. It can also convert data to an encoding of choice after markup processing, and will ensure the correct charset value is set in the HTTP Content-Type header. Directives • xml2EncAlias • xml2EncDefault • xml2StartParse Usage There are two usage scenarios: with modules programmed to work with mod xml2enc, and with those that are not aware of it: Filter modules enabled for mod xml2enc Modules such as MOD PROXY HTML version 3.1 and up use the xml2enc charset optional function to retrieve the charset argument to pass to the libxml2 parser, and may use the xml2enc filter optional function to postprocess to another encoding. Using mod xml2enc with an enabled module, no configuration is necessary: the other module will configure mod xml2enc for you (though you may still want to customise it using the configuration directives below). Non-enabled modules To use it with a libxml2-based module that isn’t explicitly enabled for mod xml2enc, you will have to configure the filter chain yourself. So to use it with a filter foo provided by a module mod foo to improve the latter’s i18n support with HTML and XML, you could use FilterProvider FilterProvider FilterProvider FilterProvider FilterChain iconv xml2enc Content-Type $text/html iconv xml2enc Content-Type $xml markup foo Content-Type $text/html markup foo Content-Type $xml iconv markup mod foo will now support any character set supported by either (or both) of libxml2 or apr xlate/iconv. Programming API Programmers writing libxml2-based filter modules are encouraged to enable them for mod xml2enc, to provide strong i18n support for your users without reinventing the wheel. The programming API is exposed in mod xml2enc.h, and a usage example is MOD PROXY HTML. 104 http://xmlsoft.org/ 988 CHAPTER 10. APACHE MODULES Detecting an Encoding Unlike MOD CHARSET LITE, mod xml2enc is designed to work with data whose encoding cannot be known in advance and thus configured. It therefore uses ’sniffing’ techniques to detect the encoding of HTTP data as follows: 1. If the HTTP Content-Type header includes a charset parameter, that is used. 2. If the data start with an XML Byte Order Mark (BOM) or an XML encoding declaration, that is used. 3. If an encoding is declared in an HTML element, that is used. 4. If none of the above match, the default value set by XML 2E NC D EFAULT is used. The rules are applied in order. As soon as a match is found, it is used and detection is stopped. Output Encoding libxml2105 always uses UTF-8 (Unicode) internally, and libxml2-based filter modules will output that by default. mod xml2enc can change the output encoding through the API, but there is currently no way to configure that directly. Changing the output encoding should (in theory, at least) never be necessary, and is not recommended due to the extra processing load on the server of an unnecessary conversion. Unsupported Encodings If you are working with encodings that are not supported by any of the conversion methods available on your platform, you can still alias them to a supported encoding using XML 2E NC A LIAS. xml2EncAlias Directive Description: Syntax: Context: Status: Module: Recognise Aliases for encoding values xml2EncAlias charset alias [alias ...] server config Base mod xml2enc This server-wide directive aliases one or more encoding to another encoding. This enables encodings not recognised by libxml2 to be handled internally by libxml2’s encoding support using the translation table for a recognised encoding. This serves two purposes: to support character sets (or names) not recognised either by libxml2 or iconv, and to skip conversion for an encoding where it is known to be unnecessary. xml2EncDefault Directive Description: Syntax: Context: Status: Module: Compatibility: 105 http://xmlsoft.org/ Sets a default encoding to assume when absolutely no information can be automatically detected xml2EncDefault name server config, virtual host, directory, .htaccess Base mod xml2enc Version 2.4.0 and later; available as a third-party module for earlier versions. 10.129. APACHE MODULE MOD XML2ENC 989 If you are processing data with known encoding but no encoding information, you can set this default to help mod xml2enc process the data correctly. For example, to work with the default value of Latin1 (iso-8859-1 specified in HTTP/1.0, use xml2EncDefault iso-8859-1 xml2StartParse Directive Description: Syntax: Context: Status: Module: Advise the parser to skip leading junk. xml2StartParse element [element ...] server config, virtual host, directory, .htaccess Base mod xml2enc Specify that the markup parser should start at the first instance of any of the elements specified. This can be used as a workaround where a broken backend inserts leading junk that messes up the parser (example here106 ). It should never be used for XML, nor well-formed HTML. 106 http://bahumbug.wordpress.com/2006/10/12/mod proxy html-revisited/ 990 CHAPTER 10. APACHE MODULES 10.130 Apache Module mpm common Description: Status: A collection of directives that are implemented by more than one multi-processing module (MPM) MPM Directives • CoreDumpDirectory • EnableExceptionHook • GracefulShutdownTimeout • Listen • ListenBackLog • ListenCoresBucketsRatio • MaxConnectionsPerChild • MaxMemFree • MaxRequestWorkers • MaxSpareThreads • MinSpareThreads • PidFile • ReceiveBufferSize • ScoreBoardFile • SendBufferSize • ServerLimit • StartServers • StartThreads • ThreadLimit • ThreadsPerChild • ThreadStackSize CoreDumpDirectory Directive Description: Syntax: Default: Context: Status: Module: Directory where Apache HTTP Server attempts to switch before dumping core CoreDumpDirectory directory See usage for the default setting server config MPM EVENT , WORKER , PREFORK This controls the directory to which Apache httpd attempts to switch before dumping core. If your operating system is configured to create core files in the working directory of the crashing process, C ORE D UMP D IRECTORY is necessary to change working directory from the default S ERVER ROOT directory, which should not be writable by the user the server runs as. If you want a core dump for debugging, you can use this directive to place it in a different location. This directive has no effect if your operating system is not configured to write core files to the working directory of the crashing processes. 10.130. APACHE MODULE MPM COMMON 991 =⇒Core Dumps on Linux If Apache httpd starts as root and switches to another user, the Linux kernel disables core dumps even if the directory is writable for the process. Apache httpd (2.0.46 and later) reenables core dumps on Linux 2.4 and beyond, but only if you explicitly configure a C ORE D UMP D IRECTORY. =⇒Core Dumps on BSD To enable core-dumping of suid-executables on BSD-systems (such as FreeBSD), set kern.sugid coredump to 1. =⇒Specific signals C D D ORE UMP IRECTORY processing only occurs for a select set of fatal signals: SIGFPE, SIGILL, SIGABORT, SIGSEGV, and SIGBUS. On some operating systems, SIGQUIT also results in a core dump but does not go through C ORE D UMP D IRECTORY or E NABLE E XCEPTION H OOK processing, so the core location is dictated entirely by the operating system. EnableExceptionHook Directive Description: Syntax: Default: Context: Status: Module: Enables a hook that runs exception handlers after a crash EnableExceptionHook On|Off EnableExceptionHook Off server config MPM EVENT , WORKER , PREFORK For safety reasons this directive is only available if the server was configured with the --enable-exception-hook option. It enables a hook that allows external modules to plug in and do something after a child crashed. There are already two modules, mod whatkilledus and mod backtrace that make use of this hook. Please have a look at Jeff Trawick’s EnableExceptionHook site107 for more information about these. GracefulShutdownTimeout Directive Description: Syntax: Default: Context: Status: Module: Specify a timeout after which a gracefully shutdown server will exit. GracefulShutdownTimeout seconds GracefulShutdownTimeout 0 server config MPM EVENT , WORKER , PREFORK The G RACEFUL S HUTDOWN T IMEOUT specifies how many seconds after receiving a "graceful-stop" signal, a server should continue to run, handling the existing connections. Setting this value to zero means that the server will wait indefinitely until all remaining requests have been fully served. 107 http://people.apache.org/˜trawick/exception hook.html 992 CHAPTER 10. APACHE MODULES Listen Directive Description: Syntax: Context: Status: Module: IP addresses and ports that the server listens to Listen [IP-address:]portnumber [protocol] server config MPM EVENT , WORKER , PREFORK , MPM WINNT, MPM NETWARE , MPMT OS 2 The L ISTEN directive instructs Apache httpd to listen to only specific IP addresses or ports; by default it responds to requests on all IP interfaces. L ISTEN is now a required directive. If it is not in the config file, the server will fail to start. This is a change from previous versions of Apache httpd. The L ISTEN directive tells the server to accept incoming requests on the specified port or address-and-port combination. If only a port number is specified, the server listens to the given port on all interfaces. If an IP address is given as well as a port, the server will listen on the given port and interface. Multiple L ISTEN directives may be used to specify a number of addresses and ports to listen to. The server will respond to requests from any of the listed addresses and ports. For example, to make the server accept connections on both port 80 and port 8000, use: Listen 80 Listen 8000 To make the server accept connections on two specified interfaces and port numbers, use Listen 192.170.2.1:80 Listen 192.170.2.5:8000 IPv6 addresses must be surrounded in square brackets, as in the following example: Listen [2001:db8::a00:20ff:fea7:ccea]:80 The optional protocol argument is not required for most configurations. If not specified, https is the default for port 443 and http the default for all other ports. The protocol is used to determine which module should handle a request, and to apply protocol specific optimizations with the ACCEPT F ILTER directive. You only need to set the protocol if you are running on non-standard ports. For example, running an https site on port 8443: Listen 192.170.2.1:8443 https =⇒Error condition Multiple L ISTEN directives for the same ip address and port will result in an Address already in use error message. See also • DNS Issues (p. 121) • Setting which addresses and ports Apache HTTP Server uses (p. 88) • Further discussion of the Address already in use error message, including other causes.108 108 http://wiki.apache.org/httpd/CouldNotBindToAddress 10.130. APACHE MODULE MPM COMMON 993 ListenBackLog Directive Description: Syntax: Default: Context: Status: Module: Maximum length of the queue of pending connections ListenBacklog backlog ListenBacklog 511 server config MPM EVENT , WORKER , PREFORK , MPM WINNT, MPM NETWARE , MPMT OS 2 The maximum length of the queue of pending connections. Generally no tuning is needed or desired, however on some systems it is desirable to increase this when under a TCP SYN flood attack. See the backlog parameter to the listen(2) system call. This will often be limited to a smaller number by the operating system. This varies from OS to OS. Also note that many OSes do not use exactly what is specified as the backlog, but use a number based on (but normally larger than) what is set. ListenCoresBucketsRatio Directive Description: Syntax: Default: Context: Status: Module: Compatibility: Ratio between the number of CPU cores (online) and the number of listeners’ buckets ListenCoresBucketsRatio ratio ListenCoresBucketsRatio 0 (disabled) server config MPM EVENT , WORKER , PREFORK Available in Apache HTTP Server 2.4.17, with a kernel supporting the socket option SO REUSEPORT and distributing new connections evenly accross listening processes’ (or threads’) sockets using it (eg. Linux 3.9 and later, but not the current implementations of SO REUSEPORT in *BSDs. A ratio between the number of (online) CPU cores and the number of listeners’ buckets can be used to make Apache HTTP Server create num cpu cores / ratio listening buckets, each containing its own L ISTEN-ing socket(s) on the same port(s), and then make each child handle a single bucket (with round-robin distribution of the buckets at children creation time). =⇒Meaning of "online" CPU core On Linux (and also BSD) a CPU core can be turned on/off if Hotplug is configured, therefore a L ISTEN C ORES B UCKETS R ATIO needs to take this parameter into account while calculating the number of buckets to create. a https://www.kernel.org/doc/Documentation/cpu-hotplug.txt L ISTEN C ORES B UCKETS R ATIO can improve the scalability when accepting new connections is/becomes the bottleneck. On systems with a large number of CPU cores, enabling this feature has been tested to show significant performances improvement and shorter responses time. There must be at least twice the number of CPU cores than the configured ratio for this to be active. The recommended ratio is 8, hence at least 16 cores should be available at runtime when this value is used. The right ratio to obtain maximum performance needs to be calculated for each target system, testing multiple values and observing the variations in your key performance metrics. 994 CHAPTER 10. APACHE MODULES MaxConnectionsPerChild Directive Description: Syntax: Default: Context: Status: Module: Compatibility: Limit on the number of connections that an individual child server will handle during its life MaxConnectionsPerChild number MaxConnectionsPerChild 0 server config MPM EVENT , WORKER , PREFORK , MPM WINNT, MPM NETWARE , MPMT OS 2 Available Apache HTTP Server 2.3.9 and later. The old name MaxRequestsPerChild is still supported. The M AX C ONNECTIONS P ER C HILD directive sets the limit on the number of connections that an individual child server process will handle. After M AX C ONNECTIONS P ER C HILD connections, the child process will die. If M AX C ONNECTIONS P ER C HILD is 0, then the process will never expire. Setting M AX C ONNECTIONS P ER C HILD to a non-zero value limits the amount of memory that process can consume by (accidental) memory leakage. MaxMemFree Directive Description: Syntax: Default: Context: Status: Module: Maximum amount of memory that the main allocator is allowed to hold without calling free() MaxMemFree KBytes MaxMemFree 2048 server config MPM EVENT , WORKER , PREFORK , MPM WINNT, MPM NETWARE The M AX M EM F REE directive sets the maximum number of free Kbytes that every allocator is allowed to hold without calling free(). In threaded MPMs, every thread has its own allocator. When set to zero, the threshold will be set to unlimited. MaxRequestWorkers Directive Description: Syntax: Default: Context: Status: Module: Maximum number of connections that will be processed simultaneously MaxRequestWorkers number See usage for details server config MPM EVENT , WORKER , PREFORK The M AX R EQUEST W ORKERS directive sets the limit on the number of simultaneous requests that will be served. Any connection attempts over the M AX R EQUEST W ORKERS limit will normally be queued, up to a number based on the L ISTEN BACKLOG directive. Once a child process is freed at the end of a different request, the connection will then be serviced. For non-threaded servers (i.e., PREFORK), M AX R EQUEST W ORKERS translates into the maximum number of child processes that will be launched to serve requests. The default value is 256; to increase it, you must also raise S ERVER L IMIT. For threaded and hybrid servers (e.g. EVENT or WORKER) M AX R EQUEST W ORKERS restricts the total number of threads that will be available to serve clients. For hybrid MPMs the default value is 16 (S ERVER L IMIT) multiplied by the value of 25 (T HREADS P ER C HILD). Therefore, to increase M AX R EQUEST W ORKERS to a value that requires more than 16 processes, you must also raise S ERVER L IMIT. M AX R EQUEST W ORKERS was called M AX C LIENTS before version 2.3.13. The old name is still supported. 10.130. APACHE MODULE MPM COMMON 995 MaxSpareThreads Directive Description: Syntax: Default: Context: Status: Module: Maximum number of idle threads MaxSpareThreads number See usage for details server config MPM EVENT , WORKER , MPM NETWARE , MPMT OS 2 Maximum number of idle threads. Different MPMs deal with this directive differently. For WORKER and EVENT, the default is MaxSpareThreads 250. These MPMs deal with idle threads on a serverwide basis. If there are too many idle threads in the server then child processes are killed until the number of idle threads is less than this number. For MPM NETWARE the default is MaxSpareThreads 100. Since this MPM runs a single-process, the spare thread count is also server-wide. MPMT OS 2 works similar to MPM NETWARE. For MPMT OS 2 the default value is 10. =⇒Restrictions The range of the M AX S PARE T HREADS value is restricted. Apache httpd will correct the given value automatically according to the following rules: • MPM NETWARE wants the value to be greater than M IN S PARE T HREADS. • For WORKER and EVENT, the value must be greater or equal to the sum of M IN SPARE T HREADS and T HREADS P ER C HILD . See also • M IN S PARE T HREADS • S TART S ERVERS • M AX S PARE S ERVERS MinSpareThreads Directive Description: Syntax: Default: Context: Status: Module: Minimum number of idle threads available to handle request spikes MinSpareThreads number See usage for details server config MPM EVENT , WORKER , MPM NETWARE , MPMT OS 2 Minimum number of idle threads to handle request spikes. Different MPMs deal with this directive differently. WORKER and EVENT use a default of MinSpareThreads 75 and deal with idle threads on a server-wide basis. If there aren’t enough idle threads in the server then child processes are created until the number of idle threads is greater than number. Please also note that additional processes/threads might be created if L ISTEN C ORES B UCKETS R ATIO is enabled. MPM NETWARE uses a default of MinSpareThreads 10 and, since it is a single-process MPM, tracks this on a server-wide bases. MPMT OS 2 works similar to MPM NETWARE. For MPMT OS 2 the default value is 5. See also • M AX S PARE T HREADS 996 CHAPTER 10. APACHE MODULES • S TART S ERVERS • M IN S PARE S ERVERS PidFile Directive Description: Syntax: Default: Context: Status: Module: File where the server records the process ID of the daemon PidFile filename PidFile httpd.pid server config MPM EVENT , WORKER , PREFORK , MPM WINNT, MPMT OS 2 The P ID F ILE directive sets the file to which the server records the process id of the daemon. If the filename is not absolute then it is assumed to be relative to the D EFAULT RUNTIME D IR. Example PidFile /var/run/apache.pid It is often useful to be able to send the server a signal, so that it closes and then re-opens its E RROR L OG and T RANS FER L OG , and re-reads its configuration files. This is done by sending a SIGHUP (kill -1) signal to the process id listed in the P ID F ILE. The P ID F ILE is subject to the same warnings about log file placement and security (p. 364) . =⇒Note As of Apache HTTP Server 2, we recommended that you only use the apachectl script, or the init script that your OS provides, for (re-)starting or stopping the server. ReceiveBufferSize Directive Description: Syntax: Default: Context: Status: Module: TCP receive buffer size ReceiveBufferSize bytes ReceiveBufferSize 0 server config MPM EVENT , WORKER , PREFORK , MPM WINNT, MPM NETWARE , MPMT OS 2 The server will set the TCP receive buffer size to the number of bytes specified. If set to the value of 0, the server will use the OS default. ScoreBoardFile Directive Description: Syntax: Default: Context: Status: Module: Location of the file used to store coordination data for the child processes ScoreBoardFile file-path ScoreBoardFile apache runtime status server config MPM EVENT , WORKER , PREFORK , MPM WINNT Apache HTTP Server uses a scoreboard to communicate between its parent and child processes. Some architectures require a file to facilitate this communication. If the file is left unspecified, Apache httpd first attempts to create the scoreboard entirely in memory (using anonymous shared memory) and, failing that, will attempt to create the file on 10.130. APACHE MODULE MPM COMMON 997 disk (using file-based shared memory). Specifying this directive causes Apache httpd to always create the file on the disk. If file-path is not an absolute path, the location specified will be relative to the value of D EFAULT RUNTIME D IR. Example ScoreBoardFile /var/run/apache_runtime_status File-based shared memory is useful for third-party applications that require direct access to the scoreboard. If you use a S CORE B OARD F ILE then you may see improved speed by placing it on a RAM disk. But be careful that you heed the same warnings about log file placement and security (p. 364) . See also • Stopping and Restarting Apache HTTP Server (p. 29) SendBufferSize Directive Description: Syntax: Default: Context: Status: Module: TCP buffer size SendBufferSize bytes SendBufferSize 0 server config MPM EVENT , WORKER , PREFORK , MPM WINNT, MPM NETWARE , MPMT OS 2 Sets the server’s TCP send buffer size to the number of bytes specified. It is often useful to set this past the OS’s standard default value on high speed, high latency connections (i.e., 100ms or so, such as transcontinental fast pipes). If set to the value of 0, the server will use the default value provided by your OS. Further configuration of your operating system may be required to elicit better performance on high speed, high latency connections. =⇒OnS some operating systems, changes in TCP behavior resulting from a larger S B may not be seen unless E S is set to OFF. This interaction applies only to END UFFER IZE NABLE ENDFILE static files. ServerLimit Directive Description: Syntax: Default: Context: Status: Module: Upper limit on configurable number of processes ServerLimit number See usage for details server config MPM EVENT , WORKER , PREFORK For the PREFORK MPM, this directive sets the maximum configured value for M AX R EQUEST W ORKERS for the lifetime of the Apache httpd process. For the WORKER and EVENT MPMs, this directive in combination with T HREAD L IMIT sets the maximum configured value for M AX R EQUEST W ORKERS for the lifetime of the Apache httpd process. Any attempts to change this directive during a restart will be ignored, but M AX R EQUEST W ORKERS can be modified during a restart. Special care must be taken when using this directive. If S ERVER L IMIT is set to a value much higher than necessary, extra, unused shared memory will be allocated. If both S ERVER L IMIT and M AX R EQUEST W ORKERS are set to values higher than the system can handle, Apache httpd may not start or the system may become unstable. 998 CHAPTER 10. APACHE MODULES With the PREFORK MPM, use this directive only if you need to set M AX R EQUEST W ORKERS higher than 256 (default). Do not set the value of this directive any higher than what you might want to set M AX R EQUEST W ORKERS to. With WORKER and EVENT, use this directive only if your M AX R EQUEST W ORKERS and T HREADS P ER C HILD settings require more than 16 server processes (default). Do not set the value of this directive any higher than the number of server processes required by what you may want for M AX R EQUEST W ORKERS and T HREADS P ER C HILD. =⇒Note There is a hard limit of ServerLimit 20000 compiled into the server (for the PREFORK MPM 200000). This is intended to avoid nasty effects caused by typos. To increase it even further past this limit, you will need to modify the value of MAX SERVER LIMIT in the mpm source file and rebuild the server. See also • Stopping and Restarting Apache HTTP Server (p. 29) StartServers Directive Description: Syntax: Default: Context: Status: Module: Number of child server processes created at startup StartServers number See usage for details server config MPM EVENT , WORKER , PREFORK , MPMT OS 2 The S TART S ERVERS directive sets the number of child server processes created on startup. As the number of processes is dynamically controlled depending on the load, (see M IN S PARE T HREADS, M AX S PARE T HREADS, M IN SPARE S ERVERS , M AX S PARE S ERVERS ) there is usually little reason to adjust this parameter. The default value differs from MPM to MPM. WORKER and EVENT default to StartServers 3; PREFORK defaults to 5; MPMT OS 2 defaults to 2. StartThreads Directive Description: Syntax: Default: Context: Status: Module: Number of threads created on startup StartThreads number See usage for details server config MPM MPM NETWARE Number of threads created on startup. As the number of threads is dynamically controlled depending on the load, (see M IN S PARE T HREADS, M AX S PARE T HREADS, M IN S PARE S ERVERS, M AX S PARE S ERVERS) there is usually little reason to adjust this parameter. For MPM NETWARE the default is StartThreads 50 and, since there is only a single process, this is the total number of threads created at startup to serve requests. 10.130. APACHE MODULE MPM COMMON 999 ThreadLimit Directive Description: Syntax: Default: Context: Status: Module: Sets the upper limit on the configurable number of threads per child process ThreadLimit number See usage for details server config MPM EVENT , WORKER , MPM WINNT This directive sets the maximum configured value for T HREADS P ER C HILD for the lifetime of the Apache httpd process. Any attempts to change this directive during a restart will be ignored, but T HREADS P ER C HILD can be modified during a restart up to the value of this directive. Special care must be taken when using this directive. If T HREAD L IMIT is set to a value much higher than T HREADS P ER C HILD, extra unused shared memory will be allocated. If both T HREAD L IMIT and T HREADS P ER C HILD are set to values higher than the system can handle, Apache httpd may not start or the system may become unstable. Do not set the value of this directive any higher than your greatest predicted setting of T HREADS P ER C HILD for the current run of Apache httpd. The default value for T HREAD L IMIT is 1920 when used with MPM WINNT and 64 when used with the others. =⇒Note There is a hard limit of ThreadLimit 20000 (or ThreadLimit 100000 with EVENT , ThreadLimit 15000 with MPM WINNT) compiled into the server. This is intended to avoid nasty effects caused by typos. To increase it even further past this limit, you will need to modify the value of MAX THREAD LIMIT in the mpm source file and rebuild the server. ThreadsPerChild Directive Description: Syntax: Default: Context: Status: Module: Number of threads created by each child process ThreadsPerChild number See usage for details server config MPM EVENT , WORKER , MPM WINNT This directive sets the number of threads created by each child process. The child creates these threads at startup and never creates more. If using an MPM like MPM WINNT, where there is only one child process, this number should be high enough to handle the entire load of the server. If using an MPM like WORKER, where there are multiple child processes, the total number of threads should be high enough to handle the common load on the server. The default value for T HREADS P ER C HILD is 64 when used with MPM WINNT and 25 when used with the others. ThreadStackSize Directive Description: Syntax: Default: Context: Status: Module: The size in bytes of the stack used by threads handling client connections ThreadStackSize size 65536 on NetWare; varies on other operating systems server config MPM EVENT , WORKER , MPM WINNT, MPM NETWARE , MPMT OS 2 The T HREAD S TACK S IZE directive sets the size of the stack (for autodata) of threads which handle client connections and call modules to help process those connections. In most cases the operating system default for stack size is reasonable, but there are some conditions where it may need to be adjusted: 1000 CHAPTER 10. APACHE MODULES • On platforms with a relatively small default thread stack size (e.g., HP-UX), Apache httpd may crash when using some third-party modules which use a relatively large amount of autodata storage. Those same modules may have worked fine on other platforms where the default thread stack size is larger. This type of crash is resolved by setting T HREAD S TACK S IZE to a value higher than the operating system default. This type of adjustment is necessary only if the provider of the third-party module specifies that it is required, or if diagnosis of an Apache httpd crash indicates that the thread stack size was too small. • On platforms where the default thread stack size is significantly larger than necessary for the web server configuration, a higher number of threads per child process will be achievable if T HREAD S TACK S IZE is set to a value lower than the operating system default. This type of adjustment should only be made in a test environment which allows the full set of web server processing can be exercised, as there may be infrequent requests which require more stack to process. The minimum required stack size strongly depends on the modules used, but any change in the web server configuration can invalidate the current T HREAD S TACK S IZE setting. • On Linux, this directive can only be used to increase the default stack size, as the underlying system call uses the value as a minimum stack size. The (often large) soft limit for ulimit -s (8MB if unlimited) is used as the default stack size. =⇒child It is recommended to not reduce T S S unless a high number of threads per process is needed. On some platforms (including Linux), a setting of 128000 is already HREAD TACK IZE too low and causes crashes with some common modules. 10.131. APACHE MODULE EVENT 10.131 1001 Apache Module event Description: Status: ModuleIdentifier: SourceFile: A variant of the WORKER MPM with the goal of consuming threads only for connections with active processing MPM mpm event module event.c Summary The EVENT Multi-Processing Module (MPM) is, as its name implies, an asynchronous, event-based implementation designed to allow more requests to be served simultaneously by passing off some processing work to the listeners threads, freeing up the worker threads to serve new requests. To use the EVENT MPM, add --with-mpm=event to the configure script’s arguments when building the httpd. Directives • AsyncRequestWorkerFactor • CoreDumpDirectory (p. 990) • EnableExceptionHook (p. 991) • Group (p. 972) • Listen (p. 992) • ListenBacklog (p. 993) • MaxConnectionsPerChild (p. 994) • MaxMemFree (p. 994) • MaxRequestWorkers (p. 994) • MaxSpareThreads (p. 995) • MinSpareThreads (p. 995) • PidFile (p. 996) • ScoreBoardFile (p. 996) • SendBufferSize (p. 997) • ServerLimit (p. 997) • StartServers (p. 998) • ThreadLimit (p. 999) • ThreadsPerChild (p. 999) • ThreadStackSize (p. 999) • User (p. 973) See also • The worker MPM (p. 1014) 1002 CHAPTER 10. APACHE MODULES Relationship with the Worker MPM EVENT is based on the WORKER MPM, which implements a hybrid multi-process multi-threaded server. A single control process (the parent) is responsible for launching child processes. Each child process creates a fixed number of server threads as specified in the T HREADS P ER C HILD directive, as well as a listener thread which listens for connections and passes them to a worker thread for processing when they arrive. Run-time configuration directives are identical to those provided by WORKER, with the only addition of the A SYN C R EQUEST W ORKER FACTOR . How it Works This original goal of this MPM was to fix the ’keep alive problem’ in HTTP. After a client completes the first request, it can keep the connection open, sending further requests using the same socket and saving significant overhead in creating TCP connections. However, Apache HTTP Server traditionally keeps an entire child process/thread waiting for data from the client, which brings its own disadvantages. To solve this problem, this MPM uses a dedicated listener thread for each process along with a pool of worker threads, sharing queues specific for those requests in keep-alive mode (or, more simply, "readable"), those in write- completion mode, and those in the process of shutting down ("closing"). An event loop, triggered on the status of the socket’s availability, adjusts these queues and pushes work to the worker pool. This new architecture, leveraging non-blocking sockets and modern kernel features exposed by APR (like Linux’s epoll), no longer requires the mpm-accept M UTEX configured to avoid the thundering herd problem. The total amount of connections that a single process/threads block can handle is regulated by the A SYNC R EQUESTW ORKER FACTOR directive. Async connections Async connections would need a fixed dedicated worker thread with the previous MPMs but not with event. The status page of MOD STATUS shows new columns under the Async connections section: Writing While sending the response to the client, it might happen that the TCP write buffer fills up because the connection is too slow. Usually in this case a write() to the socket returns EWOULDBLOCK or EAGAIN, to become writable again after an idle time. The worker holding the socket might be able to offload the waiting task to the listener thread, that in turn will re-assign it to the first idle worker thread available once an event will be raised for the socket (for example, "the socket is now writable"). Please check the Limitations section for more information. Keep-alive Keep Alive handling is the most basic improvement from the worker MPM. Once a worker thread finishes to flush the response to the client, it can offload the socket handling to the listener thread, that in turns will wait for any event from the OS, like "the socket is readable". If any new request comes from the client, then the listener will forward it to the first worker thread available. Conversely, if the K EEPA LIVE T IMEOUT occurs then the socket will be closed by the listener. In this way the worker threads are not responsible for idle sockets and they can be re-used to serve other requests. Closing Sometimes the MPM needs to perform a lingering close, namely sending back an early error to the client while it is still transmitting data to httpd. Sending the response and then closing the connection immediately is not the correct thing to do since the client (still trying to send the rest of the request) would get a connection reset and could not read the httpd’s response. So in such cases, httpd tries to read the rest of the request to allow the client to consume the response. The lingering close is time bounded but it can take relatively long time, so a worker thread can offload this work to the listener. These improvements are valid for both HTTP/HTTPS connections. 10.131. APACHE MODULE EVENT 1003 Limitations The improved connection handling may not work for certain connection filters that have declared themselves as incompatible with event. In these cases, this MPM will fall back to the behaviour of the WORKER MPM and reserve one worker thread per connection. All modules shipped with the server are compatible with the event MPM. A similar restriction is currently present for requests involving an output filter that needs to read and/or modify the whole response body. If the connection to the client blocks while the filter is processing the data, and the amount of data produced by the filter is too big to be buffered in memory, the thread used for the request is not freed while httpd waits until the pending data is sent to the client. To illustrate this point we can think about the following two situations: serving a static asset (like a CSS file) versus serving content retrieved from FCGI/CGI or a proxied server. The former is predictable, namely the event MPM has full visibility on the end of the content and it can use events: the worker thread serving the response content can flush the first bytes until EWOULDBLOCK or EAGAIN is returned, delegating the rest to the listener. This one in turn waits for an event on the socket, and delegates the work to flush the rest of the content to the first idle worker thread. Meanwhile in the latter example (FCGI/CGI/proxied content) the MPM can’t predict the end of the response and a worker thread has to finish its work before returning the control to the listener. The only alternative is to buffer the response in memory, but it wouldn’t be the safest option for the sake of the server’s stability and memory footprint. Background material The event model was made possible by the introduction of new APIs into the supported operating systems: • epoll (Linux) • kqueue (BSD) • event ports (Solaris) Before these new APIs where made available, the traditional select and poll APIs had to be used. Those APIs get slow if used to handle many connections or if the set of connections rate of change is high. The new APIs allow to monitor much more connections and they perform way better when the set of connections to monitor changes frequently. So these APIs made it possible to write the event MPM, that scales much better with the typical HTTP pattern of many idle connections. The MPM assumes that the underlying apr pollset implementation is reasonably threadsafe. This enables the MPM to avoid excessive high level locking, or having to wake up the listener thread in order to send it a keep-alive socket. This is currently only compatible with KQueue and EPoll. Requirements This MPM depends on APR’s atomic compare-and-swap operations for thread synchronization. If you are compiling for an x86 target and you don’t need to support 386s, or you are compiling for a SPARC and you don’t need to run on pre-UltraSPARC chips, add --enable-nonportable-atomics=yes to the configure script’s arguments. This will cause APR to implement atomic operations using efficient opcodes not available in older CPUs. This MPM does not perform well on older platforms which lack good threading, but the requirement for EPoll or KQueue makes this moot. • To use this MPM on FreeBSD, FreeBSD 5.3 or higher is recommended. However, it is possible to run this MPM on FreeBSD 5.2.1, if you use libkse (see man libmap.conf). • For NetBSD, at least version 2.0 is recommended. • For Linux, a 2.6 kernel is recommended. It is also necessary to ensure that your version of glibc has been compiled with support for EPoll. 1004 CHAPTER 10. APACHE MODULES AsyncRequestWorkerFactor Directive Description: Syntax: Default: Context: Status: Module: Compatibility: Limit concurrent connections per process AsyncRequestWorkerFactor factor 2 server config MPM event Available in version 2.3.13 and later The event MPM handles some connections in an asynchronous way, where request worker threads are only allocated for short periods of time as needed, and other connections with one request worker thread reserved per connection. This can lead to situations where all workers are tied up and no worker thread is available to handle new work on established async connections. To mitigate this problem, the event MPM does two things: • it limits the number of connections accepted per process, depending on the number of idle request workers; • if all workers are busy, it will close connections in keep-alive state even if the keep-alive timeout has not expired. This allows the respective clients to reconnect to a different process which may still have worker threads available. This directive can be used to fine-tune the per-process connection limit. A process will only accept new connections if the current number of connections (not counting connections in the "closing" state) is lower than: T HREADS P ER C HILD + (A SYNC R EQUEST W ORKER FACTOR * number of idle workers) An estimation of the maximum concurrent connections across all the processes given an average value of idle worker threads can be calculated with: (T HREADS P ER C HILD + (A SYNC R EQUEST W ORKER FACTOR * number of idle workers)) * S ERVER L IMIT =⇒Example ThreadsPerChild = 10 ServerLimit = 4 AsyncRequestWorkerFactor = 2 MaxRequestWorkers = 40 idle_workers = 4 (average for all the processes to keep it simple) max_connections = (ThreadsPerChild + (AsyncRequestWorkerFactor * idle_workers)) * Se = (10 + (2 * 4)) * 4 = 72 When all the worker threads are idle, then absolute maximum numbers of concurrent connections can be calculared in a simpler way: (A SYNC R EQUEST W ORKER FACTOR + 1) * M AX R EQUEST W ORKERS 10.131. APACHE MODULE EVENT 1005 =⇒Example ThreadsPerChild = 10 ServerLimit = 4 MaxRequestWorkers = 40 AsyncRequestWorkerFactor = 2 If all the processes have all threads idle then: idle_workers = 10 We can calculate the absolute maximum numbers of concurrent connections in two ways: max_connections = (ThreadsPerChild + (AsyncRequestWorkerFactor * idle_workers)) * Se = (10 + (2 * 10)) * 4 = 120 max_connections = (AsyncRequestWorkerFactor + 1) * MaxRequestWorkers = (2 + 1) * 40 = 120 Tuning A SYNC R EQUEST W ORKER FACTOR requires knowledge about the traffic handled by httpd in each specific use case, so changing the default value requires extensive testing and data gathering from MOD STATUS. M AX R EQUEST W ORKERS was called M AX C LIENTS prior to version 2.3.13. The above value shows that the old name did not accurately describe its meaning for the event MPM. A SYNC R EQUEST W ORKER FACTOR can take non-integer arguments, e.g "1.5". 1006 10.132 CHAPTER 10. APACHE MODULES Apache Module mpm netware Description: Status: ModuleIdentifier: SourceFile: Multi-Processing Module implementing an exclusively threaded web server optimized for Novell NetWare MPM mpm netware module mpm netware.c Summary This Multi-Processing Module (MPM) implements an exclusively threaded web server that has been optimized for Novell NetWare. The main thread is responsible for launching child worker threads which listen for connections and serve them when they arrive. Apache HTTP Server always tries to maintain several spare or idle worker threads, which stand ready to serve incoming requests. In this way, clients do not need to wait for a new child threads to be spawned before their requests can be served. The S TART T HREADS, M IN S PARE T HREADS, M AX S PARE T HREADS, and M AX T HREADS regulate how the main thread creates worker threads to serve requests. In general, Apache httpd is very self-regulating, so most sites do not need to adjust these directives from their default values. Sites with limited memory may need to decrease M AX T HREADS to keep the server from thrashing (spawning and terminating idle threads). More information about tuning process creation is provided in the performance hints (p. 339) documentation. M AX C ONNECTIONS P ER C HILD controls how frequently the server recycles processes by killing old ones and launching new ones. On the NetWare OS it is highly recommended that this directive remain set to 0. This allows worker threads to continue servicing requests indefinitely. Directives • Listen (p. 992) • ListenBacklog (p. 993) • MaxConnectionsPerChild (p. 994) • MaxMemFree (p. 994) • MaxSpareThreads (p. 995) • MaxThreads • MinSpareThreads (p. 995) • ReceiveBufferSize (p. 996) • SendBufferSize (p. 997) • StartThreads (p. 998) • ThreadStackSize (p. 999) See also • Setting which addresses and ports Apache httpd uses (p. 88) 10.132. APACHE MODULE MPM NETWARE 1007 MaxThreads Directive Description: Syntax: Default: Context: Status: Module: Set the maximum number of worker threads MaxThreads number MaxThreads 2048 server config MPM mpm netware The M AX T HREADS directive sets the desired maximum number worker threads allowable. The default value is also the compiled in hard limit. Therefore it can only be lowered, for example: MaxThreads 512 1008 10.133 CHAPTER 10. APACHE MODULES Apache Module mpmt os2 Description: Status: ModuleIdentifier: SourceFile: Hybrid multi-process, multi-threaded MPM for OS/2 MPM mpm mpmt os2 module mpmt os2.c Summary The Server consists of a main, parent process and a small, static number of child processes. The parent process’ job is to manage the child processes. This involves spawning children as required to ensure there are always S TART S ERVERS processes accepting connections. Each child process consists of a pool of worker threads and a main thread that accepts connections and passes them to the workers via a work queue. The worker thread pool is dynamic, managed by a maintenance thread so that the number of idle threads is kept between M IN S PARE T HREADS and M AX S PARE T HREADS. Directives • Group (p. 972) • Listen (p. 992) • ListenBacklog (p. 993) • MaxConnectionsPerChild (p. 994) • MaxSpareThreads (p. 995) • MinSpareThreads (p. 995) • PidFile (p. 996) • ReceiveBufferSize (p. 996) • SendBufferSize (p. 997) • StartServers (p. 998) • User (p. 973) See also • Setting which addresses and ports Apache uses (p. 88) 10.134. APACHE MODULE PREFORK 10.134 1009 Apache Module prefork Description: Status: ModuleIdentifier: SourceFile: Implements a non-threaded, pre-forking web server MPM mpm prefork module prefork.c Summary This Multi-Processing Module (MPM) implements a non-threaded, pre-forking web server. Each server process may answer incoming requests, and a parent process manages the size of the server pool. It is appropriate for sites that need to avoid threading for compatibility with non-thread-safe libraries. It is also the best MPM for isolating each request, so that a problem with a single request will not affect any other. This MPM is very self-regulating, so it is rarely necessary to adjust its configuration directives. Most important is that M AX R EQUEST W ORKERS be big enough to handle as many simultaneous requests as you expect to receive, but small enough to assure that there is enough physical RAM for all processes. Directives • CoreDumpDirectory (p. 990) • EnableExceptionHook (p. 991) • Group (p. 972) • Listen (p. 992) • ListenBacklog (p. 993) • MaxConnectionsPerChild (p. 994) • MaxMemFree (p. 994) • MaxRequestWorkers (p. 994) • MaxSpareServers • MinSpareServers • PidFile (p. 996) • ReceiveBufferSize (p. 996) • ScoreBoardFile (p. 996) • SendBufferSize (p. 997) • ServerLimit (p. 997) • StartServers (p. 998) • User (p. 973) See also • Setting which addresses and ports Apache HTTP Server uses (p. 88) How it Works A single control process is responsible for launching child processes which listen for connections and serve them when they arrive. Apache httpd always tries to maintain several spare or idle server processes, which stand ready to serve 1010 CHAPTER 10. APACHE MODULES incoming requests. In this way, clients do not need to wait for a new child processes to be forked before their requests can be served. The S TART S ERVERS, M IN S PARE S ERVERS, M AX S PARE S ERVERS, and M AX R EQUEST W ORKERS regulate how the parent process creates children to serve requests. In general, Apache httpd is very self-regulating, so most sites do not need to adjust these directives from their default values. Sites which need to serve more than 256 simultaneous requests may need to increase M AX R EQUEST W ORKERS, while sites with limited memory may need to decrease M AX R EQUEST W ORKERS to keep the server from thrashing (swapping memory to disk and back). More information about tuning process creation is provided in the performance hints (p. 339) documentation. While the parent process is usually started as root under Unix in order to bind to port 80, the child processes are launched by Apache httpd as a less-privileged user. The U SER and G ROUP directives are used to set the privileges of the Apache httpd child processes. The child processes must be able to read all the content that will be served, but should have as few privileges beyond that as possible. M AX C ONNECTIONS P ER C HILD controls how frequently the server recycles processes by killing old ones and launching new ones. This MPM uses the mpm-accept mutex to serialize access to incoming connections when subject to the thundering herd problem (generally, when there are multiple listening sockets). The implementation aspects of this mutex can be configured with the M UTEX directive. The performance hints (p. 339) documentation has additional information about this mutex. MaxSpareServers Directive Description: Syntax: Default: Context: Status: Module: Maximum number of idle child server processes MaxSpareServers number MaxSpareServers 10 server config MPM prefork The M AX S PARE S ERVERS directive sets the desired maximum number of idle child server processes. An idle process is one which is not handling a request. If there are more than M AX S PARE S ERVERS idle, then the parent process will kill off the excess processes. Tuning of this parameter should only be necessary on very busy sites. Setting this parameter to a large number is almost always a bad idea. If you are trying to set the value equal to or lower than M IN S PARE S ERVERS, Apache HTTP Server will automatically adjust it to M IN S PARE S ERVERS + 1. See also • M IN S PARE S ERVERS • S TART S ERVERS • M AX S PARE T HREADS MinSpareServers Directive Description: Syntax: Default: Context: Status: Module: Minimum number of idle child server processes MinSpareServers number MinSpareServers 5 server config MPM prefork 10.134. APACHE MODULE PREFORK 1011 The M IN S PARE S ERVERS directive sets the desired minimum number of idle child server processes. An idle process is one which is not handling a request. If there are fewer than M IN S PARE S ERVERS idle, then the parent process creates new children: It will spawn one, wait a second, then spawn two, wait a second, then spawn four, and it will continue exponentially until it is spawning 32 children per second. It will stop whenever it satisfies the M IN S PARE S ERVERS setting. Tuning of this parameter should only be necessary on very busy sites. Setting this parameter to a large number is almost always a bad idea. See also • M AX S PARE S ERVERS • S TART S ERVERS • M IN S PARE T HREADS 1012 CHAPTER 10. APACHE MODULES 10.135 Apache Module mpm winnt Description: Status: ModuleIdentifier: SourceFile: Multi-Processing Module optimized for Windows NT. MPM mpm winnt module mpm winnt.c Summary This Multi-Processing Module (MPM) is the default for the Windows NT operating systems. It uses a single control process which launches a single child process which in turn creates threads to handle requests Capacity is configured using the T HREADS P ER C HILD directive, which sets the maximum number of concurrent client connections. By default, this MPM uses advanced Windows APIs for accepting new client connections. In some configurations, third-party products may interfere with this implementation, with the following messages written to the web server log: Child: Encountered too many AcceptEx faults accepting client connections. winnt mpm: falling back to ’AcceptFilter none’. The MPM falls back to a safer implementation, but some client requests were not processed correctly. In order to avoid this error, use ACCEPT F ILTER with accept filter none. AcceptFilter http none AcceptFilter https none In Apache httpd 2.0 and 2.2, W IN 32D ISABLE ACCEPT E X was used for this purpose. The WinNT MPM differs from the Unix MPMs such as worker and event in several areas: • When a child process is exiting due to shutdown, restart, or M AX C ONNECTIONS P ER C HILD, active requests in the exiting process have T IME O UT seconds to finish before processing is aborted. Alternate types of restart and shutdown are not implemented. • New child processes read the configuration files instead of inheriting the configuration from the parent. The behavior will be the same as on Unix if the child process is created at startup or restart, but if a child process is created because the prior one crashed or reached M AX C ONNECTIONS P ER C HILD, any pending changes to the configuration will become active in the child at that point, and the parent and child will be using a different configuration. If planned configuration changes have been partially implemented and the current configuration cannot be parsed, the replacement child process cannot start up and the server will halt. Because of this behavior, configuration files should not be changed until the time of a server restart. • The monitor and fatal exception hooks are not currently implemented. • ACCEPT F ILTER is implemented in the MPM and has a different type of control over handling of new connections. (Refer to the ACCEPT F ILTER documentation for details.) Directives • AcceptFilter (p. 382) • CoreDumpDirectory (p. 990) 10.135. APACHE MODULE MPM WINNT • Listen (p. 992) • ListenBacklog (p. 993) • MaxConnectionsPerChild (p. 994) • MaxMemFree (p. 994) • PidFile (p. 996) • ReceiveBufferSize (p. 996) • ScoreBoardFile (p. 996) • SendBufferSize (p. 997) • ThreadLimit (p. 999) • ThreadsPerChild (p. 999) • ThreadStackSize (p. 999) See also • Using Apache HTTP Server on Microsoft Windows (p. 267) 1013 1014 10.136 CHAPTER 10. APACHE MODULES Apache Module worker Description: Status: ModuleIdentifier: SourceFile: Multi-Processing Module implementing a hybrid multi-threaded multi-process web server MPM mpm worker module worker.c Summary This Multi-Processing Module (MPM) implements a hybrid multi-process multi-threaded server. By using threads to serve requests, it is able to serve a large number of requests with fewer system resources than a process-based server. However, it retains much of the stability of a process-based server by keeping multiple processes available, each with many threads. The most important directives used to control this MPM are T HREADS P ER C HILD, which controls the number of threads deployed by each child process and M AX R EQUEST W ORKERS, which controls the maximum total number of threads that may be launched. Directives • CoreDumpDirectory (p. 990) • EnableExceptionHook (p. 991) • Group (p. 972) • Listen (p. 992) • ListenBacklog (p. 993) • MaxConnectionsPerChild (p. 994) • MaxMemFree (p. 994) • MaxRequestWorkers (p. 994) • MaxSpareThreads (p. 995) • MinSpareThreads (p. 995) • PidFile (p. 996) • ReceiveBufferSize (p. 996) • ScoreBoardFile (p. 996) • SendBufferSize (p. 997) • ServerLimit (p. 997) • StartServers (p. 998) • ThreadLimit (p. 999) • ThreadsPerChild (p. 999) • ThreadStackSize (p. 999) • User (p. 973) See also • Setting which addresses and ports Apache HTTP Server uses (p. 88) 10.136. APACHE MODULE WORKER 1015 How it Works A single control process (the parent) is responsible for launching child processes. Each child process creates a fixed number of server threads as specified in the T HREADS P ER C HILD directive, as well as a listener thread which listens for connections and passes them to a server thread for processing when they arrive. Apache HTTP Server always tries to maintain a pool of spare or idle server threads, which stand ready to serve incoming requests. In this way, clients do not need to wait for a new threads or processes to be created before their requests can be served. The number of processes that will initially launch is set by the S TART S ERVERS directive. During operation, the server assesses the total number of idle threads in all processes, and forks or kills processes to keep this number within the boundaries specified by M IN S PARE T HREADS and M AX S PARE T HREADS. Since this process is very self-regulating, it is rarely necessary to modify these directives from their default values. The maximum number of clients that may be served simultaneously (i.e., the maximum total number of threads in all processes) is determined by the M AX R EQUEST W ORKERS directive. The maximum number of active child processes is determined by the M AX R EQUEST W ORKERS directive divided by the T HREADS P ER C HILD directive. Two directives set hard limits on the number of active child processes and the number of server threads in a child process, and can only be changed by fully stopping the server and then starting it again. S ERVER L IMIT is a hard limit on the number of active child processes, and must be greater than or equal to the M AX R EQUEST W ORKERS directive divided by the T HREADS P ER C HILD directive. T HREAD L IMIT is a hard limit of the number of server threads, and must be greater than or equal to the T HREADS P ER C HILD directive. In addition to the set of active child processes, there may be additional child processes which are terminating, but where at least one server thread is still handling an existing client connection. Up to M AX R EQUEST W ORKERS terminating processes may be present, though the actual number can be expected to be much smaller. This behavior can be avoided by disabling the termination of individual child processes, which is achieved using the following: • set the value of M AX C ONNECTIONS P ER C HILD to zero • set the value of M AX S PARE T HREADS to the same value as M AX R EQUEST W ORKERS A typical configuration of the process-thread controls in the WORKER MPM could look as follows: ServerLimit StartServers MaxRequestWorkers MinSpareThreads MaxSpareThreads ThreadsPerChild 16 2 150 25 75 25 While the parent process is usually started as root under Unix in order to bind to port 80, the child processes and threads are launched by the server as a less-privileged user. The U SER and G ROUP directives are used to set the privileges of the Apache HTTP Server child processes. The child processes must be able to read all the content that will be served, but should have as few privileges beyond that as possible. In addition, unless suexec is used, these directives also set the privileges which will be inherited by CGI scripts. M AX C ONNECTIONS P ER C HILD controls how frequently the server recycles processes by killing old ones and launching new ones. This MPM uses the mpm-accept mutex to serialize access to incoming connections when subject to the thundering herd problem (generally, when there are multiple listening sockets). The implementation aspects of this mutex can be configured with the M UTEX directive. The performance hints (p. 339) documentation has additional information about this mutex. 1016 CHAPTER 10. APACHE MODULES Chapter 11 Developer Documentation 1017 1018 CHAPTER 11. DEVELOPER DOCUMENTATION 11.1 ! Developer Documentation for the Apache HTTP Server 2.4 Warning Many of the documents listed here are in need of update. They are in different stages of progress. Please be patient and follow this linka to propose a fix or point out any error/discrepancy. a https://httpd.apache.org/docs-project/ 2.4 development documents • Developing modules for the Apache HTTP Server 2.4 (p. 1042) • Hook Functions in 2.4 (p. 1071) • Request Processing in 2.4 (p. 1078) • How filters work in 2.4 (p. 1081) • Guidelines for output filters in 2.4 (p. 1084) • Documenting code in 2.4 (p. 1070) • Thread Safety Issues in 2.4 (p. 1091) Upgrading to 2.4 • API changes in 2.3/2.4 (p. 1035) • Converting Modules from 1.3 to 2.x (p. 1074) External Resources • Autogenerated Apache HTTP Server (trunk) code documentation1 (the link is built by this job2 ). • Developer articles at apachetutor3 include: – – – – – Request Processing4 Configuration for Modules5 Resource Management6 Connection Pooling7 Introduction to Buckets and Brigades8 1 http://ci.apache.org/projects/httpd/trunk/doxygen/ 2 https://ci.apache.org/builders/httpd-doxygen-nightly 3 http://www.apachetutor.org/ 4 http://www.apachetutor.org/dev/request 5 http://www.apachetutor.org/dev/config 6 http://www.apachetutor.org/dev/pools 7 http://www.apachetutor.org/dev/reslist 8 http://www.apachetutor.org/dev/brigades 11.2. APACHE 1.3 API NOTES 11.2 ! 1019 Apache 1.3 API notes Warning This document has not been updated to take into account changes made in the 2.0 version of the Apache HTTP Server. Some of the information may still be relevant, but please use it with care. These are some notes on the Apache API and the data structures you have to deal with, etc. They are not yet nearly complete, but hopefully, they will help you get your bearings. Keep in mind that the API is still subject to change as we gain experience with it. (See the TODO file for what might be coming). However, it will be easy to adapt modules to any changes that are made. (We have more modules to adapt than you do). A few notes on general pedagogical style here. In the interest of conciseness, all structure declarations here are incomplete – the real ones have more slots that I’m not telling you about. For the most part, these are reserved to one component of the server core or another, and should be altered by modules with caution. However, in some cases, they really are things I just haven’t gotten around to yet. Welcome to the bleeding edge. Finally, here’s an outline, to give you some bare idea of what’s coming up, and in what order: • Basic concepts. – Handlers, Modules, and Requests – A brief tour of a module • How handlers work – – – – – – A brief tour of the request rec Where request rec structures come from Handling requests, declining, and returning error codes Special considerations for response handlers Special considerations for authentication handlers Special considerations for logging handlers • Resource allocation and resource pools • Configuration, commands and the like – Per-directory configuration structures – Command handling – Side notes — per-server configuration, virtual servers, etc. Basic concepts We begin with an overview of the basic concepts behind the API, and how they are manifested in the code. Handlers, Modules, and Requests Apache breaks down request handling into a series of steps, more or less the same way the Netscape server API does (although this API has a few more stages than NetSite does, as hooks for stuff I thought might be useful in the future). These are: • URI -> Filename translation 1020 CHAPTER 11. DEVELOPER DOCUMENTATION • Auth ID checking [is the user who they say they are?] • Auth access checking [is the user authorized here?] • Access checking other than auth • Determining MIME type of the object requested • ‘Fixups’ – there aren’t any of these yet, but the phase is intended as a hook for possible extensions like S ET E NV, which don’t really fit well elsewhere. • Actually sending a response back to the client. • Logging the request These phases are handled by looking at each of a succession of modules, looking to see if each of them has a handler for the phase, and attempting invoking it if so. The handler can typically do one of three things: • Handle the request, and indicate that it has done so by returning the magic constant OK. • Decline to handle the request, by returning the magic integer constant DECLINED. In this case, the server behaves in all respects as if the handler simply hadn’t been there. • Signal an error, by returning one of the HTTP error codes. This terminates normal handling of the request, although an ErrorDocument may be invoked to try to mop up, and it will be logged in any case. Most phases are terminated by the first module that handles them; however, for logging, ‘fixups’, and non-access authentication checking, all handlers always run (barring an error). Also, the response phase is unique in that modules may declare multiple handlers for it, via a dispatch table keyed on the MIME type of the requested object. Modules may declare a response-phase handler which can handle any request, by giving it the key */* (i.e., a wildcard MIME type specification). However, wildcard handlers are only invoked if the server has already tried and failed to find a more specific response handler for the MIME type of the requested object (either none existed, or they all declined). The handlers themselves are functions of one argument (a request rec structure. vide infra), which returns an integer, as above. A brief tour of a module At this point, we need to explain the structure of a module. Our candidate will be one of the messier ones, the CGI module – this handles both CGI scripts and the S CRIPTA LIAS config file command. It’s actually a great deal more complicated than most modules, but if we’re going to have only one example, it might as well be the one with its fingers in every place. Let’s begin with handlers. In order to handle the CGI scripts, the module declares a response handler for them. Because of S CRIPTA LIAS, it also has handlers for the name translation phase (to recognize S CRIPTA LIASed URIs), the type-checking phase (any S CRIPTA LIASed request is typed as a CGI script). The module needs to maintain some per (virtual) server information, namely, the S CRIPTA LIASes in effect; the module structure therefore contains pointers to a functions which builds these structures, and to another which combines two of them (in case the main server and a virtual server both have S CRIPTA LIASes declared). Finally, this module contains code to handle the S CRIPTA LIAS command itself. This particular module only declares one command, but there could be more, so modules have command tables which declare their commands, and describe where they are permitted, and how they are to be invoked. A final note on the declared types of the arguments of some of these commands: a pool is a pointer to a resource pool structure; these are used by the server to keep track of the memory which has been allocated, files opened, etc., either to service a particular request, or to handle the process of configuring itself. That way, when the request is over (or, for the configuration pool, when the server is restarting), the memory can be freed, and the files closed, en masse, without anyone having to write explicit code to track them all down and dispose of them. Also, a cmd parms structure 11.2. APACHE 1.3 API NOTES 1021 contains various information about the config file being read, and other status information, which is sometimes of use to the function which processes a config-file command (such as S CRIPTA LIAS). With no further ado, the module itself: /* Declarations of handlers. */ int translate scriptalias (request rec *); int type scriptalias (request rec *); int cgi handler (request rec *); /* Subsidiary dispatch table for response-phase * handlers, by MIME type */ handler rec cgi handlers[] = { { "application/x-httpd-cgi", cgi handler }, { NULL } }; /* Declarations of routines to manipulate the * module’s configuration info. Note that these are * returned, and passed in, as void *’s; the server * core keeps track of them, but it doesn’t, and can’t, * know their internal structure. */ void *make cgi server config (pool *); void *merge cgi server config (pool *, void *, void *); /* Declarations of routines to handle config-file commands */ extern char *script alias(cmd parms *, void *per dir config, char *fake, char *real); command rec cgi cmds[] = { { "ScriptAlias", script alias, NULL, RSRC CONF, TAKE2, "a fakename and a realname"}, { NULL } }; module cgi module = { STANDARD_MODULE_STUFF, NULL, NULL, NULL, make_cgi_server_config, merge_cgi_server_config, cgi_cmds, cgi_handlers, translate_scriptalias, NULL, NULL, NULL, type_scriptalias, NULL, NULL, NULL }; /* /* /* /* /* /* /* /* /* /* /* /* /* /* /* initializer */ dir config creator */ dir merger */ server config */ merge server config */ command table */ handlers */ filename translation */ check_user_id */ check auth */ check access */ type_checker */ fixups */ logger */ header parser */ 1022 CHAPTER 11. DEVELOPER DOCUMENTATION How handlers work The sole argument to handlers is a request rec structure. This structure describes a particular request which has been made to the server, on behalf of a client. In most cases, each connection to the client generates only one request rec structure. A brief tour of the request rec The request rec contains pointers to a resource pool which will be cleared when the server is finished handling the request; to structures containing per-server and per-connection information, and most importantly, information on the request itself. The most important such information is a small set of character strings describing attributes of the object being requested, including its URI, filename, content-type and content-encoding (these being filled in by the translation and type-check handlers which handle the request, respectively). Other commonly used data items are tables giving the MIME headers on the client’s original request, MIME headers to be sent back with the response (which modules can add to at will), and environment variables for any subprocesses which are spawned off in the course of servicing the request. These tables are manipulated using the ap table get and ap table set routines. =⇒theNoteapthattable the Content-type header value cannot be set by module content-handlers using () routines. Rather, it is set by pointing the content type field in the * request rec structure to an appropriate string. e.g., r->content type = "text/html"; Finally, there are pointers to two data structures which, in turn, point to per-module configuration structures. Specifically, these hold pointers to the data structures which the module has built to describe the way it has been configured to operate in a given directory (via .htaccess files or sections), for private data it has built in the course of servicing the request (so modules’ handlers for one phase can pass ‘notes’ to their handlers for other phases). There is another such configuration vector in the server rec data structure pointed to by the request rec, which contains per (virtual) server configuration data. Here is an abridged declaration, giving the fields most commonly used: 11.2. APACHE 1.3 API NOTES 1023 struct request rec { pool *pool; conn rec *connection; server rec *server; /* What object is being requested */ char *uri; char *filename; char *path info; char *args; struct stat finfo; /* QUERY_ARGS, if any */ /* Set by server core; * st_mode set to zero if no such file */ char *content type; char *content encoding; /* MIME header environments, in and out. Also, * an array containing environment variables to * be passed to subprocesses, so people can write * modules to add to that environment. * * The difference between headers out and * err headers out is that the latter are printed * even on error, and persist across internal * redirects (so the headers printed for * E R R O R D O C U M E N T handlers will have them). */ table *headers in; table *headers out; table *err headers out; table *subprocess env; /* Info about the request itself... int header_only; char *protocol; char *method; int method_number; /* /* /* /* */ HEAD request, as opposed to GET */ Protocol, as given to us, or HTTP/0.9 */ GET, HEAD, POST, etc. */ M_GET, M_POST, etc. */ /* Info for logging */ char *the request; int bytes sent; /* A flag which modules can set, to indicate that * the data being returned is volatile, and clients * should be told not to cache it. */ int no cache; /* Various other config info which may change * with .htaccess files * These are config vectors, with one void* * pointer for each module (the thing pointed * to being the module’s business). */ void *per_dir_config; void *request_config; }; /* Options set in config files, etc. */ /* Notes on *this* request */ 1024 CHAPTER 11. DEVELOPER DOCUMENTATION Where request rec structures come from Most request rec structures are built by reading an HTTP request from a client, and filling in the fields. However, there are a few exceptions: • If the request is to an imagemap, a type map (i.e., a *.var file), or a CGI script which returned a local ‘Location:’, then the resource which the user requested is going to be ultimately located by some URI other than what the client originally supplied. In this case, the server does an internal redirect, constructing a new request rec for the new URI, and processing it almost exactly as if the client had requested the new URI directly. • If some handler signaled an error, and an ErrorDocument is in scope, the same internal redirect machinery comes into play. • Finally, a handler occasionally needs to investigate ‘what would happen if’ some other request were run. For instance, the directory indexing module needs to know what MIME type would be assigned to a request for each directory entry, in order to figure out what icon to use. Such handlers can construct a sub-request, using the functions ap sub req lookup file, ap sub req lookup uri, and ap sub req method uri; these construct a new request rec structure and processes it as you would expect, up to but not including the point of actually sending a response. (These functions skip over the access checks if the sub-request is for a file in the same directory as the original request). (Server-side includes work by building sub-requests and then actually invoking the response handler for them, via the function ap run sub req). Handling requests, declining, and returning error codes As discussed above, each handler, when invoked to handle a particular request rec, has to return an int to indicate what happened. That can either be • OK – the request was handled successfully. This may or may not terminate the phase. • DECLINED – no erroneous condition exists, but the module declines to handle the phase; the server tries to find another. • an HTTP error code, which aborts handling of the request. Note that if the error code returned is REDIRECT, then the module should put a Location in the request’s headers out, to indicate where the client should be redirected to. Special considerations for response handlers Handlers for most phases do their work by simply setting a few fields in the request rec structure (or, in the case of access checkers, simply by returning the correct error code). However, response handlers have to actually send a request back to the client. They should begin by sending an HTTP response header, using the function ap send http header. (You don’t have to do anything special to skip sending the header for HTTP/0.9 requests; the function figures out on its own that it shouldn’t do anything). If the request is marked header only, that’s all they should do; they should return after that, without attempting any further output. Otherwise, they should produce a request body which responds to the client as appropriate. The primitives for this are ap rputc and ap rprintf, for internally generated output, and ap send fd, to copy the contents of some FILE * straight to the client. 11.2. APACHE 1.3 API NOTES 1025 At this point, you should more or less understand the following piece of code, which is the handler which handles GET requests which have no more specific handler; it also shows how conditional GETs can be handled, if it’s desirable to do so in a particular response handler – ap set last modified checks against the If-modified-since value supplied by the client, if any, and returns an appropriate code (which will, if nonzero, be USE LOCAL COPY). No similar considerations apply for ap set content length, but it returns an error code for symmetry. int default handler (request rec *r) { int errstatus; FILE *f; if (r->method number != M GET) return DECLINED; if (r->finfo.st mode == 0) return NOT FOUND; if ((errstatus = ap set content length (r, r->finfo.st size)) || (errstatus = ap set last modified (r, r->finfo.st mtime))) return errstatus; f = fopen (r->filename, "r"); if (f == NULL) { log reason("file permissions deny server access", r->filename, r); return FORBIDDEN; } register timeout ("send", r); ap send http header (r); if (!r->header only) send fd (f, r); ap pfclose (r->pool, f); return OK; } Finally, if all of this is too much of a challenge, there are a few ways out of it. First off, as shown above, a response handler which has not yet produced any output can simply return an error code, in which case the server will automatically produce an error response. Secondly, it can punt to some other handler by invoking ap internal redirect, which is how the internal redirection machinery discussed above is invoked. A response handler which has internally redirected should always return OK. (Invoking ap internal redirect from handlers which are not response handlers will lead to serious confusion). Special considerations for authentication handlers Stuff that should be discussed here in detail: • Authentication-phase handlers not invoked unless auth is configured for the directory. • Common auth configuration stored in the core per-dir configuration; it has accessors ap auth type, ap auth name, and ap requires. • Common routines, to handle the protocol end of things, at least for HTTP basic authentication (ap get basic auth pw, which sets the connection->user structure field automatically, and ap note basic auth failure, which arranges for the proper WWW-Authenticate: header to be sent back). 1026 CHAPTER 11. DEVELOPER DOCUMENTATION Special considerations for logging handlers When a request has internally redirected, there is the question of what to log. Apache handles this by bundling the entire chain of redirects into a list of request rec structures which are threaded through the r->prev and r->next pointers. The request rec which is passed to the logging handlers in such cases is the one which was originally built for the initial request from the client; note that the bytes sent field will only be correct in the last request in the chain (the one for which a response was actually sent). Resource allocation and resource pools One of the problems of writing and designing a server-pool server is that of preventing leakage, that is, allocating resources (memory, open files, etc.), without subsequently releasing them. The resource pool machinery is designed to make it easy to prevent this from happening, by allowing resource to be allocated in such a way that they are automatically released when the server is done with them. The way this works is as follows: the memory which is allocated, file opened, etc., to deal with a particular request are tied to a resource pool which is allocated for the request. The pool is a data structure which itself tracks the resources in question. When the request has been processed, the pool is cleared. At that point, all the memory associated with it is released for reuse, all files associated with it are closed, and any other clean-up functions which are associated with the pool are run. When this is over, we can be confident that all the resource tied to the pool have been released, and that none of them have leaked. Server restarts, and allocation of memory and resources for per-server configuration, are handled in a similar way. There is a configuration pool, which keeps track of resources which were allocated while reading the server configuration files, and handling the commands therein (for instance, the memory that was allocated for per-server module configuration, log files and other files that were opened, and so forth). When the server restarts, and has to reread the configuration files, the configuration pool is cleared, and so the memory and file descriptors which were taken up by reading them the last time are made available for reuse. It should be noted that use of the pool machinery isn’t generally obligatory, except for situations like logging handlers, where you really need to register cleanups to make sure that the log file gets closed when the server restarts (this is most easily done by using the function ap pfopen, which also arranges for the underlying file descriptor to be closed before any child processes, such as for CGI scripts, are execed), or in case you are using the timeout machinery (which isn’t yet even documented here). However, there are two benefits to using it: resources allocated to a pool never leak (even if you allocate a scratch string, and just forget about it); also, for memory allocation, ap palloc is generally faster than malloc. We begin here by describing how memory is allocated to pools, and then discuss how other resources are tracked by the resource pool machinery. Allocation of memory in pools Memory is allocated to pools by calling the function ap palloc, which takes two arguments, one being a pointer to a resource pool structure, and the other being the amount of memory to allocate (in chars). Within handlers for handling requests, the most common way of getting a resource pool structure is by looking at the pool slot of the relevant request rec; hence the repeated appearance of the following idiom in module code: 11.2. APACHE 1.3 API NOTES 1027 int my handler(request rec *r) { struct my structure *foo; ... foo = (foo *)ap palloc (r->pool, sizeof(my structure)); } Note that there is no ap pfree – ap palloced memory is freed only when the associated resource pool is cleared. This means that ap palloc does not have to do as much accounting as malloc(); all it does in the typical case is to round up the size, bump a pointer, and do a range check. (It also raises the possibility that heavy use of ap palloc could cause a server process to grow excessively large. There are two ways to deal with this, which are dealt with below; briefly, you can use malloc, and try to be sure that all of the memory gets explicitly freed, or you can allocate a sub-pool of the main pool, allocate your memory in the sub-pool, and clear it out periodically. The latter technique is discussed in the section on sub-pools below, and is used in the directory-indexing code, in order to avoid excessive storage allocation when listing directories with thousands of files). Allocating initialized memory There are functions which allocate initialized memory, and are frequently useful. The function ap pcalloc has the same interface as ap palloc, but clears out the memory it allocates before it returns it. The function ap pstrdup takes a resource pool and a char * as arguments, and allocates memory for a copy of the string the pointer points to, returning a pointer to the copy. Finally ap pstrcat is a varargs-style function, which takes a pointer to a resource pool, and at least two char * arguments, the last of which must be NULL. It allocates enough memory to fit copies of each of the strings, as a unit; for instance: ap pstrcat (r->pool, "foo", "/", "bar", NULL); returns a pointer to 8 bytes worth of memory, initialized to "foo/bar". Commonly-used pools in the Apache Web server A pool is really defined by its lifetime more than anything else. There are some static pools in http main which are passed to various non-http main functions as arguments at opportune times. Here they are: permanent pool never passed to anything else, this is the ancestor of all pools pconf • subpool of permanent pool • created at the beginning of a config "cycle"; exists until the server is terminated or restarts; passed to all config-time routines, either via cmd->pool, or as the "pool *p" argument on those which don’t take pools • passed to the module init() functions ptemp • sorry I lie, this pool isn’t called this currently in 1.3, I renamed it this in my pthreads development. I’m referring to the use of ptrans in the parent... contrast this with the later definition of ptrans in the child. • subpool of permanent pool • created at the beginning of a config "cycle"; exists until the end of config parsing; passed to config-time routines via cmd->temp pool. Somewhat of a "bastard child" because it isn’t available everywhere. Used for temporary scratch space which may be needed by some config routines but which is deleted at the end of config. 1028 CHAPTER 11. DEVELOPER DOCUMENTATION pchild • subpool of permanent pool • created when a child is spawned (or a thread is created); lives until that child (thread) is destroyed • passed to the module child init functions • destruction happens right after the child exit functions are called... (which may explain why I think child exit is redundant and unneeded) ptrans • should be a subpool of pchild, but currently is a subpool of permanent pool, see above • cleared by the child before going into the accept() loop to receive a connection • used as connection->pool • for the main request this is a subpool of connection->pool; for subrequests it is a subpool of the parent request’s pool. • exists until the end of the request (i.e., ap destroy sub req, or in child main after process request has finished) • note that r itself is allocated from r->pool; i.e., r->pool is first created and then r is the first thing palloc()d from it r->pool For almost everything folks do, r->pool is the pool to use. But you can see how other lifetimes, such as pchild, are useful to some modules... such as modules that need to open a database connection once per child, and wish to clean it up when the child dies. You can also see how some bugs have manifested themself, such as setting connection->user to a value from r->pool – in this case connection exists for the lifetime of ptrans, which is longer than r->pool (especially if r->pool is a subrequest!). So the correct thing to do is to allocate from connection->pool. And there was another interesting bug in MOD INCLUDE / MOD CGI. You’ll see in those that they do this test to decide if they should use r->pool or r->main->pool. In this case the resource that they are registering for cleanup is a child process. If it were registered in r->pool, then the code would wait() for the child when the subrequest finishes. With MOD INCLUDE this could be any old #include, and the delay can be up to 3 seconds... and happened quite frequently. Instead the subprocess is registered in r->main->pool which causes it to be cleaned up when the entire request is done – i.e., after the output has been sent to the client and logging has happened. Tracking open files, etc. As indicated above, resource pools are also used to track other sorts of resources besides memory. The most common are open files. The routine which is typically used for this is ap pfopen, which takes a resource pool and two strings as arguments; the strings are the same as the typical arguments to fopen, e.g., ... FILE *f = ap pfopen (r->pool, r->filename, "r"); if (f == NULL) { ... } else { ... } There is also a ap popenf routine, which parallels the lower-level open system call. Both of these routines arrange for the file to be closed when the resource pool in question is cleared. Unlike the case for memory, there are functions to close files allocated with ap pfopen, and ap popenf, namely ap pfclose and ap pclosef. (This is because, on many systems, the number of files which a single process can have open is quite limited). It is important to use these functions to close files allocated with ap pfopen and ap popenf, since to do otherwise could cause fatal errors on systems such as Linux, which react badly if the same FILE* is closed more than once. (Using the close functions is not mandatory, since the file will eventually be closed regardless, but you should consider it in cases where your module is opening, or could open, a lot of files). 11.2. APACHE 1.3 API NOTES 1029 Other sorts of resources – cleanup functions More text goes here. spawn process. Describe the cleanup primitives in terms of which the file stuff is implemented; also, Pool cleanups live until clear pool() is called: clear pool(a) recursively calls destroy pool() on all subpools of a; then calls all the cleanups for a; then releases all the memory for a. destroy pool(a) calls clear pool(a) and then releases the pool structure itself. i.e., clear pool(a) doesn’t delete a, it just frees up all the resources and you can start using it again immediately. Fine control – creating and dealing with sub-pools, with a note on sub-requests On rare occasions, too-free use of ap palloc() and the associated primitives may result in undesirably profligate resource allocation. You can deal with such a case by creating a sub-pool, allocating within the sub-pool rather than the main pool, and clearing or destroying the sub-pool, which releases the resources which were associated with it. (This really is a rare situation; the only case in which it comes up in the standard module set is in case of listing directories, and then only with very large directories. Unnecessary use of the primitives discussed here can hair up your code quite a bit, with very little gain). The primitive for creating a sub-pool is ap make sub pool, which takes another pool (the parent pool) as an argument. When the main pool is cleared, the sub-pool will be destroyed. The sub-pool may also be cleared or destroyed at any time, by calling the functions ap clear pool and ap destroy pool, respectively. (The difference is that ap clear pool frees resources associated with the pool, while ap destroy pool also deallocates the pool itself. In the former case, you can allocate new resources within the pool, and clear it again, and so forth; in the latter case, it is simply gone). One final note – sub-requests have their own resource pools, which are sub-pools of the resource pool for the main request. The polite way to reclaim the resources associated with a sub request which you have allocated (using the ap sub req ... functions) is ap destroy sub req, which frees the resource pool. Before calling this function, be sure to copy anything that you care about which might be allocated in the sub-request’s resource pool into someplace a little less volatile (for instance, the filename in its request rec structure). (Again, under most circumstances, you shouldn’t feel obliged to call this function; only 2K of memory or so are allocated for a typical sub request, and it will be freed anyway when the main request pool is cleared. It is only when you are allocating many, many sub-requests for a single main request that you should seriously consider the ap destroy ... functions). Configuration, commands and the like One of the design goals for this server was to maintain external compatibility with the NCSA 1.3 server — that is, to read the same configuration files, to process all the directives therein correctly, and in general to be a drop-in replacement for NCSA. On the other hand, another design goal was to move as much of the server’s functionality into modules which have as little as possible to do with the monolithic server core. The only way to reconcile these goals is to move the handling of most commands from the central server into the modules. However, just giving the modules command tables is not enough to divorce them completely from the server core. The server has to remember the commands in order to act on them later. That involves maintaining data which is private to the modules, and which can be either per-server, or per-directory. Most things are per-directory, including in particular access control and authorization information, but also information on how to determine file types from suffixes, which can be modified by A DD T YPE and F ORCE T YPE directives, and so forth. In general, the governing philosophy is that anything which can be made configurable by directory should be; per-server information is generally used in the standard set of modules for information like A LIASes and R EDIRECTs which come into play before the request is tied to a particular place in the underlying file system. Another requirement for emulating the NCSA server is being able to handle the per-directory configuration files, 1030 CHAPTER 11. DEVELOPER DOCUMENTATION generally called .htaccess files, though even in the NCSA server they can contain directives which have nothing at all to do with access control. Accordingly, after URI -> filename translation, but before performing any other phase, the server walks down the directory hierarchy of the underlying filesystem, following the translated pathname, to read any .htaccess files which might be present. The information which is read in then has to be merged with the applicable information from the server’s own config files (either from the sections in access.conf, or from defaults in srm.conf, which actually behaves for most purposes almost exactly like ). Finally, after having served a request which involved reading .htaccess files, we need to discard the storage allocated for handling them. That is solved the same way it is solved wherever else similar problems come up, by tying those structures to the per-transaction resource pool. Per-directory configuration structures Let’s look out how all of this plays out in mod mime.c, which defines the file typing handler which emulates the NCSA server’s behavior of determining file types from suffixes. What we’ll be looking at, here, is the code which implements the A DD T YPE and A DD E NCODING commands. These commands can appear in .htaccess files, so they must be handled in the module’s private per-directory data, which in fact, consists of two separate tables for MIME types and encoding information, and is declared as follows: typedef struct { table *forced_types; table *encoding_types; } mime_dir_config; /* Additional AddTyped stuff */ /* Added with AddEncoding... */ When the server is reading a configuration file, or section, which includes one of the MIME module’s commands, it needs to create a mime dir config structure, so those commands have something to act on. It does this by invoking the function it finds in the module’s ‘create per-dir config slot’, with two arguments: the name of the directory to which this configuration information applies (or NULL for srm.conf), and a pointer to a resource pool in which the allocation should happen. (If we are reading a .htaccess file, that resource pool is the per-request resource pool for the request; otherwise it is a resource pool which is used for configuration data, and cleared on restarts. Either way, it is important for the structure being created to vanish when the pool is cleared, by registering a cleanup on the pool if necessary). For the MIME module, the per-dir config creation function just ap pallocs the structure above, and a creates a couple of tables to fill it. That looks like this: void *create mime dir config (pool *p, char *dummy) { mime dir config *new = (mime dir config *) ap palloc (p, sizeof(mime dir config)); new->forced types = ap make table (p, 4); new->encoding types = ap make table (p, 4); return new; } Now, suppose we’ve just read in a .htaccess file. We already have the per-directory configuration structure for the next directory up in the hierarchy. If the .htaccess file we just read in didn’t have any A DD T YPE or A DD E NCOD ING commands, its per-directory config structure for the MIME module is still valid, and we can just use it. Otherwise, we need to merge the two structures somehow. 11.2. APACHE 1.3 API NOTES 1031 To do that, the server invokes the module’s per-directory config merge function, if one is present. That function takes three arguments: the two structures being merged, and a resource pool in which to allocate the result. For the MIME module, all that needs to be done is overlay the tables from the new per-directory config structure with those from the parent: void *merge *subdirv) { mime dir mime dir mime dir mime dir configs (pool *p, void *parent dirv, void config *parent dir = (mime dir config *)parent dirv; config *subdir = (mime dir config *)subdirv; config *new = (mime dir config *)ap palloc (p, sizeof(mime dir config)); new->forced types = ap overlay tables (p, subdir->forced types, parent dir->forced types); new->encoding types = ap overlay tables (p, subdir->encoding types, parent dir->encoding types); return new; } As a note – if there is no per-directory merge function present, the server will just use the subdirectory’s configuration info, and ignore the parent’s. For some modules, that works just fine (e.g., for the includes module, whose perdirectory configuration information consists solely of the state of the XBITHACK), and for those modules, you can just not declare one, and leave the corresponding structure slot in the module itself NULL. Command handling Now that we have these structures, we need to be able to figure out how to fill them. That involves processing the actual A DD T YPE and A DD E NCODING commands. To find commands, the server looks in the module’s command table. That table contains information on how many arguments the commands take, and in what formats, where it is permitted, and so forth. That information is sufficient to allow the server to invoke most command-handling functions with pre-parsed arguments. Without further ado, let’s look at the A DD T YPE command handler, which looks like this (the A DD E NCODING command looks basically the same, and won’t be shown here): char *add type(cmd parms *cmd, mime dir config *m, char *ct, char *ext) { if (*ext == ’.’) ++ext; ap table set (m->forced types, ext, ct); return NULL; } This command handler is unusually simple. As you can see, it takes four arguments, two of which are pre-parsed arguments, the third being the per-directory configuration structure for the module in question, and the fourth being a pointer to a cmd parms structure. That structure contains a bunch of arguments which are frequently of use to some, but not all, commands, including a resource pool (from which memory can be allocated, and to which cleanups should be tied), and the (virtual) server being configured, from which the module’s per-server configuration data can be obtained if required. Another way in which this particular command handler is unusually simple is that there are no error conditions which it can encounter. If there were, it could return an error message instead of NULL; this causes an error to be printed out 1032 CHAPTER 11. DEVELOPER DOCUMENTATION on the server’s stderr, followed by a quick exit, if it is in the main config files; for a .htaccess file, the syntax error is logged in the server error log (along with an indication of where it came from), and the request is bounced with a server error response (HTTP error status, code 500). The MIME module’s command table has entries for these commands, which look like this: command rec mime cmds[] = { { "AddType", add type, NULL, OR FILEINFO, TAKE2, "a mime type followed by a file extension" }, { "AddEncoding", add encoding, NULL, OR FILEINFO, TAKE2, "an encoding (e.g., gzip), followed by a file extension" }, { NULL } }; The entries in these tables are: • The name of the command • The function which handles it • a (void *) pointer, which is passed in the cmd parms structure to the command handler — this is useful in case many similar commands are handled by the same function. • A bit mask indicating where the command may appear. There are mask bits corresponding to each AllowOverride option, and an additional mask bit, RSRC CONF, indicating that the command may appear in the server’s own config files, but not in any .htaccess file. • A flag indicating how many arguments the command handler wants pre-parsed, and how they should be passed in. TAKE2 indicates two pre-parsed arguments. Other options are TAKE1, which indicates one pre-parsed argument, FLAG, which indicates that the argument should be On or Off, and is passed in as a boolean flag, RAW ARGS, which causes the server to give the command the raw, unparsed arguments (everything but the command name itself). There is also ITERATE, which means that the handler looks the same as TAKE1, but that if multiple arguments are present, it should be called multiple times, and finally ITERATE2, which indicates that the command handler looks like a TAKE2, but if more arguments are present, then it should be called multiple times, holding the first argument constant. • Finally, we have a string which describes the arguments that should be present. If the arguments in the actual config file are not as required, this string will be used to help give a more specific error message. (You can safely leave this NULL). Finally, having set this all up, we have to use it. This is ultimately done in the module’s handlers, specifically for its file-typing handler, which looks more or less like this; note that the per-directory configuration structure is extracted from the request rec’s per-directory configuration vector by using the ap get module config function. 11.2. APACHE 1.3 API NOTES 1033 int find ct(request rec *r) { int i; char *fn = ap pstrdup (r->pool, r->filename); mime dir config *conf = (mime dir config *) ap get module config(r->per dir config, &mime module); char *type; if (S ISDIR(r->finfo.st mode)) { r->content type = DIR MAGIC TYPE; return OK; } if((i=ap rind(fn,’.’)) ++i; < 0) return DECLINED; if ((type = ap table get (conf->encoding types, &fn[i]))) { r->content encoding = type; /* go back to previous extension to try to use it as a type */ fn[i-1] = ’\0’; if((i=ap rind(fn,’.’)) < 0) return OK; ++i; } if ((type = ap table get (conf->forced types, &fn[i]))) { r->content type = type; } return OK; } Side notes – per-server configuration, virtual servers, etc. The basic ideas behind per-server module configuration are basically the same as those for per-directory configuration; there is a creation function and a merge function, the latter being invoked where a virtual server has partially overridden the base server configuration, and a combined structure must be computed. (As with per-directory configuration, the default if no merge function is specified, and a module is configured in some virtual server, is that the base configuration is simply ignored). The only substantial difference is that when a command needs to configure the per-server private module data, it needs to go to the cmd parms data to get at it. Here’s an example, from the alias module, which also indicates how a syntax error can be returned (note that the per-directory configuration argument to the command handler is declared as a dummy, since the module doesn’t actually have per-directory config data): 1034 CHAPTER 11. DEVELOPER DOCUMENTATION char *add redirect(cmd parms *cmd, void *dummy, char *f, char *url) { server rec *s = cmd->server; alias server conf *conf = (alias server conf *) ap get module config(s->module config,&alias module); alias entry *new = ap push array (conf->redirects); if (!ap is url (url)) return "Redirect to non-URL"; new->fake = f; new->real = url; return NULL; } 11.3. API CHANGES IN APACHE HTTP SERVER 2.4 SINCE 2.2 11.3 1035 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 VERSIONING9 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. Changed APIs ap expr (NEW!) Introduces a new API to parse and evaluate boolean and algebraic expressions, including provision for a standard syntax and customised variants. ap listen (changed; backwards-compatible) Introduces a new API to enable httpd child processes to serve different purposes. ap mpm (changed) ap mpm run is replaced by a new mpm hook. ap mpm register timed callback is new. Also ap graceful stop signalled is lost, and ap regex (changed) 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. ap slotmem (NEW!) Introduces an API for modules to allocate and manage memory slots, most commonly for shared memory. ap socache (NEW!) API to manage a shared object cache. heartbeat (NEW!) common structures for heartbeat modules 9 http://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.x/VERSIONING 1036 CHAPTER 11. DEVELOPER DOCUMENTATION ap parse htaccess (changed) 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). http config (changed) • Introduces per-module, per-directory loglevels, including macro wrappers. • New AP DECLARE MODULE macro to declare all modules. • New APLOG USE MODULE macro necessary for per-module loglevels in multi-file modules. • New API to retain data across module unload/load • New check config hook • New ap process fnmatch configs() function to process wildcards • Change ap configfile t, ap cfg getline(), ap cfg getc() to return error codes, and add ap pcfg strerror() for retrieving an error description. • Any config directive permitted in ACCESS CONF context must now correctly handle being called from an .htaccess file via the new A LLOW OVERRIDE L IST directive. ap check cmd context() accepts a new flag NOT IN HTACCESS to detect this case. http core (changed) • REMOVED ap default type, ap requires, all 2.2 authnz API • Introduces Optional Functions for logio and authnz • New function ap get server name for url to support IPv6 literals. • New function ap register errorlog handler to register error log format string handlers. • Arguments of error log hook have changed. Declaration has moved to http core.h. • New function 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. • New function ap get conn socket to get the socket descriptor for a connection. This should be used instead of accessing the core connection config directly. httpd (changed) • Introduce per-directory, per-module loglevel • New loglevels APLOG TRACEn • Introduce errorlog ids for requests and connections • Support for mod request kept body • Support buffering filter data for async requests • New CONN STATE values • Function changes: ap escape html ap escape path segment buffer updated; ap unescape all, • Modules that load other modules later than the EXEC ON READ config reading stage need to call ap reserve module slots() or ap reserve module slots directive() in their pre config hook. 11.3. API CHANGES IN APACHE HTTP SERVER 2.4 SINCE 2.2 1037 • The useragent IP address per request can now be tracked independently of the client IP address of the connection, for support of deployments with load balancers. http log (changed) • Introduce per-directory, per-module loglevel • New loglevels 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) • piped logging revamped • module index added to error log hook • new function: ap log command line http request (changed) • New auth internal API and auth provider API • New EOR bucket type • New function ap process async request • New flags AP AUTH INTERNAL PER CONF and AP AUTH INTERNAL PER URI • New access checker ex hook to apply additional access control and/or bypass authentication. • New functions ap hook check access ex, ap hook check access, ap hook check authn, ap hook check authz which accept AP AUTH INTERNAL PER * flags • DEPRECATED direct use of ap hook access checker, ap hook check user id, ap hook auth checker access checker ex, 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. mod auth (NEW!) Introduces the new provider framework for authn and authz mod cache (changed) 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. mod core (NEW!) This introduces low-level APIs to send arbitrary headers, and exposes functions to handle HTTP OPTIONS and TRACE. 1038 CHAPTER 11. DEVELOPER DOCUMENTATION mod cache disk (changed) 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. mod disk cache (renamed) 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. mod request (NEW!) The API for MOD REQUEST, to make input data available to multiple application/handler modules where required, and to parse HTML form data. mpm common (changed) • REMOVES: accept, lockfile, lock mech, set scoreboard (locking uses the new ap mutex API) • NEW API to drop privileges (delegates this platform-dependent function to modules) • NEW Hooks: mpm query, timed callback, and get name • CHANGED interfaces: ap relieve child processes monitor hook, ap reclaim child processes, scoreboard (changed) ap get scoreboard worker is made non-backwards-compatible as an alternative version is introduced. Additional proxy balancer support. Child status stuff revamped. util cookies (NEW!) Introduces a new API for managing HTTP Cookies. util ldap (changed) no description available util mutex (NEW!) A wrapper for APR proc and global mutexes in httpd, providing common configuration for the underlying mechanism and location of lock files. util script (changed) NEW: ap args to table 11.3. API CHANGES IN APACHE HTTP SERVER 2.4 SINCE 2.2 1039 util time (changed) NEW: ap recent ctime ex Specific information on upgrading modules from 2.2 Logging 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 #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 behavor 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: • Check current use of APLOG DEBUG and consider if one of the APLOG TRACEn levels is more appropriate. 1040 CHAPTER 11. DEVELOPER DOCUMENTATION • If your module currently has a mechanism for configuring the amount of debug logging which is performed, consider eliminating that mechanism and relying on the use of different 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.) If your module uses these existing APIs... ap default type() This is no longer available; Content-Type must be configured explicitly or added by the application. ap get server name() If the returned server name is used in a URL, use 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() For logging purposes, where detailed information is appropriate, use 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() Replace with a call to 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 Use ap mpm query() query codes AP MPMQ MAX DAEMON USED, AP MPMQ GENERATION, and AP MPMQ MAX THREADS, respectively. ap mpm query() Ensure that it is not used until after the register-hooks hook has completed. Otherwise, an MPM built as a DSO would not have had a chance to enable support for this function. ap requires() The core server now provides better infrastructure for handling R EQUIRE configuration. Register an auth provider function for each supported entity using ap register auth provider(). The function will be called as necessary during R EQUIRE processing. (Consult bundled modules for detailed examples.) ap server conf->process->pool userdata Optional: • If your module uses this to determine which pass of the startup hooks is being run, use ap state query(AP SQ MAIN STATE). • If your module uses this to maintain data across the unloading and reloading of your module, use ap retained data create() and ap retained data get(). apr global mutex create(), apr proc mutex create() Optional: See ap mutex register(), ap global mutex create(), and ap proc mutex create(); these allow your mutexes to be configurable with the M UTEX directive; you can also remove any configuration mechanisms in your module for such mutexes CORE PRIVATE This is now unnecessary and ignored. dav new error() and dav new error tag() Previously, these assumed that 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. The header file and most of the default configuration values set in it are no longer visible to modules. (Most can still be overridden at build time.) DEFAULT PIDLOG and DEFAULT REL RUNTIMEDIR are now universally available via ap config.h. 11.3. API CHANGES IN APACHE HTTP SERVER 2.4 SINCE 2.2 1041 unixd config This has been renamed to ap unixd config. conn rec->remote ip and conn rec->remote addr These fields have been renamed in order to distinguish between the client IP address of the connection and the useragent IP address of the request (potentially overridden by a load balancer or proxy). References to either of these fields must be updated with one of the following options, as appropriate for the module: • When you require the IP address of the user agent, which might be connected directly to the server, or might optionally be separated from the server by a transparent load balancer or proxy, use request rec->useragent ip and request rec->useragent addr. • When you require the IP address of the client that is connected directly to the server, which might be the useragent or might be the load balancer or proxy itself, use conn rec->client ip and conn rec->client addr. If your module interfaces with this feature... suEXEC Optional: If your module logs an error when 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. Extended status data in the scoreboard In previous releases, 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. Does your module... Parse query args Consider if ap args to table() would be helpful. Parse form data... Use ap parse form data(). Check for request header fields Content-Length and Transfer-Encoding to see if a body was specified Use ap request has body(). Implement cleanups which clear pointer variables Use ap pool cleanup set null(). Create run-time files such as shared memory files, pid files, etc. Use 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 D EFAULT RUNTIME D IR directive, will be respected. Apache httpd 2.4.2 and above. 1042 11.4 CHAPTER 11. DEVELOPER DOCUMENTATION Developing modules for the Apache HTTP Server 2.4 This document explains how you can develop modules for the Apache HTTP Server 2.4 See also • Request Processing in Apache 2.4 (p. 1078) • Apache 2.x Hook Functions (p. 1071) Introduction What we will be discussing in this document This document will discuss how you can create modules for the Apache HTTP Server 2.4, by exploring an example module called mod example. In the first part of this document, the purpose of this module will be to calculate and print out various digest values for existing files on your web server, whenever we access the URL http://hostname/filename.sum. For instance, if we want to know the MD5 digest value of the file located at http://www.example.com/index.html, we would visit http://www.example.com/index.html.sum. In the second part of this document, which deals with configuration directive and context awareness, we will be looking at a module that simply writes out its own configuration to the client. Prerequisites First and foremost, you are expected to have a basic knowledge of how the C programming language works. In most cases, we will try to be as pedagogical as possible and link to documents describing the functions used in the examples, but there are also many cases where it is necessary to either just assume that "it works" or do some digging yourself into what the hows and whys of various function calls. Lastly, you will need to have a basic understanding of how modules are loaded and configured in the Apache HTTP Server, as well as how to get the headers for Apache if you do not have them already, as these are needed for compiling new modules. Compiling your module To compile the source code we are building in this document, we will be using APXS (p. 303) . Assuming your source file is called mod example.c, compiling, installing and activating the module is as simple as: apxs -i -a -c mod_example.c 11.4. DEVELOPING MODULES FOR THE APACHE HTTP SERVER 2.4 1043 Defining a module Every module starts with the same declaration, or name tag if you will, that defines a module as a separate entity within Apache: module AP_MODULE_DECLARE_DATA example_module = { STANDARD20_MODULE_STUFF, create_dir_conf, /* Per-directory configuration handler */ merge_dir_conf, /* Merge handler for per-directory configurations */ create_svr_conf, /* Per-server configuration handler */ merge_svr_conf, /* Merge handler for per-server configurations */ directives, /* Any directives we may have for httpd */ register_hooks /* Our hook registering function */ }; This bit of code lets the server know that we have now registered a new module in the system, and that its name is example module. The name of the module is used primarily for two things: • Letting the server know how to load the module using the LoadModule • Setting up a namespace for the module to use in configurations For now, we’re only concerned with the first purpose of the module name, which comes into play when we need to load the module: LoadModule example_module "modules/mod_example.so" In essence, this tells the server to open up mod example.so and look for a module called example module. Within this name tag of ours is also a bunch of references to how we would like to handle things: Which directives do we respond to in a configuration file or .htaccess, how do we operate within specific contexts, and what handlers are we interested in registering with the Apache HTTP service. We’ll return to all these elements later in this document. Getting started: Hooking into the server An introduction to hooks When handling requests in Apache HTTP Server 2.4, the first thing you will need to do is create a hook into the request handling process. A hook is essentially a message telling the server that you are willing to either serve or at least take a glance at certain requests given by clients. All handlers, whether it’s mod rewrite, mod authn *, 1044 CHAPTER 11. DEVELOPER DOCUMENTATION mod proxy and so on, are hooked into specific parts of the request process. As you are probably aware, modules serve different purposes; Some are authentication/authorization handlers, others are file or script handlers while some third modules rewrite URIs or proxies content. Furthermore, in the end, it is up to the user of the server how and when each module will come into place. Thus, the server itself does not presume to know which module is responsible for handling a specific request, and will ask each module whether they have an interest in a given request or not. It is then up to each module to either gently decline serving a request, accept serving it or flat out deny the request from being served, as authentication/authorization modules do: To make it a bit easier for handlers such as our mod example to know whether the client is requesting content we should handle or not, the server has directives for hinting to modules whether their assistance is needed or not. Two of these are A DD H ANDLER and S ET H ANDLER. Let’s take a look at an example using A DD H ANDLER. In our example case, we want every request ending with .sum to be served by mod example, so we’ll add a configuration directive that tells the server to do just that: AddHandler example-handler ".sum" What this tells the server is the following: Whenever we receive a request for a URI ending in .sum, we are to let all modules know that we are looking for whoever goes by the name of "example-handler" . Thus, when a request is being served that ends in .sum, the server will let all modules know, that this request should be served by "examplehandler". As you will see later, when we start building mod example, we will check for this handler tag relayed by AddHandler and reply to the server based on the value of this tag. Hooking into httpd To begin with, we only want to create a simple handler, that replies to the client browser when a specific URL is requested, so we won’t bother setting up configuration handlers and directives just yet. Our initial module definition will look like this: module AP_MODULE_DECLARE_DATA example_module = 11.4. DEVELOPING MODULES FOR THE APACHE HTTP SERVER 2.4 1045 { STANDARD20_MODULE_STUFF, NULL, NULL, NULL, NULL, NULL, register_hooks /* Our hook registering function */ }; This lets the server know that we are not interested in anything fancy, we just want to hook onto the requests and possibly handle some of them. The reference in our example declaration, register hooks is the name of a function we will create to manage how we hook onto the request process. In this example module, the function has just one purpose; To create a simple hook that gets called after all the rewrites, access control etc has been handled. Thus, we will let the server know, that we want to hook into its process as one of the last modules: static void register_hooks(apr_pool_t *pool) { /* Create a hook in the request handler, so we get called when a request arrives */ ap_hook_handler(example_handler, NULL, NULL, APR_HOOK_LAST); } The example handler reference is the function that will handle the request. We will discuss how to create a handler in the next chapter. Other useful hooks Hooking into the request handling phase is but one of many hooks that you can create. Some other ways of hooking are: • ap hook child init: Place a hook that executes when a child process is spawned (commonly used for initializing modules after the server has forked) • ap hook pre config: Place a hook that executes before any configuration data has been read (very early hook) • ap hook post config: Place a hook that executes after configuration has been parsed, but before the server has forked • ap hook translate name: Place a hook that executes when a URI needs to be translated into a filename on the server (think mod rewrite) • ap hook quick handler: Similar to ap hook handler, except it is run before any other request hooks (translation, auth, fixups etc) • ap hook log transaction: Place a hook that executes when the server is about to add a log entry of the current request Building a handler A handler is essentially a function that receives a callback when a request to the server is made. It is passed a record of the current request (how it was made, which headers and requests were passed along, who’s giving the request and so on), and is put in charge of either telling the server that it’s not interested in the request or handle the request with the tools provided. 1046 CHAPTER 11. DEVELOPER DOCUMENTATION A simple "Hello, world!" handler Let’s start off by making a very simple request handler that does the following: 1. Check that this is a request that should be served by "example-handler" 2. Set the content type of our output to text/html 3. Write "Hello, world!" back to the client browser 4. Let the server know that we took care of this request and everything went fine In C code, our example handler will now look like this: static int example_handler(request_rec *r) { /* First off, we need to check if this is a call for the "example-handler" handler. * If it is, we accept it and do our things, if not, we simply return DECLINED, * and the server will try somewhere else. */ if (!r->handler || strcmp(r->handler, "example-handler")) return (DECLINED); /* Now that we are handling this request, we’ll write out "Hello, world!" to the client * To do so, we must first set the appropriate content type, followed by our output. */ ap_set_content_type(r, "text/html"); ap_rprintf(r, "Hello, world!"); /* Lastly, we must tell the server that we took care of this request and everything wen * We do so by simply returning the value OK to the server. */ return OK; } Now, we put all we have learned together and end up with a program that looks like mod example 1.c10 . The functions used in this example will be explained later in the section "Some useful functions you should know". The request rec structure The most essential part of any request is the request record . In a call to a handler function, this is represented by the request rec* structure passed along with every call that is made. This struct, typically just referred to as r in modules, contains all the information you need for your module to fully process any HTTP request and respond accordingly. Some key elements of the request rec structure are: • r->handler (char*): Contains the name of the handler the server is currently asking to do the handling of this request • r->method (char*): Contains the HTTP method being used, f.x. GET or POST • r->filename (char*): Contains the translated filename the client is requesting • r->args (char*): Contains the query string of the request, if any 10 http://people.apache.org/˜humbedooh/mods/examples/mod example 1.c 11.4. DEVELOPING MODULES FOR THE APACHE HTTP SERVER 2.4 1047 • r->headers in (apr table t*): Contains all the headers sent by the client • r->connection (conn rec*): A record containing information about the current connection • r->user (char*): If the URI requires authentication, this is set to the username provided • r->useragent ip (char*): The IP address of the client connecting to us • r->pool (apr pool t*): The memory pool of this request. We’ll discuss this in the "Memory management" chapter. A complete list of all the values contained within the request rec structure can be found in the httpd.h11 header file or at http://ci.apache.org/projects/httpd/trunk/doxygen/structrequest rec.html. Let’s try out some of these variables in another example handler: static int example_handler(request_rec *r) { /* Set the appropriate content type */ ap_set_content_type(r, "text/html"); /* Print out the IP address of the client connecting to us: */ ap_rprintf(r, "

Hello, %s!

* "/foo/bar/gum" -> "gum"
* "/foo/bar/gum/" -> ""
* "gum" -> "gum"
* "wi\\n32\\stuff" -> "stuff"
* 

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.5
Linearized                      : No
Page Count                      : 1138
Page Mode                       : UseOutlines
Author                          : Apache Software Foundation
Title                           : Apache HTTP Server Documentation Version 2.5
Subject                         : 
Creator                         : LaTeX with hyperref package
Producer                        : pdfTeX-1.40.15
Create Date                     : 2016:06:01 12:37:14-04:00
Modify Date                     : 2016:06:01 12:37:14-04:00
Trapped                         : False
PTEX Fullbanner                 : This is pdfTeX, Version 3.14159265-2.6-1.40.15 (TeX Live 2014) kpathsea version 6.2.0