<p>When httpd starts, it binds to some port and address on
the local machine and waits for incoming requests. By default,
it listens to all addresses on the machine. However, it may need to
- be told to listen on specific ports, or only on selected
- addresses, or a combination of both. This is often combined with the
- <a href="vhosts.html">Virtual Host</a> feature, which determines how
- <code>httpd</code> responds to different IP addresses, hostnames and
+ be told to listen on specific ports, or only on selected
+ addresses, or a combination of both. This is often combined with the
+ <a href="vhosts.html">Virtual Host</a> feature, which determines how
+ <code>httpd</code> responds to different IP addresses, hostnames and
ports.</p>
<p>The <directive module="mpm_common">Listen</directive>
incoming requests only on the specified port(s) or
address-and-port combinations. If only a port number is
specified in the <directive module="mpm_common">Listen</directive>
- directive, the server listens to the given port on all interfaces.
+ directive, 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 <directive
+ on the given port and interface. Multiple <directive
module="mpm_common">Listen</directive> directives may be used to
specify a number of addresses and ports to listen on. The
server will respond to requests from any of the listed
Listen [2001:db8::a00:20ff:fea7:ccea]:80
</example>
- <note type="warning"><p>Overlapping <directive
- module="mpm_common">Listen</directive> directives will result in a
+ <note type="warning"><p>Overlapping <directive
+ module="mpm_common">Listen</directive> directives will result in a
fatal error which will prevent the server from starting up.</p>
-
+
<example>
(48)Address already in use: make_sock: could not bind to address [::]:80
</example>
<p>A growing number of platforms implement IPv6, and
<glossary>APR</glossary> supports IPv6 on most of these platforms,
- allowing httpd to allocate IPv6 sockets, and to handle requests sent
+ allowing httpd to allocate IPv6 sockets, and to handle requests sent
over IPv6.</p>
<p>One complicating factor for httpd administrators is whether or
- not an IPv6 socket can handle both IPv4 connections and IPv6
- connections. Handling IPv4 connections with an IPv6 socket uses
- IPv4-mapped IPv6 addresses, which are allowed by default on most
- platforms, but are disallowed by default on FreeBSD, NetBSD, and
+ not an IPv6 socket can handle both IPv4 connections and IPv6
+ connections. Handling IPv4 connections with an IPv6 socket uses
+ IPv4-mapped IPv6 addresses, which are allowed by default on most
+ platforms, but are disallowed by default on FreeBSD, NetBSD, and
OpenBSD, in order to match the system-wide policy on those
- platforms. On systems where it is disallowed by default, a
+ platforms. On systems where it is disallowed by default, a
special <program>configure</program> parameter can change this behavior
for httpd.</p>
- <p>On the other hand, on some platforms, such as Linux and Tru64, the
- <strong>only</strong> way to handle both IPv6 and IPv4 is to use
- mapped addresses. If you want <code>httpd</code> to handle IPv4 and IPv6 connections
- with a minimum of sockets, which requires using IPv4-mapped IPv6
+ <p>On the other hand, on some platforms, such as Linux and Tru64, the
+ <strong>only</strong> way to handle both IPv6 and IPv4 is to use
+ mapped addresses. If you want <code>httpd</code> to handle IPv4 and IPv6 connections
+ with a minimum of sockets, which requires using IPv4-mapped IPv6
addresses, specify the <code>--enable-v4-mapped</code> <program>
configure</program> option.</p>
- <p><code>--enable-v4-mapped</code> is the default on all platforms except
- FreeBSD, NetBSD, and OpenBSD, so this is probably how your httpd was
+ <p><code>--enable-v4-mapped</code> is the default on all platforms except
+ FreeBSD, NetBSD, and OpenBSD, so this is probably how your httpd was
built.</p>
- <p>If you want httpd to handle IPv4 connections only, regardless of
- what your platform and APR will support, specify an IPv4 address on all
+ <p>If you want httpd to handle IPv4 connections only, regardless of
+ what your platform and APR will support, specify an IPv4 address on all
<directive module="mpm_common">Listen</directive> directives, as in the
following examples:</p>
Listen 192.0.2.1:80
</example>
- <p>If your platform supports it and you want httpd to handle IPv4 and
- IPv6 connections on separate sockets (i.e., to disable IPv4-mapped
+ <p>If your platform supports it and you want httpd to handle IPv4 and
+ IPv6 connections on separate sockets (i.e., to disable IPv4-mapped
addresses), specify the <code>--disable-v4-mapped</code> <program>
configure</program> option. <code>--disable-v4-mapped</code> is the
default on FreeBSD, NetBSD, and OpenBSD.</p>
<title>Specifying the protocol with Listen</title>
<p>The optional second <var>protocol</var> argument of
<directive module="mpm_common">Listen</directive>
- is not required for most
- configurations. If not specified, <code>https</code> is the default for
- port 443 and <code>http</code> the default for all other ports. The
+ is not required for most
+ configurations. If not specified, <code>https</code> is the default for
+ port 443 and <code>http</code> 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
+ to apply protocol specific optimizations with the
<directive module="core">AcceptFilter</directive> directive.</p>
- <p>You only need to set the protocol if you are running on non-standard
+ <p>You only need to set the protocol if you are running on non-standard
ports. For example, running an <code>https</code> site on port 8443:</p>
<example>
<title>How This Works With Virtual Hosts</title>
<p> The <directive
- module="mpm_common">Listen</directive> directive does not implement
+ module="mpm_common">Listen</directive> directive does not implement
Virtual Hosts - it only tells the
main server what addresses and ports to listen on. If no
<directive module="core" type="section">VirtualHost</directive>
<summary>
<p>This document supplements the <module>mod_cache</module>,
- <module>mod_cache_disk</module>, <module>mod_file_cache</module> and <a
+ <module>mod_cache_disk</module>, <module>mod_file_cache</module> and <a
href="programs/htcacheclean.html">htcacheclean</a> reference documentation.
- It describes how to use the Apache HTTP Server's caching features to accelerate web and
+ It describes how to use the Apache HTTP Server's caching features to accelerate web and
proxy serving, while avoiding common problems and misconfigurations.</p>
</summary>
caching architectures provide a powerful means to accelerate HTTP
handling, both as an origin webserver and as a proxy.</p>
- <p><module>mod_cache</module> and its provider modules
- <module>mod_cache_disk</module>
+ <p><module>mod_cache</module> and its provider modules
+ <module>mod_cache_disk</module>
provide intelligent, HTTP-aware caching. The content itself is stored
in the cache, and mod_cache aims to honor all of the various HTTP
headers and options that control the cachability of content. It can
handle both local and proxied content. <module>mod_cache</module>
is aimed at both simple and complex caching configurations, where
- you are dealing with proxied content, dynamic local content or
- have a need to speed up access to local files which change with
+ you are dealing with proxied content, dynamic local content or
+ have a need to speed up access to local files which change with
time.</p>
<p><module>mod_file_cache</module> on the other hand presents a more
basic, but sometimes useful, form of caching. Rather than maintain
the complexity of actively ensuring the cachability of URLs,
- <module>mod_file_cache</module> offers file-handle and memory-mapping
- tricks to keep a cache of files as they were when httpd was last
- started. As such, <module>mod_file_cache</module> is aimed at improving
+ <module>mod_file_cache</module> offers file-handle and memory-mapping
+ tricks to keep a cache of files as they were when httpd was last
+ started. As such, <module>mod_file_cache</module> is aimed at improving
the access time to local static files which do not change very
often.</p>
<p>As <module>mod_file_cache</module> presents a relatively simple
- caching implementation, apart from the specific sections on <directive
- module="mod_file_cache">CacheFile</directive> and <directive
+ caching implementation, apart from the specific sections on <directive
+ module="mod_file_cache">CacheFile</directive> and <directive
module="mod_file_cache">MMapFile</directive>, the explanations
- in this guide cover the <module>mod_cache</module> caching
+ in this guide cover the <module>mod_cache</module> caching
architecture.</p>
- <p>To get the most from this document, you should be familiar with
- the basics of HTTP, and have read the Users' Guides to
- <a href="urlmapping.html">Mapping URLs to the Filesystem</a> and
+ <p>To get the most from this document, you should be familiar with
+ the basics of HTTP, and have read the Users' Guides to
+ <a href="urlmapping.html">Mapping URLs to the Filesystem</a> and
<a href="content-negotiation.html">Content negotiation</a>.</p>
</section>
-
+
<section id="overview">
<title>Caching Overview</title>
-
+
<related>
<modulelist>
<module>mod_cache</module>
<p>There are two main stages in <module>mod_cache</module> that can
occur in the lifetime of a request. First, <module>mod_cache</module>
is a URL mapping module, which means that if a URL has been cached,
- and the cached version of that URL has not expired, the request will
+ and the cached version of that URL has not expired, the request will
be served directly by <module>mod_cache</module>.</p>
<p>This means that any other stages that might ordinarily happen
<p>If the URL is not found within the cache, <module>mod_cache</module>
will add a <a href="filter.html">filter</a> to the request handling. After
httpd has located the content by the usual means, the filter will be run
- as the content is served. If the content is determined to be cacheable,
+ as the content is served. If the content is determined to be cacheable,
the content will be saved to the cache for future serving.</p>
<p>If the URL is found within the cache, but also found to have expired,
<section>
<title>Improving Cache Hits</title>
- <p>When caching locally generated content, ensuring that
- <directive module="core">UseCanonicalName</directive> is set to
+ <p>When caching locally generated content, ensuring that
+ <directive module="core">UseCanonicalName</directive> is set to
<code>On</code> can dramatically improve the ratio of cache hits. This
is because the hostname of the virtual-host serving the content forms
a part of the cache key. With the setting set to <code>On</code>
differently cached entities, and instead content will be cached as
per the canonical hostname.</p>
- <p>Because caching is performed within the URL to filename translation
+ <p>Because caching is performed within the URL to filename translation
phase, cached documents will only be served in response to URL requests.
Ordinarily this is of little consequence, but there is one circumstance
- in which it matters: If you are using <a href="howto/ssi.html">Server
+ in which it matters: If you are using <a href="howto/ssi.html">Server
Side Includes</a>;</p>
<example>
serves from the cache, you should use <code>virtual</code> include
types.</p>
</section>
-
+
<section>
<title>Expiry Periods</title>
-
- <p>The default expiry period for cached entities is one hour, however
- this can be easily over-ridden by using the <directive
+
+ <p>The default expiry period for cached entities is one hour, however
+ this can be easily over-ridden by using the <directive
module="mod_cache">CacheDefaultExpire</directive> directive. This
default is only used when the original source of the content does not
specify an expire time or time of last modification.</p>
<p>If a response does not include an <code>Expires</code> header but does
include a <code>Last-Modified</code> header, <module>mod_cache</module>
- can infer an expiry period based on the use of the <directive
+ can infer an expiry period based on the use of the <directive
module="mod_cache">CacheLastModifiedFactor</directive> directive.</p>
<p>For local content, <module>mod_expires</module> may be used to
<section>
<title>A Brief Guide to Conditional Requests</title>
- <p>When content expires from the cache and is re-requested from the
+ <p>When content expires from the cache and is re-requested from the
backend or content provider, rather than pass on the original request,
httpd will use a conditional request instead.</p>
<p>HTTP offers a number of headers which allow a client, or cache
to discern between different versions of the same content. For
example if a resource was served with an "Etag:" header, it is
- possible to make a conditional request with an "If-None-Match:"
+ possible to make a conditional request with an "If-None-Match:"
header. If a resource was served with a "Last-Modified:" header
- it is possible to make a conditional request with an
+ it is possible to make a conditional request with an
"If-Modified-Since:" header, and so on.</p>
<p>When such a conditional request is made, the response differs
- depending on whether the content matches the conditions. If a request is
- made with an "If-Modified-Since:" header, and the content has not been
- modified since the time indicated in the request then a terse "304 Not
+ depending on whether the content matches the conditions. If a request is
+ made with an "If-Modified-Since:" header, and the content has not been
+ modified since the time indicated in the request then a terse "304 Not
Modified" response is issued.</p>
<p>If the content has changed, then it is served as if the request were
not conditional to begin with.</p>
- <p>The benefits of conditional requests in relation to caching are
- twofold. Firstly, when making such a request to the backend, if the
+ <p>The benefits of conditional requests in relation to caching are
+ twofold. Firstly, when making such a request to the backend, if the
content from the backend matches the content in the store, this can be
determined easily and without the overhead of transferring the entire
resource.</p>
from the cache if it has not changed. As long as reading from the cache
store is faster than reading from the backend (e.g. <module
>mod_cache_disk</module> with memory disk
- compared to reading from disk).</p>
+ compared to reading from disk).</p>
</section>
<section>
<title>What Can be Cached?</title>
- <p>As mentioned already, the two styles of caching in httpd work
- differently, <module>mod_file_cache</module> caching maintains file
- contents as they were when httpd was started. When a request is
- made for a file that is cached by this module, it is intercepted
+ <p>As mentioned already, the two styles of caching in httpd work
+ differently, <module>mod_file_cache</module> caching maintains file
+ contents as they were when httpd was started. When a request is
+ made for a file that is cached by this module, it is intercepted
and the cached file is served.</p>
<p><module>mod_cache</module> caching on the other hand is more
complex. When serving a request, if it has not been cached
previously, the caching module will determine if the content
- is cacheable. The conditions for determining cachability of
+ is cacheable. The conditions for determining cachability of
a response are;</p>
<ol>
- <li>Caching must be enabled for this URL. See the <directive
+ <li>Caching must be enabled for this URL. See the <directive
module="mod_cache">CacheEnable</directive> and <directive
module="mod_cache">CacheDisable</directive> directives.</li>
- <li>The response must have a HTTP status code of 200, 203, 300, 301 or
+ <li>The response must have a HTTP status code of 200, 203, 300, 301 or
410.</li>
<li>The request must be a HTTP GET request.</li>
<li>If the response has a status of 200 (OK), the response must
also include at least one of the "Etag", "Last-Modified" or
the "Expires" headers, or the max-age or s-maxage directive of
- the "Cache-Control:" header, unless the
- <directive module="mod_cache">CacheIgnoreNoLastMod</directive>
+ the "Cache-Control:" header, unless the
+ <directive module="mod_cache">CacheIgnoreNoLastMod</directive>
directive has been used to require otherwise.</li>
<li>If the response includes the "private" option in a "Cache-Control:"
- header, it will not be stored unless the
+ header, it will not be stored unless the
<directive module="mod_cache">CacheStorePrivate</directive> has been
used to require otherwise.</li>
- <li>Likewise, if the response includes the "no-store" option in a
- "Cache-Control:" header, it will not be stored unless the
+ <li>Likewise, if the response includes the "no-store" option in a
+ "Cache-Control:" header, it will not be stored unless the
<directive module="mod_cache">CacheStoreNoStore</directive> has been
used.</li>
<section>
<title>What Should Not be Cached?</title>
-
+
<p>In short, any content which is highly time-sensitive, or which varies
depending on the particulars of the request that are not covered by
HTTP negotiation, should not be cached.</p>
<section>
<title>Variable/Negotiated Content</title>
- <p>If a response with a "Vary" header is received by
+ <p>If a response with a "Vary" header is received by
<module>mod_cache</module> when requesting content by the backend it
- will attempt to handle it intelligently. If possible,
+ will attempt to handle it intelligently. If possible,
<module>mod_cache</module> will detect the headers attributed in the
- "Vary" response in future requests and serve the correct cached
+ "Vary" response in future requests and serve the correct cached
response.</p>
<p>If for example, a response is received with a vary header such as;</p>
<p>As requests to end-users can be served from the cache, the cache
itself can become a target for those wishing to deface or interfere with
content. It is important to bear in mind that the cache must at all
- times be writable by the user which httpd is running as. This is in
+ times be writable by the user which httpd is running as. This is in
stark contrast to the usually recommended situation of maintaining
all content unwritable by the Apache user.</p>
<p>If the Apache user is compromised, for example through a flaw in
a CGI process, it is possible that the cache may be targeted. When
- using <module>mod_cache_disk</module>, it is relatively easy to
+ using <module>mod_cache_disk</module>, it is relatively easy to
insert or modify a cached entity.</p>
- <p>This presents a somewhat elevated risk in comparison to the other
- types of attack it is possible to make as the Apache user. If you are
- using <module>mod_cache_disk</module> you should bear this in mind -
- ensure you upgrade httpd when security upgrades are announced and
- run CGI processes as a non-Apache user using <a
+ <p>This presents a somewhat elevated risk in comparison to the other
+ types of attack it is possible to make as the Apache user. If you are
+ using <module>mod_cache_disk</module> you should bear this in mind -
+ ensure you upgrade httpd when security upgrades are announced and
+ run CGI processes as a non-Apache user using <a
href="suexec.html">suEXEC</a> if possible.</p>
</section>
<title>Cache Poisoning</title>
<p>When running httpd as a caching proxy server, there is also the
- potential for so-called cache poisoning. Cache Poisoning is a broad
- term for attacks in which an attacker causes the proxy server to
+ potential for so-called cache poisoning. Cache Poisoning is a broad
+ term for attacks in which an attacker causes the proxy server to
retrieve incorrect (and usually undesirable) content from the backend.
</p>
</directivelist>
</related>
- <p>The act of opening a file can itself be a source of delay, particularly
+ <p>The act of opening a file can itself be a source of delay, particularly
on network filesystems. By maintaining a cache of open file descriptors
for commonly served files, httpd can avoid this delay. Currently
httpd
- provides one implementation of File-Handle Caching.</p>
+ provides one implementation of File-Handle Caching.</p>
<section>
<title>CacheFile</title>
<p>The most basic form of caching present in httpd is the file-handle
- caching provided by <module>mod_file_cache</module>. Rather than caching
- file-contents, this cache maintains a table of open file descriptors. Files
+ caching provided by <module>mod_file_cache</module>. Rather than caching
+ file-contents, this cache maintains a table of open file descriptors. Files
to be cached in this manner are specified in the configuration file using
- the <directive module="mod_file_cache">CacheFile</directive>
+ the <directive module="mod_file_cache">CacheFile</directive>
directive.</p>
- <p>The
- <directive module="mod_file_cache">CacheFile</directive> directive
- instructs httpd to open the file when it is started and to re-use
+ <p>The
+ <directive module="mod_file_cache">CacheFile</directive> directive
+ instructs httpd to open the file when it is started and to re-use
this file-handle for all subsequent access to this file.</p>
<example>
CacheFile /usr/local/apache2/htdocs/index.html
</example>
- <p>If you intend to cache a large number of files in this manner, you
- must ensure that your operating system's limit for the number of open
+ <p>If you intend to cache a large number of files in this manner, you
+ must ensure that your operating system's limit for the number of open
files is set appropriately.</p>
<p>Although using <directive module="mod_file_cache">CacheFile</directive>
</section>
</section>
-
+
<section id="inmemory">
<title>In-Memory Caching</title>
<directive module="mod_file_cache">MMapFile</directive>
</directivelist>
</related>
-
+
<p>Serving directly from system memory is universally the fastest method
of serving content. Reading files from a disk controller or, even worse,
from a remote network is orders of magnitude slower. Disk controllers
<p>System memory isn't cheap though, byte for byte it's by far the most
expensive type of storage and it's important to ensure that it is used
- efficiently. By caching files in memory you decrease the amount of
+ efficiently. By caching files in memory you decrease the amount of
memory available on the system. As we'll see, in the case of operating
system caching, this is not so much of an issue, but when using
httpd's own in-memory caching it is important to make sure that you
do not allocate too much memory to a cache. Otherwise the system
- will be forced to swap out memory, which will likely degrade
+ will be forced to swap out memory, which will likely degrade
performance.</p>
<section>
of time it takes to read the file. This is because the kernel has cached
the file contents in memory.</p>
- <p>By ensuring there is "spare" memory on your system, you can ensure
- that more and more file-contents will be stored in this cache. This
- can be a very efficient means of in-memory caching, and involves no
+ <p>By ensuring there is "spare" memory on your system, you can ensure
+ that more and more file-contents will be stored in this cache. This
+ can be a very efficient means of in-memory caching, and involves no
extra configuration of httpd at all.</p>
- <p>Additionally, because the operating system knows when files are
- deleted or modified, it can automatically remove file contents from the
- cache when necessary. This is a big advantage over httpd's in-memory
+ <p>Additionally, because the operating system knows when files are
+ deleted or modified, it can automatically remove file contents from the
+ cache when necessary. This is a big advantage over httpd's in-memory
caching which has no way of knowing when a file has changed.</p>
</section>
<p>Despite the performance and advantages of automatic operating system
- caching there are some circumstances in which in-memory caching may be
+ caching there are some circumstances in which in-memory caching may be
better performed by httpd.</p>
<section>
<title>MMapFile Caching</title>
- <p><module>mod_file_cache</module> provides the
+ <p><module>mod_file_cache</module> provides the
<directive module="mod_file_cache">MMapFile</directive> directive, which
allows you to have httpd map a static file's contents into memory at
- start time (using the mmap system call). httpd will use the in-memory
+ start time (using the mmap system call). httpd will use the in-memory
contents for all subsequent accesses to this file.</p>
<example>
changes in these files will not be picked up by httpd after it has
started.</p>
- <p> The <directive module="mod_file_cache">MMapFile</directive>
+ <p> The <directive module="mod_file_cache">MMapFile</directive>
directive does not keep track of how much memory it allocates, so
you must ensure not to over-use the directive. Each httpd child
process will replicate this memory, so it is critically important
system to swap memory.</p>
</section>
</section>
-
+
<section id="disk">
<title>Disk-based Caching</title>
<directive module="mod_cache">CacheDisable</directive>
</directivelist>
</related>
-
- <p><module>mod_cache_disk</module> provides a disk-based caching mechanism
+
+ <p><module>mod_cache_disk</module> provides a disk-based caching mechanism
for <module>mod_cache</module>. This cache is intelligent and content will
be served from the cache only as long as it is considered valid.</p>
<p>Typically the module will be configured as so;</p>
- <example>
+ <example>
CacheRoot /var/cache/apache/<br />
CacheEnable disk /<br />
CacheDirLevels 2<br />
</example>
<p>Importantly, as the cached files are locally stored, operating system
- in-memory caching will typically be applied to their access also. So
- although the files are stored on disk, if they are frequently accessed
+ in-memory caching will typically be applied to their access also. So
+ although the files are stored on disk, if they are frequently accessed
it is likely the operating system will ensure that they are actually
served from memory.</p>
as a prefix for the naming of the files specific to that URL within
the cache, however first it is split up into directories as per
the <directive module="mod_cache_disk">CacheDirLevels</directive> and
- <directive module="mod_cache_disk">CacheDirLength</directive>
+ <directive module="mod_cache_disk">CacheDirLength</directive>
directives.</p>
- <p><directive module="mod_cache_disk">CacheDirLevels</directive>
+ <p><directive module="mod_cache_disk">CacheDirLevels</directive>
specifies how many levels of subdirectory there should be, and
<directive module="mod_cache_disk">CacheDirLength</directive>
specifies how many characters should be in each directory. With
the example settings given above, the hash would be turned into
- a filename prefix as
+ a filename prefix as
<code>/var/cache/apache/x/y/TGxSMO2b68mBCykqkp1w</code>.</p>
<p>The overall aim of this technique is to reduce the number of
subdirectories or files that may be in a particular directory,
as most file-systems slow down as this number increases. With
- setting of "1" for
+ setting of "1" for
<directive module="mod_cache_disk">CacheDirLength</directive>
- there can at most be 64 subdirectories at any particular level.
+ there can at most be 64 subdirectories at any particular level.
With a setting of 2 there can be 64 * 64 subdirectories, and so on.
Unless you have a good reason not to, using a setting of "1"
for <directive module="mod_cache_disk">CacheDirLength</directive>
is recommended.</p>
- <p>Setting
+ <p>Setting
<directive module="mod_cache_disk">CacheDirLevels</directive>
depends on how many files you anticipate to store in the cache.
With the setting of "2" used in the above example, a grand
total of 4096 subdirectories can ultimately be created. With
- 1 million files cached, this works out at roughly 245 cached
+ 1 million files cached, this works out at roughly 245 cached
URLs per directory.</p>
<p>Each URL uses at least two files in the cache-store. Typically
- there is a ".header" file, which includes meta-information about
+ there is a ".header" file, which includes meta-information about
the URL, such as when it is due to expire and a ".data" file
which is a verbatim copy of the content to be served.</p>
<p>In the case of a content negotiated via the "Vary" header, a
- ".vary" directory will be created for the URL in question. This
+ ".vary" directory will be created for the URL in question. This
directory will have multiple ".data" files corresponding to the
differently negotiated content.</p>
</section>
<section>
<title>Maintaining the Disk Cache</title>
-
+
<p>Although <module>mod_cache_disk</module> will remove cached content
as it is expired, it does not maintain any information on the total
size of the cache or how little free space may be left.</p>
- <p>Instead, provided with httpd is the <a
+ <p>Instead, provided with httpd is the <a
href="programs/htcacheclean.html">htcacheclean</a> tool which, as the name
- suggests, allows you to clean the cache periodically. Determining
- how frequently to run <a
- href="programs/htcacheclean.html">htcacheclean</a> and what target size to
+ suggests, allows you to clean the cache periodically. Determining
+ how frequently to run <a
+ href="programs/htcacheclean.html">htcacheclean</a> and what target size to
use for the cache is somewhat complex and trial and error may be needed to
select optimal values.</p>
- <p><a href="programs/htcacheclean.html">htcacheclean</a> has two modes of
- operation. It can be run as persistent daemon, or periodically from
- cron. <a
- href="programs/htcacheclean.html">htcacheclean</a> can take up to an hour
- or more to process very large (tens of gigabytes) caches and if you are
- running it from cron it is recommended that you determine how long a typical
+ <p><a href="programs/htcacheclean.html">htcacheclean</a> has two modes of
+ operation. It can be run as persistent daemon, or periodically from
+ cron. <a
+ href="programs/htcacheclean.html">htcacheclean</a> can take up to an hour
+ or more to process very large (tens of gigabytes) caches and if you are
+ running it from cron it is recommended that you determine how long a typical
run takes, to avoid running more than one instance at a time.</p>
<p class="figure">
cache growth / clean sequence.</p>
<p>Because <module>mod_cache_disk</module> does not itself pay attention
- to how much space is used you should ensure that
- <a href="programs/htcacheclean.html">htcacheclean</a> is configured to
+ to how much space is used you should ensure that
+ <a href="programs/htcacheclean.html">htcacheclean</a> is configured to
leave enough "grow room" following a clean.</p>
</section>
<p>httpd supports 'server driven' content negotiation, as
defined in the HTTP/1.1 specification. It fully supports the
<code>Accept</code>, <code>Accept-Language</code>,
- <code>Accept-Charset</code> and<code>Accept-Encoding</code>
+ <code>Accept-Charset</code> and<code>Accept-Encoding</code>
request headers. httpd also supports 'transparent'
content negotiation, which is an experimental negotiation
protocol defined in RFC 2295 and RFC 2296. It does not offer
<code>.var</code>. In the examples shown below, the resource is
named <code>foo</code>, so the type map file is named
<code>foo.var</code>.</p>
-
+
<p>This file should have an entry for each available
variant; these entries consist of contiguous HTTP-format header
lines. Entries for different variants are separated by blank
not selected at each test are eliminated. After each test,
if only one variant remains, select it as the best match
and proceed to step 3. If more than one variant remains,
- move on to the next test.
+ move on to the next test.
<ol>
<li>Multiply the quality factor from the <code>Accept</code>
</section>
<section id="extensions"><title>Extensions to Transparent Content
-Negotiation</title>
+Negotiation</title>
<p>httpd extends the transparent content negotiation protocol (RFC
2295) as follows. A new <code>{encoding ..}</code> element is used in
<p>Although the Apache HTTP Server provides generic error responses
in the event of 4xx or 5xx HTTP status codes, these responses are
rather stark, uninformative, and can be intimidating to site users.
- You may wish to provide custom error responses which are either
+ You may wish to provide custom error responses which are either
friendlier, or in some language other than English, or perhaps which
are styled more in line with your site layout.</p>
module="core">ErrorDocument</directive> directive,
which may be used in global,
virtualhost, or directory context. It may be used in .htaccess files
- if <directive module="core">AllowOverride</directive> is set to
+ if <directive module="core">AllowOverride</directive> is set to
FileInfo.</p>
<example>
<p>Note that if the response contains <code>Location:</code>
header (in order to issue a client-side redirect), the script
- <em>must</em> emit an appropriate <code>Status:</code> header
- (such as <code>302 Found</code>). Otherwise the
+ <em>must</em> emit an appropriate <code>Status:</code> header
+ (such as <code>302 Found</code>). Otherwise the
<code>Location:</code> header may have no effect.</p>
</section>
provide more useful information to users about your site, and what
they can expect to find there.</p>
- <p><module>mod_include</module> and <module>mod_negotiation</module>
+ <p><module>mod_include</module> and <module>mod_negotiation</module>
must be enabled to use this feature.</p>
</section>
<ul>
<li>
- <a href="#basics">Basic concepts.</a>
+ <a href="#basics">Basic concepts.</a>
<ul>
<li><a href="#HMR">Handlers, Modules, and
</li>
<li>
- <a href="#handlers">How handlers work</a>
+ <a href="#handlers">How handlers work</a>
<ul>
<li><a href="#req_tour">A brief tour of the
pools</a></li>
<li>
- <a href="#config">Configuration, commands and the like</a>
+ <a href="#config">Configuration, commands and the like</a>
<ul>
<li><a href="#per-dir">Per-directory configuration
</li>
</ul>
</summary>
-
+
<section id="basics"><title>Basic concepts</title>
<p>We begin with an overview of the basic concepts behind the API, and how
they are manifested in the code.</p>
describes the modes available and gives instructions on activating
them.</p>
</summary>
-
+
<section id="options"><title>Available debugging options</title>
<section id="alloc_debug">
<title>Allocation Debugging - ALLOC_DEBUG</title>
@return description<br />
@deffunc signature of the function<br />
</example>
-
+
<p>The <code>deffunc</code> is not always necessary. DoxyGen does not
have a full parser in it, so any prototype that use a macro in the
return type declaration is too complex for scandoc. Those functions
might not be SSI data. So, the subrequest adds the following:</p>
<example>
-<pre>
+<pre>
Default_handler --> includes_filter -/-> byterange --> ...
/
Default_handler --> sub_request_core
>Handling configuration directives</a></li>
</ul></li>
- <li><a href="http://www.onlamp.com/pub/ct/38">Some notes on
+ <li><a href="http://www.onlamp.com/pub/ct/38">Some notes on
Apache module development by Ryan Bloom</a></li>
<li>Developer articles at <a href="http://www.apachetutor.org/">apachetutor</a> include:
take advantage of API changes to offer significant improvements).</p>
<p>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
+ reference documentation, and can be used to generate a browsable
HTML reference with <code>make docs</code>.</p>
</summary>
directly. In this way, the code will remain compatible with HTTPD 2.0
and 2.2.</p>
- <p>Code which calls <code>ap_log_*</code> without passing
+ <p>Code which calls <code>ap_log_*</code> without passing
<code>APLOG_MARK</code> will necessarily differ between 2.4 and earlier
releases, as 2.4 requires a new third argument,
<code>APLOG_MODULE_INDEX</code>.</p>
<br />
</example>
- <p>A <code>server_rec</code> pointer must be passed to
+ <p>A <code>server_rec</code> pointer must be passed to
<code>ap_log_error()</code> when called after startup. This
was always appropriate, but there are even more limitations with
a <code>NULL</code> <code>server_rec</code> in 2.4 than in
<code>NULL</code> only when it is valid to pass <code>NULL</code>
to <code>ap_log_error()</code>. <code>ap_server_conf</code>
should be used only when a more appropriate <code>server_rec</code>
- is not available.</p>
+ is not available.</p>
<p>Consider the following changes to take advantage of the new
<code>APLOG_TRACE1..8</code> log levels:</p>
literal address.</dd>
<dt><code>ap_get_server_version()</code></dt>
- <dd>For logging purposes, where detailed information is
+ <dd>For logging purposes, where detailed information is
appropriate, use <code>ap_get_server_description()</code>.
When generating output, where the amount of information
should be configurable by ServerTokens, use
<parentdocument href="./">Developer Documentation</parentdocument>
<title>Guide to writing output filters</title>
-
+
<summary>
<p>There are a number of common pitfalls encountered when writing
output filters; this page aims to document best practice for
<section id="invocation">
<title>Filter invocation</title>
-
+
<p>For any given request, an output filter might be invoked only
- once and be given a single brigade representing the entire response.
+ once and be given a single brigade representing the entire response.
It is also possible that the number of times a filter is invoked
for a single response is proportional to the size of the content
being filtered, with the filter being passed a brigade containing
calling this function (since it comes from a pool), but the
associated pool cleanup is unregistered. Using
<code>apr_brigade_destroy</code> can in fact cause memory leaks;
- if a "destroyed" brigade contains buckets when its
+ if a "destroyed" brigade contains buckets when its
containing pool is destroyed, those buckets will <em>not</em> be
immediately destroyed.</p>
-
+
<p>In general, filters should use <code>apr_brigade_cleanup</code>
in preference to <code>apr_brigade_destroy</code>.</p></note>
<section id="state">
<title>Maintaining state</title>
-
+
<p>A filter which needs to maintain state over multiple
invocations per response can use the <code>->ctx</code> field of
its <code>ap_filter_t</code> structure. It is typical to store a
temporary brigade in such a structure, to avoid having to allocate
a new brigade per invocation as described in the <a
href="#brigade">Brigade structure</a> section.</p>
-
+
<example><title>Example code to maintain filter state</title>
struct dummy_state {<br />
<indent>
</example>
</section>
-
+
<section id="buffer">
<title>Buffering buckets</title>
from every data bucket using a non-blocking read; if that fails
with <code>APR_EAGAIN</code>, then send a <code>FLUSH</code>
bucket down the filter chain, and retry using a blocking read.</p>
-
+
<p>This mode of operation ensures that any filters further down the
filter chain will flush any buffered buckets if a slow content
source is being used.</p>
<li>Output filters must process a fixed amount of data at a
time, to ensure that memory consumption is not proportional to
the size of the content being filtered.</li>
-
+
<li>Output filters should be agnostic with respect to bucket
types, and must be able to process buckets of unfamiliar
type.</li>
before reusing that brigade structure; output filters should
never use <code>apr_brigade_destroy</code> to "destroy"
brigades.</li>
-
+
<li>Output filters must <em>setaside</em> any buckets which are
preserved beyond the duration of the filter function.</li>
allowed to use static or global variables. There are times when you
actually want something to affect all threads, but generally you need to
avoid using them if you want your code to be thread safe.</p>
-
+
<p>In the case where you have a global variable that needs to be global and
accessed by all threads, be very careful when you update it. If, for
example, it is an incrementing counter, you need to atomically increment
to their <code><var>*</var>_r</code> equivalents and sometimes changes
the common <code>getc</code>/<code>putc</code> macros into safer function
calls. Check your libc documentation for specifics. Instead of, or in
- addition to <code>_REENTRANT</code> the symbols that may affect this are
+ addition to <code>_REENTRANT</code> the symbols that may affect this are
<code>_POSIX_C_SOURCE</code>, <code>_THREAD_SAFE</code>,
<code>_SVID_SOURCE</code>, and <code>_BSD_SOURCE</code>.</p>
</section>
users typed in URLs of the form
<code>http://www.example2.dom/whatever</code>) will all be served by
the <code>example1.dom</code> virtual host. To better understand why
- this happens requires a more in-depth discussion of how httpd
+ this happens requires a more in-depth discussion of how httpd
matches up incoming requests with the virtual host that will
serve it. A rough document describing this <a
href="vhosts/details.html">is available</a>.</p>
or maybe <code>/etc/nsswitch.conf</code>.</p>
<p>If your server doesn't have to perform DNS for any other
- reason then you might be able to get away with running httpd
+ reason then you might be able to get away with running httpd
with the <code>HOSTRESORDER</code> environment variable set to
"local". This all depends on what OS and resolver libraries you
are using. It also affects CGIs unless you use
Build and install a <em>third-party</em> Apache httpd module, say
<code>mod_foo.c</code>, into its own DSO
<code>mod_foo.so</code> <em>outside of</em> the Apache httpd
- source tree using <program>apxs</program>:
+ source tree using <program>apxs</program>:
<example>
$ cd /path/to/3rdparty<br />
not be a number. Characters which do not match this
restriction will be replaced by an underscore when passed to
CGI scripts and SSI pages.</li>
-
+
<li>A special case are HTTP headers which are passed to CGI
scripts and the like via environment variables (see below).
They are converted to uppercase and only dashes are replaced with
<p>When set, <module>mod_cache</module> will not save an otherwise
cacheable response. This environment variable does not influence
- whether a response already in the cache will be served for the current
+ whether a response already in the cache will be served for the current
request.</p>
</section>
<section id="fixheader">
<title>Passing broken headers to CGI scripts</title>
-
+
<p>Starting with version 2.4, Apache is more strict about how HTTP
headers are converted to environment variables in <module>mod_cgi
</module> and other modules: Previously any invalid characters
for some potential cross-site-scripting attacks via header injection
(see <a href="http://events.ccc.de/congress/2007/Fahrplan/events/2212.en.html">
Unusual Web Bugs</a>, slide 19/20).</p>
-
+
<p>If you have to support a client which sends broken headers and
which can't be fixed, a simple workaround involving <module>mod_setenvif
</module> and <module>mod_header</module> allows you to still accept
these headers:</p>
-
+
<example>
# <br />
# The following works around a client sending a broken Accept_Encoding<br />
SetEnvIfNoCase ^Accept.Encoding$ ^(.*)$ fix_accept_encoding=$1<br />
RequestHeader set Accept-Encoding %{fix_accept_encoding}e env=fix_accept_encoding
</example>
-
+
</section>
<section id="misbehaving">
required on the request body. For example, the <module>mod_deflate</module>
module might be used to provide a general compression service, or an image
transformation filter might be turned into an image transformation service.</p>
-
+
</section>
-
+
<section id="using">
<title>Using Filters</title>
<p>There are two ways to use filtering: Simple and Dynamic.
href="howto/auth.html">Authentication, Authorization, and Access
Control</a>
</dd>
-
+
<dt><a name="algorithm" id="algorithm">Algorithm</a></dt>
<dd>An unambiguous formula or set of rules for solving a problem in a finite
number of steps. Algorithms for encryption are usually called
<dfn>Ciphers</dfn>.
</dd>
-
+
<dt><a name="apacheextensiontool" id="apacheextensiontool">APache
eXtension Tool</a> <a name="apxs" id="apxs">(apxs)</a></dt>
<dd>A perl script that aids in compiling <glossary
channels over HTTP. It can be used to encapsulate other protocols, such as
the SSL protocol.
</dd>
-
+
<dt><a name="context" id="context">Context</a></dt>
<dd>An area in the <glossary ref="configurationfile">configuration
files</glossary> where certain types of <glossary
<em>Certificate</em>.<br />
See: <a href="ssl/">SSL/TLS Encryption</a>
</dd>
-
+
<dt><a name="directive" id="directive">Directive</a></dt>
<dd>A configuration command that controls one or more aspects of Apache's
behavior. Directives are placed in the <glossary
See: <a href="filter.html">Filters</a>
</dd>
- <dt><a name="fully-qualifieddomain-name"
+ <dt><a name="fully-qualifieddomain-name"
id="fully-qualifieddomain-name">Fully-Qualified Domain-Name</a>
<a name="fqdn" id="fqdn">(FQDN)</a></dt>
<dd>The unique name of a network entity, consisting of a hostname and a
domain name that can resolve to an IP address. For example,
<code>www</code> is a hostname, <code>example.com</code> is a domain name,
and <code>www.example.com</code> is a fully-qualified domain name.
- </dd>
-
+ </dd>
+
<dt><a name="handler" id="handler">Handler</a></dt>
<dd>An internal Apache representation of the action to be performed when a
file is called. Generally, files have implicit handlers, based on the file
<dd>The part of the <glossary ref="http">HTTP</glossary> request and
response that is sent before the actual content, and that contains
meta-information describing the content.
- </dd>
-
- <dt><a name="htaccess" id="htaccess">.htaccess</a></dt>
+ </dd>
+
+ <dt><a name="htaccess" id="htaccess">.htaccess</a></dt>
<dd>A <glossary ref="configurationfile">configuration file</glossary> that
is placed inside the web tree and applies configuration <glossary
ref="directive">directives</glossary> to the directory where it is
communication mechanism on the World Wide Web. This is actually just HTTP
over <glossary ref="ssl">SSL</glossary>.<br />
See: <a href="ssl/">SSL/TLS Encryption</a>
- </dd>
+ </dd>
<dt><a name="method" id="method">Method</a></dt>
<dd>In the context of <glossary ref="http">HTTP</glossary>, an action to
perform on a resource, specified on the request line by the client. Some
of the methods available in HTTP are <code>GET</code>, <code>POST</code>,
and <code>PUT</code>.
- </dd>
-
+ </dd>
+
<dt><a name="messagedigest" id="messagedigest">Message Digest</a></dt>
<dd>A hash of a message, which can be used to verify that the contents of
the message have not been altered in transit.<br />
sign outgoing ones.<br />
See: <a href="ssl/">SSL/TLS Encryption</a>
</dd>
-
+
<dt><a name="proxy" id="proxy">Proxy</a></dt>
<dd>An intermediate server that sits between the client and the <em>origin
server</em>. It accepts requests from clients, transmits those requests
as if it is an <em>origin server</em>. This is useful to hide the real
origin server from the client for security reasons, or to load balance.
</dd>
-
+
<dt><a name="securesocketslayer" id="securesocketslayer">Secure Sockets
Layer</a> <a name="ssl" id="ssl">(SSL)</a></dt>
<dd>A protocol created by Netscape Communications Corporation for general
Extensions</a>.)</p>
<p>Handlers can either be built into the server or included in
- a module, or they can be added with the <directive
+ a module, or they can be added with the <directive
module="mod_actions">Action</directive> directive. The
built-in handlers in the standard distribution are as
follows:</p>
<p>Access control can be done by several different modules. The most
important of these are <module>mod_authz_core</module> and
- <module>mod_authz_host</module>. Also discussed in this document
+ <module>mod_authz_host</module>. Also discussed in this document
is access control using <module>mod_rewrite</module>.</p>
</section>
<note type="warning"><p>
The <directive module="mod_access_compat">Allow</directive>,
- <directive module="mod_access_compat">Deny</directive>, and
+ <directive module="mod_access_compat">Deny</directive>, and
<directive module="mod_access_compat">Order</directive> directives,
provided by <module>mod_access_compat</module>, are deprecated and
will go away in a future version. You should avoid using them, and
Require ip <var>ip.address</var>
</example>
- <p>In the first form, <var>address</var> is a fully qualified
- domain name (or a partial domain name); you may provide multiple
+ <p>In the first form, <var>address</var> is a fully qualified
+ domain name (or a partial domain name); you may provide multiple
addresses or domain names, if desired.</p>
<p>In the second form, <var>ip.address</var> is an IP address, a
<section id="scriptalias">
<title>ScriptAlias</title>
- <p>The
+ <p>The
<directive module="mod_alias">ScriptAlias</directive>
directive tells Apache that a particular directory is set
<p>For example, if the URL
<code>http://www.example.com/cgi-bin/test.pl</code>
- is requested, Apache will attempt to execute the file
+ is requested, Apache will attempt to execute the file
<code>/usr/local/apache2/cgi-bin/test.pl</code>
and return the output. Of course, the file will have to
exist, and be executable, and return output in a particular
use CGI programs. However, if the proper security precautions are
taken, there is no reason why CGI programs cannot be run from
arbitrary directories. For example, you may wish to let users
- have web content in their home directories with the
+ have web content in their home directories with the
<directive module="mod_userdir">UserDir</directive> directive.
If they want to have their own CGI programs, but don't have access to
the main <code>cgi-bin</code> directory, they will need to be able to
module="mod_mime">AddHandler</directive> or <directive
module="core">SetHandler</directive> directive. Second,
<code>ExecCGI</code> must be specified in the <directive
- module="core">Options</directive> directive.</p>
+ module="core">Options</directive> directive.</p>
</section>
<section id="options">
<p>The following is an example CGI program that prints one
line to your browser. Type in the following, save it to a
- file called <code>first.pl</code>, and put it in your
+ file called <code>first.pl</code>, and put it in your
<code>cgi-bin</code> directory.</p>
<example>
http://www.example.com/cgi-bin/first.pl
</example>
- <p>or wherever you put your file, you will see the one line
+ <p>or wherever you put your file, you will see the one line
<code>Hello, World.</code> appear in your browser window.
It's not very exciting, but once you get that working, you'll
have a good chance of getting just about anything working.</p>
<dt>The source code of your CGI program or a "POST Method Not
Allowed" message</dt>
<dd>That means that you have not properly configured Apache
- to process your CGI program. Reread the section on
+ to process your CGI program. Reread the section on
<a href="#configuring">configuring
Apache</a> and try to find what you missed.</dd>
<a href="#permissions">file permissions</a>.</dd>
<dt>A message saying "Internal Server Error"</dt>
- <dd>If you check the
+ <dd>If you check the
<a href="#errorlogs">Apache error log</a>, you will probably
find that it says "Premature end of
script headers", possibly along with an error message
assure that those variables are passed by Apache.</p>
<p>When you miss HTTP headers from the environment, make
- sure they are formatted according to
+ sure they are formatted according to
<a href="http://tools.ietf.org/html/rfc2616">RFC 2616</a>,
- section 4.2: Header names must start with a letter,
+ section 4.2: Header names must start with a letter,
followed only by letters, numbers or hyphen. Any header
violating this rule will be dropped silently.</p>
(where the computer searches for the actual file
implementing a command when you type it), your username, your
terminal type, and so on. For a full list of your normal,
- every day environment variables, type
+ every day environment variables, type
<code>env</code> at a command prompt.</p>
<p>During the CGI transaction, the server and the browser
<p>These variables are available to the CGI programmer, and
are half of the story of the client-server communication. The
- complete list of required variables is at
+ complete list of required variables is at
<a href="http://www.ietf.org/rfc/rfc3875">Common Gateway
Interface RFC</a>.</p>
<p>This simple Perl CGI program will display all of the
environment variables that are being passed around. Two
- similar programs are included in the
+ similar programs are included in the
<code>cgi-bin</code>
directory of the Apache distribution. Note that some
variables are required, while others are optional, so you may
see some variables listed that were not in the official list.
- In addition, Apache provides many different ways for you to
+ In addition, Apache provides many different ways for you to
<a href="../env.html">add your own environment variables</a>
to the basic ones provided by default.</p>
<p>Other communication between the server and the client
happens over standard input (<code>STDIN</code>) and standard
- output (<code>STDOUT</code>). In normal everyday context,
- <code>STDIN</code> means the keyboard, or a file that a
+ output (<code>STDOUT</code>). In normal everyday context,
+ <code>STDIN</code> means the keyboard, or a file that a
program is given to act on, and <code>STDOUT</code>
- usually means the console or screen.</p>
+ usually means the console or screen.</p>
<p>When you <code>POST</code> a web form to a CGI program,
the data in that form is bundled up into a special format
<p>You'll sometimes also see this type of string appended to
a URL. When that is done, the server puts that string
- into the environment variable called
+ into the environment variable called
<code>QUERY_STRING</code>. That's called a <code>GET</code>
request. Your HTML form specifies whether a <code>GET</code>
- or a <code>POST</code> is used to deliver the data, by setting the
+ or a <code>POST</code> is used to deliver the data, by setting the
<code>METHOD</code> attribute in the <code>FORM</code> tag.</p>
<p>Your program is then responsible for splitting that string
set of functionality, which is all you need in most programs.</p>
<p>If you're writing CGI programs in C, there are a variety of
- options. One of these is the <code>CGIC</code> library, from
+ options. One of these is the <code>CGIC</code> library, from
<a href="http://www.boutell.com/cgic/"
>http://www.boutell.com/cgic/</a>.</p>
</section>
<section id="moreinfo">
<title>For more information</title>
- <p>The current CGI specification is available in the
+ <p>The current CGI specification is available in the
<a href="http://www.ietf.org/rfc/rfc3875">Common Gateway
Interface RFC</a>.</p>
<summary>
<p>On systems with multiple users, each user can be permitted to have a
- web site in their home directory using the <directive
+ web site in their home directory using the <directive
module="mod_userdir">UserDir</directive> directive. Visitors
to a URL <code>http://example.com/~username/</code> will get content
out of the home directory of the user "<code>username</code>", out of
UserDir public_html /var/html
</example>
- <p>For the URL <code>http://example.com/~rbowen/file.html</code>,
- Apache will search for <code>~rbowen</code>. If it isn't found,
+ <p>For the URL <code>http://example.com/~rbowen/file.html</code>,
+ Apache will search for <code>~rbowen</code>. If it isn't found,
Apache will search for <code>rbowen</code> in <code>/var/html</code>. If
- found, the above URL will then be translated to the file path
+ found, the above URL will then be translated to the file path
<code>/var/html/rbowen/file.html</code></p>
</section>
-
+
<section id="redirect">
<title>Redirecting to external URLs</title>
<p>The <directive module="mod_userdir">UserDir</directive> directive can be
used to redirect user directory requests to external URLs.</p>
-
+
<example>
UserDir http://example.org/users/*/
</example>
-
+
<p>The above example will redirect a request for
<code>http://example.com/~bob/abc.html</code> to
<code>http://example.org/users/bob/abc.html</code>.</p>
</section>
<section id="enable">
- <title>Restricting what users are permitted to use this
+ <title>Restricting what users are permitted to use this
feature</title>
<p>Using the syntax shown in the UserDir documentation, you can restrict
order to give it a <code>.shtml</code> extension, so that those
directives would be executed.</p>
- <p>The other method is to use the <directive
+ <p>The other method is to use the <directive
module="mod_include">XBitHack</directive> directive:</p>
<example>
XBitHack on
see people recommending that you just tell Apache to parse all
<code>.html</code> files for SSI, so that you don't have to
mess with <code>.shtml</code> file names. These folks have
- perhaps not heard about <directive
+ perhaps not heard about <directive
module="mod_include">XBitHack</directive>. The thing to
keep in mind is that, by doing this, you're requiring that
Apache read through every single file that it sends out to
only at the date of the originally requested file, ignoring
the modification date of any included files.</li>
- <li>Use the directives provided by
+ <li>Use the directives provided by
<module>mod_expires</module> to set an explicit expiration
time on your files, thereby letting browsers and proxies
know that it is acceptable to cache them.</li>
discussed above (like <code>LAST_MODIFIED</code>, for example) to
give values to your variables. You will specify that something is
a variable, rather than a literal string, by using the dollar sign
- ($) before the name of the variable.</p>
+ ($) before the name of the variable.</p>
<example> <!--#set var="modified" value="$LAST_MODIFIED" -->
</example>
<page href="expr.html">Expression parser</page>
<page href="programs/">Server and Supporting Programs</page>
<page href="glossary.html">Glossary</page>
-</category>
+</category>
<category id="usersguide"><title>Users' Guide</title>
<page href="bind.html">Binding to Addresses and Ports</page>
<dd>For some of the support scripts like <program>
apxs</program> or <program>dbmmanage</program> (which are
written in Perl) the Perl 5 interpreter is required (versions
- 5.003 or newer are sufficient). If you have multiple Perl
- interpreters (for example, a systemwide install of Perl 4, and
- your own install of Perl 5), you are advised to use the
- <code>--with-perl</code> option (see below) to make sure the
+ 5.003 or newer are sufficient). If you have multiple Perl
+ interpreters (for example, a systemwide install of Perl 4, and
+ your own install of Perl 5), you are advised to use the
+ <code>--with-perl</code> option (see below) to make sure the
correct one is used by <program>configure</program>.
- If no Perl 5 interpreter is found by the
- <program>configure</program> script, you will not be able to use
- the affected support scripts. Of course, you will still be able to
+ If no Perl 5 interpreter is found by the
+ <program>configure</program> script, you will not be able to use
+ the affected support scripts. Of course, you will still be able to
build and use Apache httpd.</dd>
</dl>
</section>
<p>Please be patient here, since a base configuration takes
several minutes to compile and the time will vary widely
depending on your hardware and the number of modules that you
- have enabled.</p>
+ have enabled.</p>
</section>
<section id="install"><title>Install</title>
<example>$ vi <em>PREFIX</em>/conf/httpd.conf</example>
- <p>Have a look at the Apache manual under
+ <p>Have a look at the Apache manual under
<code><em>PREFIX</em>/docs/manual/</code> or consult <a
href="http://httpd.apache.org/docs/&httpd.docs;/"
>http://httpd.apache.org/docs/&httpd.docs;/</a> for the most recent
<summary>
<p>In order to effectively manage a web server, it is necessary
to get feedback about the activity and performance of the
- server as well as any problems that may be occurring. The Apache HTTP Server
+ server as well as any problems that may be occurring. The Apache HTTP Server
provides very comprehensive and flexible logging
capabilities. This document describes how to configure its
logging capabilities, and how to understand what the logs
<p>The format of the error log is defined by the <directive
module="core">ErrorLogFormat</directive> directive, with which you
- can customize what values are logged. A default is format defined
+ can customize what values are logged. A default is format defined
if you don't specify one. A typical log message follows:</p>
<example>
- [Fri Sep 09 10:42:29.902022 2011] [core:error] [pid 35708:tid 4328636416]
+ [Fri Sep 09 10:42:29.902022 2011] [core:error] [pid 35708:tid 4328636416]
[client 72.15.99.187] File does not exist: /usr/local/apache2/htdocs/favicon.ico
</example>
server. The location and content of the access log are
controlled by the <directive module="mod_log_config">CustomLog</directive>
directive. The <directive module="mod_log_config">LogFormat</directive>
- directive can be used to simplify the selection of
+ directive can be used to simplify the selection of
the contents of the logs. This section describes how to configure the server
to record information in the access log.</p>
<dd>
The time that the request was received.
- The format is:
+ The format is:
<p class="indent">
<code>[day/month/year:hour:minute:second zone]<br />
<title>Multiple Access Logs</title>
<p>Multiple access logs can be created simply by specifying
- multiple <directive module="mod_log_config">CustomLog</directive>
+ multiple <directive module="mod_log_config">CustomLog</directive>
directives in the configuration
file. For example, the following directives will create three
access logs. The first contains the basic CLF information,
client request. This is easily accomplished with the help of <a
href="env.html">environment variables</a>. First, an
environment variable must be set to indicate that the request
- meets certain conditions. This is usually accomplished with
+ meets certain conditions. This is usually accomplished with
<directive module="mod_setenvif">SetEnvIf</directive>. Then the
<code>env=</code> clause of the <directive
module="mod_log_config">CustomLog</directive> directive is used to
hosts</a>, there are several options for dealing with log
files. First, it is possible to use logs exactly as in a
single-host server. Simply by placing the logging directives
- outside the <directive module="core"
+ outside the <directive module="core"
type="section">VirtualHost</directive> sections in the
main server context, it is possible to log all requests in the
same access log and error log. This technique does not allow
for easy collection of statistics on individual virtual
hosts.</p>
- <p>If <directive module="mod_log_config">CustomLog</directive>
+ <p>If <directive module="mod_log_config">CustomLog</directive>
or <directive module="core">ErrorLog</directive>
directives are placed inside a
<directive module="core" type="section">VirtualHost</directive>
terminating the daemon by sending signals to the parent
process; on Windows, use the -k command line option instead.
For more information see the <a href="stopping.html">Stopping
- and Restarting</a> page.</p>
+ and Restarting</a> page.</p>
</section>
<section id="scriptlog">
<manualpage metafile="password_encryptions.xml.meta">
<parentdocument href="./">Miscellaneous Documentation</parentdocument>
-
+
<title>Password Formats</title>
-
+
<summary>
<p>Notes about the password encryption formats generated and understood by
Apache.</p>
</summary>
-
+
<section id="basic"><title>Basic Authentication</title>
<p>There are four formats that Apache recognizes for basic-authentication
passwords. Note that not all formats work on every platform:</p>
-
+
<dl>
<dt>PLAIN TEXT (i.e. <em>unencrypted</em>)</dt>
<dd>Windows & Netware only.</dd>
-
+
<dt>CRYPT</dt>
<dd>Unix only. Uses the traditional Unix <code>crypt(3)</code> function
with a randomly-generated 32-bit salt (only 12 bits used) and the first 8
characters of the password.</dd>
-
+
<dt>SHA1</dt>
<dd>"{SHA}" + Base64-encoded SHA-1 digest of the password.</dd>
-
+
<dt>MD5</dt>
<dd>"$apr1$" + the result of an Apache-specific algorithm using an
iterated (1,000 times) MD5 digest of various combinations of a
<a href="http://svn.apache.org/viewvc/apr/apr/trunk/crypto/apr_md5.c?view=markup">apr_md5.c</a>
for the details of the algorithm.</dd>
</dl>
-
+
<section><title>Generating values with htpasswd</title>
-
+
<example><title>MD5</title>
$ htpasswd -nbm myName myPassword<br />
myName:$apr1$r31.....$HqJZimcKQFAMYayBlzkrA/
</example>
-
+
<example><title>SHA1</title>
$ htpasswd -nbs myName myPassword<br />
myName:{SHA}VBPuJHI7uixaa6LQGWx4s+5GKNE=
</example>
-
+
<example><title>CRYPT</title>
$ htpasswd -nbd myName myPassword<br />
myName:rqXexS6ZhobKA
</example>
-
+
</section>
-
+
<section>
<title>Generating CRYPT and MD5 values with the OpenSSL
command-line program</title>
-
+
<p>OpenSSL knows the Apache-specific MD5 algorithm.</p>
-
+
<example><title>MD5</title>
$ openssl passwd -apr1 myPassword<br />
$apr1$qHDFfhPC$nITSVHgYbDAK1Y0acGRnY0
qQ5vTYO3c8dsU
</example>
</section>
-
+
<section>
<title>Validating CRYPT or MD5 passwords with the OpenSSL command
line program</title>
<p>The salt for a CRYPT password is the first two characters (converted to
a binary value). To validate <code>myPassword</code> against
<code>rqXexS6ZhobKA</code></p>
-
+
<example><title>CRYPT</title>
$ openssl passwd -crypt -salt rq myPassword<br />
Warning: truncating password to 8 characters<br />
rqXexS6ZhobKA
</example>
-
+
<p>Note that using <code>myPasswo</code> instead of
<code>myPassword</code> will produce the same result because only the
first 8 characters of CRYPT passwords are considered.</p>
-
+
<p>The salt for an MD5 password is between <code>$apr1$</code> and the
following <code>$</code> (as a Base64-encoded binary value - max 8 chars).
To validate <code>myPassword</code> against
<code>$apr1$r31.....$HqJZimcKQFAMYayBlzkrA/</code></p>
-
+
<example><title>MD5</title>
$ openssl passwd -apr1 -salt r31..... myPassword<br />
$apr1$r31.....$HqJZimcKQFAMYayBlzkrA/
</example>
</section>
-
+
<section><title>Database password fields for mod_dbd</title>
<p>The SHA1 variant is probably the most useful format for DBD
authentication. Since the SHA1 and Base64 functions are commonly
available, other software can populate a database with encrypted passwords
that are usable by Apache basic authentication.</p>
-
+
<p>To create Apache SHA1-variant basic-authentication passwords in various
languages:</p>
-
+
<example><title>PHP</title>
'{SHA}' . base64_encode(sha1($password, TRUE))
</example>
-
+
<example><title>Java</title>
"{SHA}" + new sun.misc.BASE64Encoder().encode(java.security.MessageDigest.getInstance("SHA1").digest(password.getBytes()))
</example>
-
+
<example><title>ColdFusion</title>
"{SHA}" & ToBase64(BinaryDecode(Hash(password, "SHA1"), "Hex"))
</example>
-
+
<example><title>Ruby</title>
require 'digest/sha1'<br />
require 'base64'<br />
'{SHA}' + Base64.encode64(Digest::SHA1.digest(password))
</example>
-
+
<example><title>C or C++</title>
Use the APR function: apr_sha1_base64
</example>
-
+
<example>
<title>PostgreSQL (with the contrib/pgcrypto functions
installed)</title>
'{SHA}'||encode(digest(password,'sha1'),'base64')
</example>
</section>
-
+
</section>
-
+
<section id="digest"><title>Digest Authentication</title>
<p>Apache recognizes one format for
digest-authentication passwords - the MD5 hash of the string
digits. <code>realm</code> is the Authorization Realm argument to the
<directive module="mod_authn_core">AuthName</directive> directive in
httpd.conf.</p>
-
+
<section><title>Database password fields for mod_dbd</title>
-
+
<p>Since the MD5 function is commonly available, other software can
populate a database with encrypted passwords that are usable by Apache
digest authentication.</p>
-
+
<p>To create Apache digest-authentication passwords in various
languages:</p>
-
+
<example><title>PHP</title>
md5($user . ':' . $realm . ':' .$password)
</example>
-
+
<example><title>Java</title>
byte b[] = java.security.MessageDigest.getInstance("MD5").digest( (user + ":" + realm + ":" + password ).getBytes());<br />
java.math.BigInteger bi = new java.math.BigInteger(1, b);<br />
</indent>
// String s is the encrypted password
</example>
-
+
<example><title>ColdFusion</title>
LCase(Hash( (user & ":" & realm & ":" & password) , "MD5"))
</example>
-
+
<example><title>Ruby</title>
require 'digest/md5'<br />
Digest::MD5.hexdigest(user + ':' + realm + ':' + password)
</example>
-
+
<example>
<title>PostgreSQL (with the contrib/pgcrypto functions installed)</title>
encode(digest( user || ':' || realm || ':' || password , 'md5'), 'hex')
</example>
-
+
</section>
</section>
-
+
</manualpage>
directives.</p>
<p>The <directive module="core">Mutex</directive> directive can
- be used to change the mutex implementation of the
+ be used to change the mutex implementation of the
<code>mpm-accept</code> mutex at run-time. Special considerations
- for different mutex implementations are documented with that
+ for different mutex implementations are documented with that
directive.</p>
<p>Another solution that has been considered but never
<parentdocument href="./">Miscellaneous Documentation</parentdocument>
<title>Relevant Standards</title>
-
+
<summary>
<p>This page documents all the relevant standards that the
Apache HTTP Server follows, along with brief descriptions.</p>
</note>
</summary>
-
+
<section id="http_recommendations"><title>HTTP Recommendations</title>
<p>Regardless of what modules are compiled and used, Apache as a
moot.</p>
<ul>
-
+
<li>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 <code>libkse</code> (see <code>man libmap.conf</code>).</li>
<modulesynopsis metafile="mod_access_compat.xml.meta">
-<name>mod_access_compat</name>
+<name>mod_access_compat</name>
<description>Group authorizations based on host (name or IP
address)</description>
<status>Extension</status>
<sourcefile>mod_access_compat.c</sourcefile>
<identifier>access_compat_module</identifier>
-<compatibility>Available in Apache HTTP Server 2.3 as a compatibility module with
+<compatibility>Available in Apache HTTP Server 2.3 as a compatibility module with
previous versions of Apache httpd 2.x. The directives provided by this module
-have been deprecated by the new authz refactoring. Please see
+have been deprecated by the new authz refactoring. Please see
<module>mod_authz_host</module></compatibility>
<summary>
<note type="warning"><title>Note</title>
<p>The directives provided by <module>mod_access_compat</module> have
- been deprecated by the new authz refactoring. Please see
+ been deprecated by the new authz refactoring. Please see
<module>mod_authz_host</module>.</p>
</note>
href="../env.html">environment variable</a>. When <code>Allow from
env=<var>env-variable</var></code> is specified, then the request is
allowed access if the environment variable <var>env-variable</var>
- exists. When <code>Allow from env=!<var>env-variable</var></code> is
- specified, then the request is allowed access if the environment
+ exists. When <code>Allow from env=!<var>env-variable</var></code> is
+ specified, then the request is allowed access if the environment
variable <var>env-variable</var> doesn't exist.
The server provides the ability to set environment
variables in a flexible way based on characteristics of the client
<example>
<Directory /var/www/private><br />
- Require valid-user<br />
+ Require valid-user<br />
</Directory><br />
<br />
<Directory /var/www/private/public><br />
<modulesynopsis metafile="mod_actions.xml.meta">
-<name>mod_actions</name>
+<name>mod_actions</name>
<description>This module provides for executing CGI scripts based on
media type or request method.</description>
</example>
<p>In this example, requests for files with a file extension of
- <code>.xyz</code> are handled by the specified cgi script
+ <code>.xyz</code> are handled by the specified cgi script
<code>/cgi-bin/program.cgi</code>.</p>
<p>The optional <code>virtual</code> modifier turns off the check
module="mod_alias">ScriptAlias</directive> or <directive
module="mod_mime">AddHandler</directive>. The URL and
file path of the requested document is sent using the standard CGI
- <code>PATH_INFO</code> and <code>PATH_TRANSLATED</code> environment
+ <code>PATH_INFO</code> and <code>PATH_TRANSLATED</code> environment
variables.</p>
<note>
effects.
</note>
- <p>Note that the <directive>Script</directive> command defines default
+ <p>Note that the <directive>Script</directive> command defines default
actions only. If a CGI script is called, or some other resource that is
capable of handling the requested method internally, it will do
- so. Also note that <directive>Script</directive> with a method of
+ so. Also note that <directive>Script</directive> with a method of
<code>GET</code> will only be called if there are query arguments present
(<em>e.g.</em>, foo.html?hi). Otherwise, the request will
proceed normally.</p>
regular expression to match the entire request URI from beginning
to end, and to use substitution on the right side.</p>
- <p>In other words, just changing
+ <p>In other words, just changing
<directive module="mod_alias">Alias</directive> to
<directive module="mod_alias">AliasMatch</directive> will not
have the same effect. At a minimum, you need to
<p>The old <em>URL-path</em> is a case-sensitive (%-decoded) path
beginning with a slash. A relative path is not allowed.</p>
-
- <p>The new <em>URL</em> may be either an absolute URL beginning
+
+ <p>The new <em>URL</em> may be either an absolute URL beginning
with a scheme and hostname, or a URL-path beginning with a slash.
In this latter case the scheme and hostname of the current server will
be added.</p>
<code>http://foo2.example.com/service/foo.txt</code>
instead. This includes requests with <code>GET</code> parameters, such as
<code>http://example.com/service/foo.pl?q=23&a=42</code>,
- it will be redirected to
+ it will be redirected to
<code>http://foo2.example.com/service/foo.pl?q=23&a=42</code>.
Note that <code>POST</code>s will be discarded.<br />
Only complete path segments are matched, so the above
<p><directive>ScriptAlias</directive> can also be used in conjunction with
a script or handler you have. For example:</p>
-
+
<example>
ScriptAlias /cgi-bin/ /web/cgi-handler.pl
</example>
-
+
<p>In this scenario all files requested in <code>/cgi-bin/</code> will be
- handled by the file you have configured, this allows you to use your own custom
- handler. You may want to use this as a wrapper for CGI so that you can add
+ handled by the file you have configured, this allows you to use your own custom
+ handler. You may want to use this as a wrapper for CGI so that you can add
content, or some other bespoke action.</p>
<note type="warning">It is safer to avoid placing CGI scripts under the
-<?xml version="1.0"?>
+<?xml version="1.0"?>
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
-<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
<!-- $LastChangedRevision$ -->
<!--
in order for it to rebuild correctly.
-->
-
-<!--
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
+
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
- The ASF licenses this file to You under the Apache License, Version 2.0
+ The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
limitations under the License.
-->
-<modulesynopsis metafile="mod_allowmethods.xml.meta">
+<modulesynopsis metafile="mod_allowmethods.xml.meta">
<name>mod_allowmethods</name>
<description>Easily restrict what HTTP methods can be used on the server</description>
<status>Experimental</status>
<directivesynopsis>
<name>AllowMethods</name>
<description>Restrict access to the listed HTTP methods</description>
-<syntax>AllowMethods reset|<em>HTTP-method</em>
+<syntax>AllowMethods reset|<em>HTTP-method</em>
[<em>HTTP-method</em>]...</syntax>
<default>AllowMethods reset</default>
<contextlist><context>directory</context></contextlist>
<override>AuthConfig</override>
<usage>
- <p>The <directive>AuthBasicProvider</directive> directive sets
+ <p>The <directive>AuthBasicProvider</directive> directive sets
which provider is used to authenticate the users for this location.
The default <code>file</code> provider is implemented
by the <module>mod_authn_file</module> module. Make sure
</example>
<p> Providers are queried in order until a provider finds a match
- for the requested username, at which point this sole provider will
+ for the requested username, at which point this sole provider will
attempt to check the password. A failure to verify the password does
not result in control being passed on to subsequent providers.</p>
<section id="using"><title>Using Digest Authentication</title>
- <p>To use MD5 Digest authentication, simply
+ <p>To use MD5 Digest authentication, simply
change the normal <code>AuthType Basic</code> and
<directive module="mod_auth_basic">AuthBasicProvider</directive>
to <code>AuthType Digest</code> and
<directive module="mod_auth_digest">AuthDigestProvider</directive>,
- when setting up authentication, then add a
+ when setting up authentication, then add a
<directive module="mod_auth_digest"
>AuthDigestDomain</directive> directive containing at least the root
URI(s) for this protection space.</p>
</Location>
</example>
- <note><title>Note</title>
+ <note><title>Note</title>
<p>Digest authentication is more secure than Basic authentication,
but only works with supporting browsers. As of September 2004, major
browsers that support digest authentication include <a
<override>AuthConfig</override>
<usage>
- <p>The <directive>AuthDigestProvider</directive> directive sets
+ <p>The <directive>AuthDigestProvider</directive> directive sets
which provider is used to authenticate the users for this location.
The default <code>file</code> provider is implemented
by the <module>mod_authn_file</module> module. Make sure
that the chosen provider module is present in the server.</p>
- <p>See <module>mod_authn_dbm</module>, <module>mod_authn_file</module>,
+ <p>See <module>mod_authn_dbm</module>, <module>mod_authn_file</module>,
<module>mod_authn_dbd</module> and <module>mod_authn_socache</module>
for providers.</p>
</usage>
<p>Once the user has been successfully authenticated, the user's login
details will be stored in a session provided by <module>mod_session</module>.
</p>
-
+
</summary>
<seealso><module>mod_session</module></seealso>
<seealso><directive module="mod_authn_core">AuthName</directive></seealso>
<seealso><a href="../howto/auth.html">Authentication howto</a></seealso>
<section id="basicconfig"><title>Basic Configuration</title>
-
+
<p>To protect a particular URL with <module>mod_auth_form</module>, you need to
decide where you will store your <var>session</var>, and you will need to
decide what method you will use to authenticate. In this simple example, the
<module>mod_session_cookie</module>, and authentication will be attempted against
a file using <module>mod_authn_file</module>. If authentication is unsuccessful,
the user will be redirected to the form login page.</p>
-
+
<example><title>Basic example</title>
AuthFormProvider file<br />
AuthUserFile conf/passwd<br />
SessionCookieName session path=/<br />
SessionCryptoPassphrase secret<br />
</example>
-
+
<p>The directive <directive module="mod_authn_core">AuthType</directive> will enable
the <module>mod_auth_form</module> authentication when set to the value <var>form</var>.
The directives <directive module="mod_auth_form">AuthFormProvider</directive> and
<directive module="mod_authn_file">AuthUserFile</directive> specify that usernames
and passwords should be checked against the chosen file.</p>
- <p>The directives <directive module="mod_session">Session</directive>,
+ <p>The directives <directive module="mod_session">Session</directive>,
<directive module="mod_session_cookie">SessionCookieName</directive> and
<directive module="mod_session_crypto">SessionCryptoPassphrase</directive> create an
encrypted session stored within an HTTP cookie on the browser. For more information
dedicated standalone login page for this purpose, or for providing the login
page inline.</p>
</section>
-
+
<section id="standalone"><title>Standalone Login</title>
<p>The login form can be hosted as a standalone page, or can be provided inline on
the same page.</p>
-
+
<p>When configuring the login as a standalone page, unsuccessful authentication
attempts should be redirected to a login form created by the website for this purpose,
using the <directive module="mod_auth_form">AuthFormLoginRequiredLocation</directive>
directive. Typically this login page will contain an HTML form, asking the user to
provide their usename and password.</p>
-
+
<example><title>Example login form</title>
<form method="POST" action="/dologin.html"><br />
Username: <input type="text" name="httpd_username" value="" /><br />
<p>The part that does the actual login is handled by the <var>form-login-handler</var>.
The action of the form should point at this handler, which is configured within
Apache httpd as follows:</p>
-
+
<example><title>Form login handler example</title>
<Location /dologin.html>
<indent>
point to a page explaining to the user that their login attempt was unsuccessful, and they
should try again. The <directive module="mod_auth_form">AuthFormLoginSuccessLocation</directive>
directive specifies the URL the user should be redirected to upon successful login.</p>
-
+
<p>Alternatively, the URL to redirect the user to on success can be embedded within the login
form, as in the example below. As a result, the same <var>form-login-handler</var> can be
reused for different areas of a website.</p>
</section>
<section id="inline"><title>Inline Login</title>
-
+
<note type="warning"><title>Warning</title>
- <p>A risk exists that under certain circumstances, the login form configured
+ <p>A risk exists that under certain circumstances, the login form configured
using inline login may be submitted more than once, revealing login credentials to
the application running underneath. The administrator must ensure that the underlying
application is properly secured to prevent abuse. If in doubt, use the
<directive module="mod_auth_form">AuthFormLoginRequiredLocation</directive> directive,
a <var>HTTP_UNAUTHORIZED</var> status code is returned to the browser indicating to the user
that they are not authorized to view the page.</p>
-
+
<p>To configure inline authentication, the administrator overrides the error document
returned by the <var>HTTP_UNAUTHORIZED</var> status code with a custom error document
containing the login form, as follows:</p>
SessionCookieName session path=/<br />
SessionCryptoPassphrase secret<br />
</example>
-
+
<p>The error document page should contain a login form with an empty action property,
as per the example below. This has the effect of submitting the form to
the original protected URL, without the page having to know what that
<p>One option is to use the <module>mod_include</module> module along with the
<directive module="core">KeptBodySize</directive> directive, along with a suitable
CGI script to embed the variables in the form.</p>
-
+
<p>Another option is to render the login form using a CGI script or other dynamic
technology.</p>
<override>AuthConfig</override>
<usage>
- <p>The <directive>AuthFormProvider</directive> directive sets
+ <p>The <directive>AuthFormProvider</directive> directive sets
which provider is used to authenticate the users for this location.
The default <code>file</code> provider is implemented
by the <module>mod_authn_file</module> module. Make sure
<p>The <directive module="mod_auth_form">AuthFormMethod</directive> directive specifies
the name of an HTML field which, if present, will contain the method of the request to
to submit should login be successful.</p>
-
+
<p>By populating the form with fields described by
- <directive module="mod_auth_form">AuthFormMethod</directive>,
+ <directive module="mod_auth_form">AuthFormMethod</directive>,
<directive module="mod_auth_form">AuthFormMimetype</directive> and
<directive module="mod_auth_form">AuthFormBody</directive>, a website can retry
a request that may have been interrupted by the login screen, or by a session
mimetype of the request to to submit should login be successful.</p>
<p>By populating the form with fields described by
- <directive module="mod_auth_form">AuthFormMethod</directive>,
+ <directive module="mod_auth_form">AuthFormMethod</directive>,
<directive module="mod_auth_form">AuthFormMimetype</directive> and
<directive module="mod_auth_form">AuthFormBody</directive>, a website can retry
a request that may have been interrupted by the login screen, or by a session
to submit should login be successful.</p>
<p>By populating the form with fields described by
- <directive module="mod_auth_form">AuthFormMethod</directive>,
+ <directive module="mod_auth_form">AuthFormMethod</directive>,
<directive module="mod_auth_form">AuthFormMimetype</directive> and
<directive module="mod_auth_form">AuthFormBody</directive>, a website can retry
a request that may have been interrupted by the login screen, or by a session
<usage>
<p>The <directive module="mod_auth_form">AuthFormSize</directive> directive specifies
the maximum size of the body of the request that will be parsed to find the login form.</p>
-
+
<p>If a login request arrives that exceeds this size, the whole request will be aborted
with the HTTP response code <code>HTTP_REQUEST_TOO_LARGE</code>.</p>
<p>If you have populated the form with fields described by
- <directive module="mod_auth_form">AuthFormMethod</directive>,
+ <directive module="mod_auth_form">AuthFormMethod</directive>,
<directive module="mod_auth_form">AuthFormMimetype</directive> and
<directive module="mod_auth_form">AuthFormBody</directive>, you probably want to set this
field to a similar size as the <directive module="core">KeptBodySize</directive>
will be returned with the page specified by the
<directive module="core">ErrorDocument</directive> directive. This directive overrides this
default.</p>
-
+
<p>Use this directive if you have a dedicated login page to redirect users to.</p>
</usage>
specifies the URL to redirect to should the user have logged in successfully. This directive
can be overridden if a form field has been defined containing another URL using the
<directive module="mod_auth_form">AuthFormLocation</directive> directive.</p>
-
+
<p>Use this directive if you have a dedicated login URL, and you have not embedded the
destination page in the login form.</p>
<p>When a URI is accessed that is served by the handler <code>form-logout-handler</code>,
the page specified by this directive will be shown to the end user. For example:</p>
-
+
<example><title>Example</title>
<Location /logout><br />
<indent>
</indent>
</Location>
</example>
-
+
<p>An attempt to access the URI <var>/logout/</var> will result in the user being logged
out, and the page <var>/loggedout.html</var> will be displayed. Make sure that the page
<var>loggedout.html</var> is not password protected, otherwise the page will not be
specifies a passphrase which, if present in the user session, causes Apache httpd to
bypass authentication checks for the given URL. It can be used on high traffic websites
to reduce the load induced on authentication infrastructure.</p>
-
+
<p>The passphrase can be inserted into a user session by adding this directive to the
configuration for the <var>form-login-handler</var>. The <var>form-login-handler</var>
itself will always run the authentication checks, regardless of whether a passphrase
<modulesynopsis metafile="mod_authn_core.xml.meta">
-<name>mod_authn_core</name>
+<name>mod_authn_core</name>
<description>Core Authentication</description>
<status>Base</status>
<sourcefile>mod_authn_core.c</sourcefile>
<compatibility>Available in Apache 2.3 and later</compatibility>
<summary>
- <p>This module provides core authentication capabilities to
- allow or deny access to portions of the web site.
- <module>mod_authn_core</module> provides directives that are
+ <p>This module provides core authentication capabilities to
+ allow or deny access to portions of the web site.
+ <module>mod_authn_core</module> provides directives that are
common to all authentication providers.</p>
</summary>
<section id="authnalias"><title>Creating Authentication Provider Aliases</title>
- <p>Extended authentication providers can be created
- within the configuration file and assigned an alias name. The alias
- providers can then be referenced through the directives
- <directive module="mod_auth_basic">AuthBasicProvider</directive> or
+ <p>Extended authentication providers can be created
+ within the configuration file and assigned an alias name. The alias
+ providers can then be referenced through the directives
+ <directive module="mod_auth_basic">AuthBasicProvider</directive> or
<directive module="mod_auth_digest">AuthDigestProvider</directive> in
the same way as a base authentication provider. Besides the ability
- to create and alias an extended provider, it also allows the same
- extended authentication provider to be reference by multiple
+ to create and alias an extended provider, it also allows the same
+ extended authentication provider to be reference by multiple
locations.</p>
<section id="example"><title>Examples</title>
</Directory><br />
</example>
- <p>The example below creates two different ldap authentication
+ <p>The example below creates two different ldap authentication
provider aliases based on the ldap provider. This allows
a single authenticated location to be serviced by multiple ldap
hosts:</p>
-
+
<example><title>Checking multiple LDAP servers</title>
<AuthnProviderAlias ldap ldap-alias1><br />
<indent>
AuthLDAPURL ldap://other.ldap.host/o=dev?cn<br />
</indent>
</AuthnProviderAlias><br /><br />
-
+
Alias /secure /webpages/secure<br />
<Directory /webpages/secure><br />
<indent>
Order deny,allow<br />
Allow from all<br /><br />
-
+
AuthBasicProvider ldap-other-alias ldap-alias1<br /><br />
-
+
AuthType Basic<br />
AuthName LDAP_Protected_Place<br />
Require valid-user<br />
tree will typically continue to send authentication HTTP headers
or cookies with each request, regardless of whether the server
actually requires authentication for every resource.</note>
-</usage>
+</usage>
<seealso><a href="../howto/auth.html">Authentication, Authorization,
- and Access Control</a></seealso>
+ and Access Control</a></seealso>
</directivesynopsis>
<directivesynopsis type="section">
<usage>
<p><code><AuthnProviderAlias></code> and
<code></AuthnProviderAlias></code> are used to enclose a group of
- authentication directives that can be referenced by the alias name
+ authentication directives that can be referenced by the alias name
using one of the directives <directive module="mod_auth_basic">
AuthBasicProvider</directive> or <directive module="mod_auth_digest">
AuthDigestProvider</directive>.</p>
<seealso><program>htpasswd</program></seealso>
<seealso><program>htdigest</program></seealso>
<seealso><a href="../misc/password_encryptions.html">Password Formats</a></seealso>
-
+
<directivesynopsis>
<name>AuthUserFile</name>
<description>Sets the name of a text file containing the list of users and
-<?xml version="1.0"?>
+<?xml version="1.0"?>
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
<!-- $LastChangedRevision$ -->
is not permitted in <var>.htaccess</var> contexts.</p>
</usage>
</directivesynopsis>
-
+
</modulesynopsis>
<summary>
<p>This module provides authentication front-ends such as
- <module>mod_auth_basic</module> to authenticate users through
+ <module>mod_auth_basic</module> to authenticate users through
an ldap directory.</p>
-
+
<p><module>mod_authnz_ldap</module> supports the following features:</p>
<ul>
<ul>
<li>
- <a href="#operation">Operation</a>
+ <a href="#operation">Operation</a>
<ul>
<li><a href="#authenphase">The Authentication
</li>
<li>
- <a href="#requiredirectives">The Require Directives</a>
+ <a href="#requiredirectives">The Require Directives</a>
<ul>
<li><a href="#requser">Require ldap-user</a></li>
<li><a href="#activedirectory">Using Active Directory</a></li>
<li>
<a href="#frontpage">Using Microsoft FrontPage with
- <module>mod_authnz_ldap</module></a>
+ <module>mod_authnz_ldap</module></a>
<ul>
<li><a href="#howitworks">How It Works</a></li>
<p>There are two phases in granting access to a user. The first
phase is authentication, in which the <module>mod_authnz_ldap</module>
- authentication provider verifies that the user's credentials are valid.
+ authentication provider verifies that the user's credentials are valid.
This is also called the <em>search/bind</em> phase. The second phase is
authorization, in which <module>mod_authnz_ldap</module> determines
if the authenticated user is allowed access to the resource in
<p><module>mod_authnz_ldap</module> registers both an authn_ldap authentication
provider and an authz_ldap authorization handler. The authn_ldap
- authentication provider can be enabled through the
- <directive module="mod_auth_basic">AuthBasicProvider</directive> directive
- using the <code>ldap</code> value. The authz_ldap handler extends the
+ authentication provider can be enabled through the
+ <directive module="mod_auth_basic">AuthBasicProvider</directive> directive
+ using the <code>ldap</code> value. The authz_ldap handler extends the
<directive module="mod_authz_core">Require</directive> directive's authorization types
- by adding <code>ldap-user</code>, <code>ldap-dn</code> and <code>ldap-group</code>
+ by adding <code>ldap-user</code>, <code>ldap-dn</code> and <code>ldap-group</code>
values.</p>
<section id="authenphase"><title>The Authentication
one of its sub-groups.</li>
<li>Grant access if there is a <a href="#reqattribute">
- <code>Require ldap-attribute</code></a>
+ <code>Require ldap-attribute</code></a>
directive, and the attribute fetched from the LDAP directory
- matches the given value.</li>
+ matches the given value.</li>
<li>Grant access if there is a <a href="#reqfilter">
- <code>Require ldap-filter</code></a>
+ <code>Require ldap-filter</code></a>
directive, and the search filter successfully finds a single user
- object that matches the dn of the authenticated user.</li>
+ object that matches the dn of the authenticated user.</li>
<li>otherwise, deny or decline access</li>
</ul>
be used which may require loading additional authorization modules.</p>
<ul>
- <li>Grant access to all successfully authenticated users if
- there is a <a href="#requser"><code>Require valid-user</code></a>
+ <li>Grant access to all successfully authenticated users if
+ there is a <a href="#requser"><code>Require valid-user</code></a>
directive. (requires <module>mod_authz_user</module>)</li>
<li>Grant access if there is a <a
href="#reqgroup"><code>Require group</code></a> directive, and
- <module>mod_authz_groupfile</module> has been loaded with the
- <directive module="mod_authz_groupfile">AuthGroupFile</directive>
+ <module>mod_authz_groupfile</module> has been loaded with the
+ <directive module="mod_authz_groupfile">AuthGroupFile</directive>
directive set.</li>
-
+
<li>others...</li>
</ul>
<p>Apache's <directive module="mod_authz_core">Require</directive>
directives are used during the authorization phase to ensure that
- a user is allowed to access a resource. mod_authnz_ldap extends the
- authorization types with <code>ldap-user</code>, <code>ldap-dn</code>,
- <code>ldap-group</code>, <code>ldap-attribute</code> and
- <code>ldap-filter</code>. Other authorization types may also be
+ a user is allowed to access a resource. mod_authnz_ldap extends the
+ authorization types with <code>ldap-user</code>, <code>ldap-dn</code>,
+ <code>ldap-group</code>, <code>ldap-attribute</code> and
+ <code>ldap-filter</code>. Other authorization types may also be
used but may require that additional authorization modules be loaded.</p>
<section id="requser"><title>Require ldap-user</title>
<p>The following directives would allow access for Bob Ellis, Tom Jackson,
Barbara Jensen, Fred User, Allan Jefferson, and Paul Tilley but would not
- allow access for Jim Swenson, or Elliot Rhodes (since they are at a
+ allow access for Jim Swenson, or Elliot Rhodes (since they are at a
sub-group depth of 2):</p>
<example>
Require ldap-group cn=Employees, o-Example<br />
administrator to grant access based on attributes of the authenticated
user in the LDAP directory. If the attribute in the directory
matches the value given in the configuration, access is granted.</p>
-
+
<p>The following directive would grant access to anyone with
the attribute employeeType = active</p>
<example>Require ldap-attribute employeeType=active</example>
<p>Multiple attribute/value pairs can be specified on the same line
- separated by spaces or they can be specified in multiple
- <code>Require ldap-attribute</code> directives. The effect of listing
- multiple attribute/values pairs is an OR operation. Access will be
- granted if any of the listed attribute values match the value of the
- corresponding attribute in the user object. If the value of the
+ separated by spaces or they can be specified in multiple
+ <code>Require ldap-attribute</code> directives. The effect of listing
+ multiple attribute/values pairs is an OR operation. Access will be
+ granted if any of the listed attribute values match the value of the
+ corresponding attribute in the user object. If the value of the
attribute contains a space, only the value must be within double quotes.</p>
<p>The following directive would grant access to anyone with
administrator to grant access based on a complex LDAP search filter.
If the dn returned by the filter search matches the authenticated user
dn, access is granted.</p>
-
+
<p>The following directive would grant access to anyone having a cell phone
and is in the marketing department</p>
<example>Require ldap-filter &(cell=*)(department=marketing)</example>
- <p>The difference between the <code>Require ldap-filter</code> directive and the
- <code>Require ldap-attribute</code> directive is that <code>ldap-filter</code>
- performs a search operation on the LDAP directory using the specified search
- filter rather than a simple attribute comparison. If a simple attribute
- comparison is all that is required, the comparison operation performed by
- <code>ldap-attribute</code> will be faster than the search operation
+ <p>The difference between the <code>Require ldap-filter</code> directive and the
+ <code>Require ldap-attribute</code> directive is that <code>ldap-filter</code>
+ performs a search operation on the LDAP directory using the specified search
+ filter rather than a simple attribute comparison. If a simple attribute
+ comparison is all that is required, the comparison operation performed by
+ <code>ldap-attribute</code> will be faster than the search operation
used by <code>ldap-filter</code> especially within a large directory.</p>
</section>
<ul>
<li>
Grant access to anyone who exists in the LDAP directory,
- using their UID for searches.
+ using their UID for searches.
<example>
AuthLDAPURL "ldap://ldap1.example.com:389/ou=People, o=Example?uid?sub?(objectClass=*)"<br />
Require valid-user
<li>
The next example is the same as above; but with the fields
that have useful defaults omitted. Also, note the use of a
- redundant LDAP server.
+ redundant LDAP server.
<example>AuthLDAPURL "ldap://ldap1.example.com ldap2.example.com/ou=People, o=Example"<br />
Require valid-user
</example>
<strong>must</strong> return exactly one entry. That's why
this approach is not recommended: it's a better idea to
choose an attribute that is guaranteed unique in your
- directory, such as <code>uid</code>.
+ directory, such as <code>uid</code>.
<example>
AuthLDAPURL "ldap://ldap.example.com/ou=People, o=Example?cn"<br />
Require valid-user
<li>
Grant access to anybody in the Administrators group. The
- users must authenticate using their UID.
+ users must authenticate using their UID.
<example>
AuthLDAPURL ldap://ldap.example.com/o=Example?uid<br />
Require ldap-group cn=Administrators, o=Example
carries an alphanumeric pager will have an LDAP attribute
of <code>qpagePagerID</code>. The example will grant access
only to people (authenticated via their UID) who have
- alphanumeric pagers:
+ alphanumeric pagers:
<example>
AuthLDAPURL ldap://ldap.example.com/o=Example?uid??(qpagePagerID=*)<br />
Require valid-user
module="mod_ldap">LDAPTrustedGlobalCert</directive> and <directive
module="mod_ldap">LDAPTrustedMode</directive>.</p>
- <p>An optional second parameter can be added to the
+ <p>An optional second parameter can be added to the
<directive module="mod_authnz_ldap">AuthLDAPURL</directive> to override
the default connection type set by <directive module="mod_ldap">LDAPTrustedMode</directive>.
- This will allow the connection established by an <em>ldap://</em> Url
+ This will allow the connection established by an <em>ldap://</em> Url
to be upgraded to a secure connection on the same port.</p>
</section>
<section id="exposed"><title>Exposing Login Information</title>
<p>when this module performs <em>authentication</em>, ldap attributes specified
- in the <directive module="mod_authnz_ldap">authldapurl</directive>
+ in the <directive module="mod_authnz_ldap">authldapurl</directive>
directive are placed in environment variables with the prefix "AUTHENTICATE_".</p>
<p>when this module performs <em>authorization</em>, ldap attributes specified
- in the <directive module="mod_authnz_ldap">authldapurl</directive>
+ in the <directive module="mod_authnz_ldap">authldapurl</directive>
directive are placed in environment variables with the prefix "AUTHORIZE_".</p>
<p>If the attribute field contains the username, common name
the LDAP directory is considered a valid user, whereas FrontPage
considers only those people in the local user file to be
valid. By substituting the ldap-group with group file authorization,
- Apache is allowed to consult the local user file (which is managed by
+ Apache is allowed to consult the local user file (which is managed by
FrontPage) - instead of LDAP - when handling authorizing the user.</p>
<p>Once directives have been added as specified above,
<module>mod_authn_file</module> and
<module>mod_authz_groupfile</module> in order to
use FrontPage support. This is because Apache will still use
- the <module>mod_authz_groupfile</module> group file for determine
+ the <module>mod_authz_groupfile</module> group file for determine
the extent of a user's access to the FrontPage web.</li>
<li>The directives must be put in the <code>.htaccess</code>
whether LDAP has performed authentication, authorization, or both.</p>
<note><title>Note</title>
- No authorization variables are set when a user is authorized on the basis of
+ No authorization variables are set when a user is authorized on the basis of
<code>Require valid-user</code>.
</note>
</usage>
</contextlist>
<override>AuthConfig</override>
<usage>
- <p>By default, subsequent authentication providers are only queried if a
+ <p>By default, subsequent authentication providers are only queried if a
user cannot be mapped to a DN, but not if the user can be mapped to a DN and their
- password cannot be verified with an LDAP bind.
- If <directive module="mod_authnz_ldap">AuthLDAPBindAuthoritative</directive>
- is set to <em>off</em>, other configured authentication modules will have
- a chance to validate the user if the LDAP bind (with the current user's credentials)
+ password cannot be verified with an LDAP bind.
+ If <directive module="mod_authnz_ldap">AuthLDAPBindAuthoritative</directive>
+ is set to <em>off</em>, other configured authentication modules will have
+ a chance to validate the user if the LDAP bind (with the current user's credentials)
fails for any reason.</p>
- <p> This allows users present in both LDAP and
+ <p> This allows users present in both LDAP and
<directive module="mod_authn_file">AuthUserFile</directive> to authenticate
when the LDAP server is available but the user's account is locked or password
is otherwise unusable.</p>
distinguished name (DN). This directive forces the server to use the verbatim username
and password provided by the incoming user to perform the initial DN
search.</p>
-
+
<p> If the verbatim username can't directly bind, but needs some
cosmetic transformation, see <directive module="mod_authnz_ldap">
AuthLDAPInitialBindPattern</directive>.</p>
-
- <p> This directive should only be used when your LDAP server doesn't
- accept anonymous searches and you cannot use a dedicated
+
+ <p> This directive should only be used when your LDAP server doesn't
+ accept anonymous searches and you cannot use a dedicated
<directive module="mod_authnz_ldap">AuthLDAPBindDN</directive>.
</p>
<p> The regular expression argument is compared against the current basic authentication username.
The substitution argument may contain backreferences, but has no other variable interpolation.</p>
-
- <p> This directive should only be used when your LDAP server doesn't
- accept anonymous searches and you cannot use a dedicated
+
+ <p> This directive should only be used when your LDAP server doesn't
+ accept anonymous searches and you cannot use a dedicated
<directive module="mod_authnz_ldap">AuthLDAPBindDN</directive>.
</p>
has no effect when this module is used exclusively for authorization.
</note>
<note><title>debugging</title>
- The substituted DN is recorded in the environment variable
- <em>LDAP_BINDASUSER</em>. If the regular expression does not match the input,
+ The substituted DN is recorded in the environment variable
+ <em>LDAP_BINDASUSER</em>. If the regular expression does not match the input,
the verbatim username is used.
</note>
</usage>
properly protected. You should only use the <directive
module="mod_authnz_ldap">AuthLDAPBindDN</directive> and <directive
module="mod_authnz_ldap">AuthLDAPBindPassword</directive> if you
- absolutely need them to search the directory.</p>
+ absolutely need them to search the directory.</p>
</usage>
</directivesynopsis>
<usage>
<p>When set, and <module>mod_authnz_ldap</module> has authenticated the
user, LDAP comparisons for authorization use the queried distinguished name (DN)
- and HTTP basic authentication password of the authenticated user instead of
+ and HTTP basic authentication password of the authenticated user instead of
the servers configured credentials.</p>
- <p> The <em>ldap-attribute</em>, <em>ldap-user</em>, and <em>ldap-group</em> (single-level only)
+ <p> The <em>ldap-attribute</em>, <em>ldap-user</em>, and <em>ldap-group</em> (single-level only)
authorization checks use comparisons.</p>
<p>This directive only has effect on the comparisons performed during
nested group processing when <directive module="mod_authnz_ldap">
AuthLDAPSearchAsUser</directive> is also enabled.</p>
-
+
<p> This directive should only be used when your LDAP server doesn't
accept anonymous comparisons and you cannot use a dedicated
<directive module="mod_authnz_ldap">AuthLDAPBindDN</directive>.
<default>none</default>
<contextlist><context>directory</context><context>.htaccess</context>
</contextlist>
-<override>AuthConfig</override>
-
+<override>AuthConfig</override>
+
<usage>
- <p>If this directive is set, the value of the
+ <p>If this directive is set, the value of the
<code>REMOTE_USER</code> environment variable will be set to the
value of the attribute specified. Make sure that this attribute is
included in the list of attributes in the AuthLDAPUrl definition,
<usage>
<p>When set, and <module>mod_authnz_ldap</module> has authenticated the
user, LDAP searches for authorization use the queried distinguished name (DN)
- and HTTP basic authentication password of the authenticated user instead of
+ and HTTP basic authentication password of the authenticated user instead of
the servers configured credentials.</p>
- <p> The <em>ldap-filter</em> and <em>ldap-dn</em> authorization
+ <p> The <em>ldap-filter</em> and <em>ldap-dn</em> authorization
checks use searches.</p>
<p>This directive only has effect on the comparisons performed during
<example>ldap://host:port/basedn?attribute?scope?filter</example>
<p>If you want to specify more than one LDAP URL that Apache should try in turn, the syntax is:</p>
<example>AuthLDAPUrl "ldap://ldap1.example.com ldap2.example.com/dc=..."</example>
-<p><em><strong>Caveat: </strong>If you specify multiple servers, you need to enclose the entire URL string in quotes;
-otherwise you will get an error: "AuthLDAPURL takes one argument, URL to define LDAP connection.." </em>
+<p><em><strong>Caveat: </strong>If you specify multiple servers, you need to enclose the entire URL string in quotes;
+otherwise you will get an error: "AuthLDAPURL takes one argument, URL to define LDAP connection.." </em>
You can of course use search parameters on each of these.</p>
<dl>
specify multiple, redundant LDAP servers, just list all
servers, separated by spaces. <module>mod_authnz_ldap</module>
will try connecting to each server in turn, until it makes a
- successful connection. If multiple ldap servers are specified,
+ successful connection. If multiple ldap servers are specified,
then entire LDAP URL must be encapsulated in double quotes.</p>
<p>Once a connection has been made to a server, that
Jenson</code>, the resulting search filter will be
<code>(&(posixid=*)(cn=Babs Jenson))</code>.</p>
- <p>An optional parameter can be added to allow the LDAP Url to override
+ <p>An optional parameter can be added to allow the LDAP Url to override
the connection type. This parameter can be one of the following:</p>
<dl>
This is the same as <code>ldaps://</code></dd>
<dt>TLS | STARTTLS</dt>
<dd>Establish an upgraded secure connection on the default LDAP port.
- This connection will be initiated on port 389 by default and then
+ This connection will be initiated on port 389 by default and then
upgraded to a secure connection on the same port.</dd>
</dl>
<modulesynopsis metafile="mod_authz_core.xml.meta">
-<name>mod_authz_core</name>
+<name>mod_authz_core</name>
<description>Core Authorization</description>
<status>Base</status>
<sourcefile>mod_authz_core.c</sourcefile>
<summary>
<p>This module provides core authorization capabilities so that
authenticated users can be allowed or denied access to portions
- of the web site. <module>mod_authz_core</module> provides the
+ of the web site. <module>mod_authz_core</module> provides the
functionality to register various authorization providers. It is
usually used in conjunction with an authentication
- provider module such as <module>mod_authn_file</module> and an
+ provider module such as <module>mod_authn_file</module> and an
authorization module such as <module>mod_authz_user</module>. It
- also allows for advanced logic to be applied to the
+ also allows for advanced logic to be applied to the
authorization processing.</p>
</summary>
allows a single authorization location to check group membership within
multiple ldap hosts:
</p>
-
+
<example><title>Example</title>
<AuthzProviderAlias ldap-group ldap-group-alias1 cn=my-group,o=ctx><br />
<indent>
AuthLDAPBindDN cn=youruser,o=ctx<br />
AuthLDAPBindPassword yourpassword<br />
AuthLDAPURL ldap://ldap.host/o=ctx<br />
- </indent>
- </AuthzProviderAlias><br /><br />
+ </indent>
+ </AuthzProviderAlias><br /><br />
<AuthzProviderAlias ldap-group ldap-group-alias2
cn=my-other-group,o=dev><br />
<indent>
AuthLDAPBindDN cn=yourotheruser,o=dev<br />
AuthLDAPBindPassword yourotherpassword<br />
AuthLDAPURL ldap://other.ldap.host/o=dev?cn<br />
- </indent>
+ </indent>
</AuthzProviderAlias><br /><br />
-
+
Alias /secure /webpages/secure<br />
<Directory /webpages/secure><br />
<indent>
Require all granted<br /><br />
-
+
AuthBasicProvider file<br /><br />
-
+
AuthType Basic<br />
AuthName LDAP_Protected_Place<br /><br />
- #implied OR operation<br />
- Require ldap-group-alias1<br />
+ #implied OR operation<br />
+ Require ldap-group-alias1<br />
Require ldap-group-alias2<br />
</indent> </Directory><br />
</example>
</RequireNone>
</indent>
</RequireAll>
- </indent>
+ </indent>
</Directory>
</example>
</section>
<p>The <code>env</code> provider allows access to the server
to be controlled based on the existence of an <a
- href="../env.html">environment variable</a>. When <code>Require
+ href="../env.html">environment variable</a>. When <code>Require
env <var>env-variable</var></code> is specified, then the request is
allowed access if the environment variable <var>env-variable</var>
exists. The server provides the ability to set environment
used to allow access based on such factors as the clients
<code>User-Agent</code> (browser type), <code>Referer</code>, or
other HTTP request header fields.</p>
-
+
<example><title>Example:</title>
SetEnvIf User-Agent ^KnockKnock/2\.0 let_me_in<br />
<Directory /docroot><br />
</indent>
</Directory>
</example>
-
+
<p>In this case, browsers with a user-agent string beginning
with <code>KnockKnock/2.0</code> will be allowed access, and all
others will be denied.</p>
<p>The <code>all</code> provider mimics the functionality the
was previously provided by the 'Allow from all' and 'Deny from all'
- directives. This provider can take one of two arguments which are
- 'granted' or 'denied'. The following examples will grant or deny
+ directives. This provider can take one of two arguments which are
+ 'granted' or 'denied'. The following examples will grant or deny
access to all requests.</p>
<example>
<p>Other authorization modules that implement require options
include <module>mod_authnz_ldap</module>,
- <module>mod_authz_dbm</module>, <module>mod_authz_dbd</module>,
- <module>mod_authz_host</module>,
+ <module>mod_authz_dbm</module>, <module>mod_authz_dbd</module>,
+ <module>mod_authz_host</module>,
<module>mod_authz_owner</module> and <module>mod_ssl</module>.</p>
<p>In most cases, for a complete authentication and authorization
configuration, <directive>Require</directive> must be accompanied by
<directive module="mod_authn_core">AuthName</directive>, <directive
- module="mod_authn_core">AuthType</directive> and
+ module="mod_authn_core">AuthType</directive> and
<directive module="mod_auth_basic">AuthBasicProvider</directive> or
- <directive module="mod_auth_digest">AuthDigestProvider</directive>
- directives, and directives such as
+ <directive module="mod_auth_digest">AuthDigestProvider</directive>
+ directives, and directives such as
<directive module="mod_authn_file">AuthUserFile</directive>
and <directive module="mod_authz_groupfile">AuthGroupFile</directive> (to
define users and groups) in order to work correctly. Example:</p>
</usage>
<seealso><a href="../howto/auth.html">Authentication, Authorization,
- and Access Control</a></seealso>
+ and Access Control</a></seealso>
<seealso><a href="#logic">Authorization Containers</a></seealso>
<seealso><module>mod_authn_core</module></seealso>
<seealso><module>mod_authz_host</module></seealso>
<seealso><a href="#logic">Authorization Containers</a></seealso>
<seealso><a href="../howto/auth.html">Authentication, Authorization,
- and Access Control</a></seealso>
+ and Access Control</a></seealso>
</directivesynopsis>
<seealso><a href="#logic">Authorization Containers</a></seealso>
<seealso><a href="../howto/auth.html">Authentication, Authorization,
- and Access Control</a></seealso>
+ and Access Control</a></seealso>
</directivesynopsis>
<seealso><a href="#logic">Authorization Containers</a></seealso>
<seealso><a href="../howto/auth.html">Authentication, Authorization,
- and Access Control</a></seealso>
+ and Access Control</a></seealso>
</directivesynopsis>
<description>Enclose a group of directives that represent an
extension of a base authorization provider and referenced by the specified
alias</description>
-<syntax><AuthzProviderAlias <var>baseProvider Alias Require-Parameters</var>>
+<syntax><AuthzProviderAlias <var>baseProvider Alias Require-Parameters</var>>
... </AuthzProviderAlias>
</syntax>
<contextlist><context>server config</context>
<example><title>Example:</title>
mygroup: bob joe anne
- </example>
+ </example>
<p>Note that searching large text files is <em>very</em>
inefficient; <directive module="mod_authz_dbm"
<modulesynopsis metafile="mod_authz_host.xml.meta">
-<name>mod_authz_host</name>
+<name>mod_authz_host</name>
<description>Group authorizations based on host (name or IP
address)</description>
<status>Base</status>
<summary>
<p>The authorization providers implemented by <module>mod_authz_host</module> are
registered using the <directive module="mod_authz_core">Require</directive>
- directive. The directive can be referenced within a
+ directive. The directive can be referenced within a
<directive module="core" type="section">Directory</directive>,
- <directive module="core" type="section">Files</directive>,
+ <directive module="core" type="section">Files</directive>,
or <directive module="core" type="section">Location</directive> section
as well as <code><a href="core.html#accessfilename">.htaccess</a>
</code> files to control access to particular parts of the server.
</summary>
<seealso><a href="../howto/auth.html">Authentication, Authorization,
- and Access Control</a></seealso>
+ and Access Control</a></seealso>
<seealso><directive module="mod_authz_core">Require</directive></seealso>
<section id="requiredirectives"><title>The Require Directives</title>
- <p>Apache's <directive module="mod_authz_core">Require</directive>
+ <p>Apache's <directive module="mod_authz_core">Require</directive>
directive is used during the authorization phase to ensure that a user is allowed or
- denied access to a resource. mod_authz_host extends the
+ denied access to a resource. mod_authz_host extends the
authorization types with <code>ip</code> and <code>host</code>.
- Other authorization types may also be
+ Other authorization types may also be
used but may require that additional authorization modules be loaded.</p>
<p>These authorization providers affect which hosts can
<section id="reqip"><title>Require ip</title>
<p>The <code>ip</code> provider allows access to the server
- to be controlled based on the IP address of the remote client.
- When <code>Require ip <var>ip-address</var></code> is specified,
+ to be controlled based on the IP address of the remote client.
+ When <code>Require ip <var>ip-address</var></code> is specified,
then the request is allowed access if the IP address matches.</p>
<p>A full IP address:</p>
-
+
<example>
Require ip 10.1.2.3<br />
Require ip 192.168.1.104 192.168.1.205
</example>
<p>An IP address of a host allowed access</p>
-
+
<p>A partial IP address:</p>
-
+
<example>
Require ip 10.1<br />
Require ip 10 172.20 192.168.2
</example>
<p>The first 1 to 3 bytes of an IP address, for subnet
restriction.</p>
-
+
<p>A network/netmask pair:</p>
-
+
<example>
Require ip 10.1.0.0/255.255.0.0
</example>
<p>A network a.b.c.d, and a netmask w.x.y.z. For more
fine-grained subnet restriction.</p>
-
+
<p>A network/nnn CIDR specification:</p>
-
+
<example>
Require ip 10.1.0.0/16
</example>
<p>Similar to the previous case, except the netmask consists of
nnn high-order 1 bits.</p>
-
+
<p>Note that the last three examples above match exactly the
same set of hosts.</p>
-
+
<p>IPv6 addresses and IPv6 subnets can be specified as shown
below:</p>
-
+
<example>
Require ip 2001:db8::a00:20ff:fea7:ccea<br />
Require ip 2001:db8::a00:20ff:fea7:ccea/10
<section id="reqhost"><title>Require host</title>
<p>The <code>host</code> provider allows access to the server
- to be controlled based on the host name of the remote client.
- When <code>Require host <var>host-name</var></code> is specified,
+ to be controlled based on the host name of the remote client.
+ When <code>Require host <var>host-name</var></code> is specified,
then the request is allowed access if the host name matches.</p>
<p>A (partial) domain-name</p>
-
+
<example>
Require host example.org<br />
Require host .net example.edu
</example>
-
+
<p>Hosts whose names match, or end in, this string are allowed
access. Only complete components are matched, so the above
example will match <code>foo.example.org</code> but it will not
<modulesynopsis metafile="mod_authz_owner.xml.meta">
-<name>mod_authz_owner</name>
+<name>mod_authz_owner</name>
<description>Authorization based on file ownership</description>
<status>Extension</status>
<sourcefile>mod_authz_owner.c</sourcefile>
<modulesynopsis metafile="mod_authz_user.xml.meta">
-<name>mod_authz_user</name>
+<name>mod_authz_user</name>
<description>User Authorization</description>
<status>Base</status>
<sourcefile>mod_authz_user.c</sourcefile>
</example>
<note type="warning"><p> Review the default configuration for a list of
- patterns that you might want to explicitly ignore after using this
+ patterns that you might want to explicitly ignore after using this
directive.</p></note>
</usage>
</directivesynopsis>
<dt><a name="indexoptions.addaltclass"
id="indexoptions.addaltclass">AddAltClass</a></dt>
<dd>Adds an additional CSS class declaration to each row of the
- directory listing table when <code>IndexOptions HTMLTable</code>
+ directory listing table when <code>IndexOptions HTMLTable</code>
is in effect and an <code>IndexStyleSheet</code> is defined.
Rather than the standard <code>even</code> and <code>odd</code>
classes that would otherwise be applied to each row of the table,
HTTP Server 2.0.23 and later</em>)</dt>
<dd>This option with <code>FancyIndexing</code> constructs
- a simple table for the fancy directory listing.
+ a simple table for the fancy directory listing.
It is necessary for utf-8 enabled platforms or if file
names or description text will alternate between
left-to-right and right-to-left reading order.</dd>
<p>You can, if desired, prevent the client from reordering the list
by also adding the <code><a
- href="#indexoptions.suppresscolumnsorting">SuppressColumnSorting</a></code>
+ href="#indexoptions.suppresscolumnsorting">SuppressColumnSorting</a></code>
index option to remove the sort link from the top of the column,
along with the <code><a
href="#indexoptions.ignoreclient">IgnoreClient</a></code> index
cause the request/response to be slower than not using a buffer at
all. These filters should be used with care, and only where
necessary.</note>
-
+
</summary>
<seealso><a href="../filter.html">Filters</a></seealso>
<summary>
<note type="warning">This module should be used with care, as when the
<directive module="mod_cache">CacheQuickHandler</directive> directive is
- in its default value of <strong>on</strong>, the <directive
- module="mod_authz_host">Allow</directive> and <directive
+ in its default value of <strong>on</strong>, the <directive
+ module="mod_authz_host">Allow</directive> and <directive
module="mod_authz_host">Deny</directive> directives will be circumvented.
You should not enable quick handler caching for any content to which you
wish to limit access by client host name, address or environment
- variable.</note>
+ variable.</note>
<p><module>mod_cache</module> implements an <a
href="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616</a> compliant
<p>Under the default mode of cache operation, the cache runs as a quick handler,
short circuiting the majority of server processing and offering the highest
cache performance available.</p>
-
+
<p>In this mode, the cache <strong>bolts onto</strong> the front of the server,
acting as if a free standing RFC 2616 caching proxy had been placed in front of
the server.</p>
-
+
<p>While this mode offers the best performance, the administrator may find that
under certain circumstances they may want to perform further processing on the
request after the request is cached, such as to inject personalisation into the
before globally defined <directive>CacheEnable</directive> directives.</p>
<p>When acting as a forward proxy server, <var>url-string</var> can
- also be used to specify remote sites and proxy protocols which
+ also be used to specify remote sites and proxy protocols which
caching should be enabled for.</p>
<example>
CacheEnable disk http://.example.org/<br />
</example>
- <p> The <code>no-cache</code> environment variable can be set to
+ <p> The <code>no-cache</code> environment variable can be set to
disable caching on a finer grained set of resources in versions
2.2.12 and later.</p>
</Location><br />
</example>
- <p>The <code>no-cache</code> environment variable can be set to
+ <p>The <code>no-cache</code> environment variable can be set to
disable caching on a finer grained set of resources in versions
2.2.12 and later.</p>
<context>directory</context>
<context>.htaccess</context>
</contextlist>
-
+
<usage>
<p>Ordinarily, documents without a last-modified date are not cached.
Under some circumstances the last-modified date is removed (during
<usage>
<p>Ordinarily, requests with query string parameters are cached separately
for each unique query string. This is according to RFC 2616/13.9 done only
- if an expiration time is specified. The
+ if an expiration time is specified. The
<directive>CacheIgnoreQueryString</directive> directive tells the cache to
- cache requests even if no expiration time is specified, and to reply with
+ cache requests even if no expiration time is specified, and to reply with
a cached reply even if the query string differs. From a caching point of
- view the request is treated as if having no query string when this
+ view the request is treated as if having no query string when this
directive is enabled.</p>
<example>
<context>directory</context>
<context>.htaccess</context>
</contextlist>
-
+
<usage>
<p>In the event that a document does not provide an expiry date but does
provide a last-modified date, an expiry date can be calculated based on
<usage>
<p>The <directive>CacheLock</directive> directive enables the thundering herd lock
for the given URL space.</p>
-
+
<p>In a minimal configuration the following directive is all that is needed to
enable the thundering herd lock in the default system temp directory.</p>
<default>CacheLockPath /tmp/mod_cache-lock</default>
<contextlist><context>server config</context><context>virtual host</context>
</contextlist>
-
+
<usage>
<p>The <directive>CacheLockPath</directive> directive allows you to specify the
directory in which the locks are created. By default, the system's temporary
<default>CacheLockMaxAge 5</default>
<contextlist><context>server config</context><context>virtual host</context>
</contextlist>
-
+
<usage>
<p>The <directive>CacheLockMaxAge</directive> directive specifies the maximum
age of any cache lock.</p>
-
+
<p>A lock older than this value in seconds will be ignored, and the next
incoming request will be given the opportunity to re-establish the lock.
This mechanism prevents a slow client taking an excessively long time to refresh
an entity.</p>
-
+
</usage>
</directivesynopsis>
<context>.htaccess</context>
</contextlist>
<compatibility>Available in Apache 2.3.9 and later</compatibility>
-
+
<usage>
<p>When the <directive module="mod_cache">CacheHeader</directive> directive
is switched on, an <strong>X-Cache</strong> header will be added to the response
<context>.htaccess</context>
</contextlist>
<compatibility>Available in Apache 2.3.9 and later</compatibility>
-
+
<usage>
<p>When the <directive module="mod_cache">CacheDetailHeader</directive> directive
is switched on, an <strong>X-Cache-Detail</strong> header will be added to the response
containing the detailed reason for a particular caching decision.</p>
-
+
<p>It can be useful during development of cached RESTful services to have additional
information about the caching decision written to the response headers, so as to
confirm whether <code>Cache-Control</code> and other headers have been correctly
used by the service and client.</p>
-
+
<p>If the normal handler is used, this directive may appear within a
<directive module="core"><Directory></directive> or
<directive module="core"><Location></directive> directive. If the quick handler
<context>directory</context>
<context>.htaccess</context>
</contextlist>
-
+
<usage>
<p>The <directive>CacheMaxFileSize</directive> directive sets the
maximum size, in bytes, for a document to be considered for storage in
<context>directory</context>
<context>.htaccess</context>
</contextlist>
-
+
<usage>
<p>The <directive>CacheReadSize</directive> directive sets the
minimum amount of data, in bytes, to be read from the backend before the
<p>This directive only takes effect when the data is being saved to the
cache, as opposed to data being served from the cache.</p>
-
+
<example>
CacheReadSize 102400
</example>
</example>
</usage>
</directivesynopsis>
-
+
</modulesynopsis>
<module>mod_cgid</module> should be used in place of
this module. At the user level, the two modules are essentially
identical.</p>
-
+
<p>For backward-compatibility, the cgi-script handler will also be activated
for any file with the mime-type <code>application/x-httpd-cgi</code>. The
use of the magic mime-type is deprecated.</p>
process locale to ISO-8859-1, but not the body of responses. In
any environment, <module>mod_charset_lite</module> can be used to
specify that response bodies should be translated. For example,
- if files are stored in EBCDIC, then
+ if files are stored in EBCDIC, then
<module>mod_charset_lite</module> can translate them to
ISO-8859-1 before sending them to the client.</p>
as a valid character set name by the character set support in
<glossary>APR</glossary>. Generally, this means that it must be
supported by iconv.</p>
-
+
<example><title>Example</title>
<Directory /export/home/trawick/apacheinst/htdocs/convert><br />
<indent>
<p>The character set names in this example work with the iconv
translation support in Solaris 8.</p>
-
+
<note>
Specifying the same charset for both <directive module="mod_charset_lite">CharsetSourceEnc</directive>
and <directive module="mod_charset_lite">CharsetDefault</directive> disables translation. The charset
</indent>
</Location><br />
</example>
-
+
</summary>
<seealso><a href="../filter.html">Filters</a></seealso>
<modulesynopsis metafile="mod_dav.xml.meta">
-<name>mod_dav</name>
+<name>mod_dav</name>
<description>Distributed Authoring and Versioning
(<a href="http://www.webdav.org/">WebDAV</a>) functionality</description>
<status>Extension</status>
by the <module>mod_dav_fs</module> module. Therefore, that module
must be compiled into the server or loaded at runtime using the
<directive module="mod_so">LoadModule</directive> directive.</p>
-
+
<p>In addition, a location for the DAV lock database must be
specified in the global section of your <code>httpd.conf</code>
file using the <directive module="mod_dav_fs">DavLockDB</directive>
</indent>
</Location>
</example>
-</usage>
+</usage>
</directivesynopsis>
<directivesynopsis>
<modulesynopsis metafile="mod_dav_fs.xml.meta">
-<name>mod_dav_fs</name>
+<name>mod_dav_fs</name>
<description>filesystem provider for <module>mod_dav</module></description>
<status>Extension</status>
<sourcefile>mod_dav_fs.c</sourcefile>
<modulesynopsis metafile="mod_dav_lock.xml.meta">
-<name>mod_dav_lock</name>
+<name>mod_dav_lock</name>
<description>generic locking module for <module>mod_dav</module></description>
<status>Extension</status>
<sourcefile>mod_dav_lock.c</sourcefile>
<dt>FreeTDS (for MSSQL and SyBase)</dt>
<dd>username, password, appname, dbname, host, charset, lang, server</dd>
<dt>MySQL</dt>
- <dd>host, port, user, pass, dbname, sock, flags, fldsz, group, reconnect</dd>
+ <dd>host, port, user, pass, dbname, sock, flags, fldsz, group, reconnect</dd>
<dt>Oracle</dt>
- <dd>user, pass, dbname, server</dd>
+ <dd>user, pass, dbname, server</dd>
<dt>PostgreSQL</dt>
<dd>The connection string is passed straight through to <code>PQconnectdb</code></dd>
<dt>SQLite2</dt>
<code>1</code> to only allow html files to be compressed (see
below). If you set this to <em>anything but <code>1</code></em> it
will be ignored.</p>
-
+
<p>If you want to restrict the compression to particular MIME types
in general, you may use the <directive module="mod_filter"
>AddOutputFilterByType</directive> directive. Here is an example of
<p>This Example will uncompress gzip'ed output from example.com, so other
filters can do further processing with it.
</p>
-
+
</section>
<section id="input"><title>Input Decompression</title>
<p>The <module>mod_deflate</module> module also provides a filter for
</indent>
</Location>
</example>
-
+
<p>Now if a request contains a <code>Content-Encoding:
gzip</code> header, the body will be automatically decompressed.
Few browsers have the ability to gzip request bodies. However,
not understand it.</p>
<p>If you use some special exclusions dependent
- on, for example, the <code>User-Agent</code> header, you must
+ on, for example, the <code>User-Agent</code> header, you must
manually configure an addition to the <code>Vary</code> header
to alert proxies of the additional restrictions. For example,
in a typical configuration where the addition of the <code>DEFLATE</code>
<example>
Header append Vary User-Agent
</example>
-
+
<p>If your decision about compression depends on other information
than request headers (<em>e.g.</em> HTTP version), you have to set the
<code>Vary</code> header to the value <code>*</code>. This prevents
<usage>
<p>The <directive>DeflateCompressionLevel</directive> directive specifies
- what level of compression should be used, the higher the value,
+ what level of compression should be used, the higher the value,
the better the compression, but the more CPU time is required to
achieve this.</p>
<p>The value must between 1 (less compression) and 9 (more compression).</p>
-<?xml version="1.0"?>
+<?xml version="1.0"?>
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
-<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
<!-- $LastChangedRevision$ -->
-<!--
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
- The ASF licenses this file to You under the Apache License, Version 2.0
+ The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
The sequence of tags is important and must be followed in order for
the document to validate. -->
-<modulesynopsis metafile="mod_dialup.xml.meta">
+<modulesynopsis metafile="mod_dialup.xml.meta">
<name>mod_dialup</name>
<description>Send static content at a bandwidth rate limit, defined by the various old modem standards</description>
<status>Experimental</status>
<summary>
<p>It is a module that sends static content at a bandwidth rate limit, defined
-by the various old modem standards. So, you can browse your site with a 56k
+by the various old modem standards. So, you can browse your site with a 56k
V.92 modem, by adding something like this:</p>
<example>
</example>
<p>Previously to do bandwidth rate limiting modules would have to block an entire
-thread, for each client, and insert sleeps to slow the bandwidth down.
-Using the new suspend feature, a handler can get callback N milliseconds in
-the future, and it will be invoked by the Event MPM on a different thread,
+thread, for each client, and insert sleeps to slow the bandwidth down.
+Using the new suspend feature, a handler can get callback N milliseconds in
+the future, and it will be invoked by the Event MPM on a different thread,
once the timer hits. From there the handler can continue to send data to the client.</p>
</summary>
</ul>
<p>The two functions are separated so that you can completely
remove (or replace) automatic index generation should you want
- to.</p>
+ to.</p>
<p>A "trailing slash" redirect is issued when the server
receives a request for a URL
executed if neither <code>index.html</code> or <code>index.txt</code>
existed in a directory.</p>
- <p>A single argument of "disabled" prevents <module>mod_dir</module> from
+ <p>A single argument of "disabled" prevents <module>mod_dir</module> from
searching for an index. An argument of "disabled" will be interpeted
literally if it has any arguments before or after it, even if they are "disabled"
as well.</p>
<name>DirectoryIndexRedirect</name>
<description>Configures an external redirect for directory indexes.
</description>
-<syntax>DirectoryIndexRedirect on | off | permanent | temp | seeother |
+<syntax>DirectoryIndexRedirect on | off | permanent | temp | seeother |
<var>3xx-code</var>
</syntax>
<default>DirectoryIndexRedirect off</default>
<p>A request for <code>http://example.com/docs/</code> would
return a temporary redirect to <code
- >http://example.com/docs/index.html</code>
+ >http://example.com/docs/index.html</code>
if it exists.</p>
</usage>
<syntax>DumpIOInput On|Off</syntax>
<default>DumpIOInput Off</default>
<contextlist><context>server config</context></contextlist>
-<compatibility>DumpIOInput is only available in Apache 2.1.3 and
+<compatibility>DumpIOInput is only available in Apache 2.1.3 and
later.</compatibility>
<usage>
<syntax>DumpIOOutput On|Off</syntax>
<default>DumpIOOutput Off</default>
<contextlist><context>server config</context></contextlist>
-<compatibility>DumpIOOutput is only available in Apache 2.1.3 and
+<compatibility>DumpIOOutput is only available in Apache 2.1.3 and
later.</compatibility>
<usage>
<modulesynopsis metafile="mod_echo.xml.meta">
<name>mod_echo</name>
-<description>A simple echo server to illustrate protocol
+<description>A simple echo server to illustrate protocol
modules</description>
<status>Experimental</status>
<sourcefile>mod_echo.c</sourcefile>
<p>This module allows for control of internal environment variables that
are used by various Apache HTTP Server modules. These variables are also
provided to CGI scripts as native system environment variables, and available
- for use in SSI pages. Environment variables may be passed from the shell
- which invoked the <program>httpd</program> process. Alternatively,
+ for use in SSI pages. Environment variables may be passed from the shell
+ which invoked the <program>httpd</program> process. Alternatively,
environment variables may be set or unset within the configuration process.</p>
</summary>
<seealso><a href="../env.html">Environment Variables</a></seealso>
<usage>
<p>Specifies one or more native system environment variables to make available
as internal environment variables, which are available to Apache HTTP Server modules
- as well as propogated to CGI scripts and SSI pages. Values come from the
- native OS environment of the shell which invoked the
+ as well as propogated to CGI scripts and SSI pages. Values come from the
+ native OS environment of the shell which invoked the
<program>httpd</program> process.</p>
<example><title>Example</title>
<override>FileInfo</override>
<usage>
- <p>Sets an internal environment variable, which is then available to Apache
+ <p>Sets an internal environment variable, which is then available to Apache
HTTP Server modules, and passed on to CGI scripts and SSI pages.</p>
<example><title>Example</title>
<em>after</em> most early request processing directives are run, such as access
control and URI-to-filename mapping. If the environment variable you're
setting is meant as input into this early phase of processing such as the
- <directive module="mod_rewrite">RewriteRule</directive> directive, you should
+ <directive module="mod_rewrite">RewriteRule</directive> directive, you should
instead set the environment variable with
<directive module="mod_setenvif"> SetEnvIf</directive>.</p>
</note>
-
+
</usage>
<seealso><a href="../env.html">Environment Variables</a></seealso>
</directivesynopsis>
be fetched from the cache rather than from the source until this
time has passed. After that, the cache copy is considered
"expired" and invalid, and a new copy must be obtained from the
- source.</p>
+ source.</p>
<p>To modify <code>Cache-Control</code> directives other than
<code>max-age</code> (see <a
module="mod_headers">Header</directive> directive.</p>
<p> When the <code>Expires</code> header is already part of the response
- generated by the server, for example when generated by a CGI script or
+ generated by the server, for example when generated by a CGI script or
proxied from an origin server, this module does not change or add
an <code>Expires</code> or <code>Cache-Control</code> header.</p>
</summary>
generated. If the criteria aren't met, no header will be sent, and
the effect will be as though this directive wasn't even
specified.</p>
- </usage>
+ </usage>
</directivesynopsis>
<directivesynopsis>
escape blanks which should be part of a program argument. Any
backslashes which are part of the argument must be escaped with
backslash themselves. In addition to the standard CGI environment
- variables, DOCUMENT_URI, DOCUMENT_PATH_INFO, and
+ variables, DOCUMENT_URI, DOCUMENT_PATH_INFO, and
QUERY_STRING_UNESCAPED will also be set for the program.</dd>
<dt><code>mode=<var>mode</var></code></dt>
<note><title>Note</title>
<p>Don't bother asking for a directive which recursively
- caches all the files in a directory. Try this instead... See the
+ caches all the files in a directory. Try this instead... See the
<directive module="core">Include</directive> directive, and consider
this command:</p>
components of the server may have stored their response headers in either
the table that corresponds to <code>onsuccess</code> or the table that
corresponds to <code>always</code>. "Always" in this context refers to
- whether headers you add will be sent during both a successful and unsucessful
+ whether headers you add will be sent during both a successful and unsucessful
response, but if your action is a function of an existing header, you
will have to read on for further complications.</p>
- <p> The default value of <code>onsuccess</code> may need to be changed to
+ <p> The default value of <code>onsuccess</code> may need to be changed to
<code>always</code> under the circumstances similar to those listed below.
Note also that repeating this directive with both conditions makes sense in
- some scenarios because <code>always</code> is not a superset of
+ some scenarios because <code>always</code> is not a superset of
<code>onsuccess</code> with respect to existing headers:</p>
<ul>
- <li> You're adding a header to a non-success (non-2xx) response, such
- as a redirect, in which case only the table corresponding to
+ <li> You're adding a header to a non-success (non-2xx) response, such
+ as a redirect, in which case only the table corresponding to
<code>always</code> is used in the ultimate response.</li>
<li> You're modifying or removing a header generated by a CGI script,
- in which case the CGI scripts are in the table corresponding to
+ in which case the CGI scripts are in the table corresponding to
<code>always</code> and not in the default table.</li>
- <li> You're modifying or removing a header generated by some piece of
- the server but that header is not being found by the default
+ <li> You're modifying or removing a header generated by some piece of
+ the server but that header is not being found by the default
<code>onsuccess</code> condition.</li>
</ul>
<usage>
<note><!-- FIXME: -->This document is still under development.</note>
-</usage>
+</usage>
</directivesynopsis>
</modulesynopsis>
<usage>
<note><!-- FIXME: -->This document is still under development.</note>
-</usage>
+</usage>
</directivesynopsis>
<directivesynopsis>
<usage>
<note><!-- FIXME: -->This document is still under development.</note>
-</usage>
+</usage>
</directivesynopsis>
</modulesynopsis>
<p>This module processes <code>.map</code> files, thereby
replacing the functionality of the <code>imagemap</code> CGI
program. Any directory or document type configured to use the
- handler <code>imap-file</code> (using either
+ handler <code>imap-file</code> (using either
<directive module="mod_mime">AddHandler</directive> or
<directive module="core">SetHandler</directive>)
will be processed by this module.</p>
>SSIUndefinedEcho</directive> directive. Any dates printed are
subject to the currently configured <code>timefmt</code>.</p>
- <p>Attributes:</p>
+ <p>Attributes:</p>
<dl>
<dt><code>var</code></dt>
<p>The <code>decoding</code> attribute must <em>precede</em> the
corresponding <code>var</code> attribute to be effective.</p>
</dd>
-
+
<dt><code>encoding</code></dt>
<dd><p>Specifies how Apache should encode special characters
contained in the variable before outputting them. If set
<em>precede</em> the corresponding <code>var</code> attribute to
be effective.</p>
</dd>
-
+
<dt><code>encoding</code></dt>
<dd><p>Specifies how Apache should encode special characters
contained in the variable before setting them. The default is
<dt><code><var>string1</var> = <var>string2</var><br />
<var>string1</var> == <var>string2</var><br />
<var>string1</var> != <var>string2</var></code></dt>
-
+
<dd><p>Compare <var>string1</var> with <var>string2</var>. If
<var>string2</var> has the form <code>/<var>string2</var>/</code>
then it is treated as a regular expression. Regular expressions are
parsed expression tokenizer information, the parse tree and how it is
evaluated into the output sent to the client.</p>
</note>
-
+
<note><title>Escaping slashes in regex strings</title>
<p>All slashes which are not intended to act as delimiters in your regex must
be escaped. This is regardless of their meaning to the regex engine.</p>
<p>You may want to use this option if you have 2 servers parsing the
output of a file each processing different commands (possibly at
- different times).</p>
+ different times).</p>
<example><title>Example</title>
SSIStartTag "<%"<br />
</example>
<p>The example given above, which also specifies a matching
- <directive module="mod_include">SSIEndTag</directive>, will
- allow you to use SSI directives as shown in the example
+ <directive module="mod_include">SSIEndTag</directive>, will
+ allow you to use SSI directives as shown in the example
below:</p>
<example><title>SSI directives with alternate start and end tags</title>
<compatibility>Available in version 2.0.30 and later.</compatibility>
<usage>
-<p>This directive changes the format in which date strings are displayed
+<p>This directive changes the format in which date strings are displayed
when echoing <code>DATE</code> environment variables. The
<var>formatstring</var> is as in <code>strftime(3)</code> from the
C standard library.</p>
if already present, or set if the header is not already present. This can
be used to enable caching of the output. <directive>SSILastModified</directive>
can take on the following values:</p>
-
+
<dl>
-
+
<dt><code>off</code></dt>
<dd>The <code>Last-Modified</code> header will be stripped from responses,
unless the <directive module="mod_include">XBitHack</directive> directive
is set to <code>full</code> as described below.</dd>
-
+
<dt><code>on</code></dt>
<dd>The <code>Last-Modified</code> header will be respected if already
present in a response, and added to the response if the response is a
file and the header is missing. The
<directive module="mod_include">SSILastModified</directive> directive
takes precedence over <directive module="mod_include">XBitHack</directive>.</dd>
-
+
</dl>
-
+
</usage>
</directivesynopsis>
new <a href="../expr.html">ap_expr</a> syntax for conditional expressions
in <code>#if</code> flow control elements. This directive allows to
switch to the <a href="#legacyexpr">old syntax</a> which is compatible
- with Apache HTTPD version 2.2.x and earlier.
+ with Apache HTTPD version 2.2.x and earlier.
</p>
</usage>
</directivesynopsis>
returned file to be the last modified time of the file. If
it is not set, then no last-modified date is sent. Setting
this bit allows clients and proxies to cache the result of
- the request.
+ the request.
<note><title>Note</title>
<p>You would not want to use the full option, unless you assure the
group-execute bit is unset for every SSI script which might <code
>#include</code> a CGI or otherwise produces different output on
each hit (or could potentially change on subsequent requests).</p>
-
+
<p>The <directive module="mod_include">SSILastModified</directive>
directive takes precedence over the
<directive module="mod_include">XBitHack</directive> directive when
this module should <strong>only</strong> be
used in a controlled environment and always with caution.</p>
- <p>You will probably want to use <module>mod_authz_host</module>
+ <p>You will probably want to use <module>mod_authz_host</module>
to limit access to your server configuration information.</p>
-
+
<example><title>Access control</title>
<Location /server-info><br />
<indent>
the directives understood by that module, the hooks implemented
by that module, and the relevant directives from the current
configuration.</p>
-
+
<p>Other views of the configuration information are available by
appending a query to the <code>server-info</code> request. For
example, <code>http://your.host.example.com/server-info?config</code>
will show all configuration directives.</p>
-
+
<dl>
<dt><code>?<module-name></code></dt>
<dd>Only information relevant to the named module</dd>
</example>
<p>If a balancer is configured as follows:</p>
-
+
<table style="data">
<tr><th>worker</th>
<th>a</th>
or produced.</p>
<p>If a balancer is configured as follows:</p>
-
+
<table style="data">
<tr><th>worker</th>
<th>a</th>
<usage>
<note><!-- FIXME: -->This document is still under development.</note>
-</usage>
+</usage>
</directivesynopsis>
</modulesynopsis>
<section id="usingssltls"><title>Using SSL/TLS</title>
- <p>The ability to create an SSL and TLS connections to an LDAP server
+ <p>The ability to create an SSL and TLS connections to an LDAP server
is defined by the directives <directive module="mod_ldap">
LDAPTrustedGlobalCert</directive>, <directive module="mod_ldap">
LDAPTrustedClientCert</directive> and <directive module="mod_ldap">
binary DER or Base64 (PEM) encoded files.</p>
<p>Both CA and client certificates may be specified globally
- (LDAPTrustedGlobalCert) or per-connection (LDAPTrustedClientCert).
- When any settings are specified per-connection, the global
+ (LDAPTrustedGlobalCert) or per-connection (LDAPTrustedClientCert).
+ When any settings are specified per-connection, the global
settings are superceded.</p>
<p>The documentation for the SDK claims to support both SSL and
<directivesynopsis>
<name>LDAPOpCacheEntries</name>
-<description>Number of entries used to cache LDAP compare
+<description>Number of entries used to cache LDAP compare
operations</description>
<syntax>LDAPOpCacheEntries <var>number</var></syntax>
<default>LDAPOpCacheEntries 1024</default>
<code>LDAPReferralHopLimit</code> works in conjunction with this directive to limit the
number of referral hops to follow before terminating the LDAP query. When referral processing
is enabled client credentials will be provided, via a rebind callback, for any LDAP server
- requiring them. </p>
+ requiring them. </p>
</usage>
</directivesynopsis>
typically controls how long the LDAP client library will wait for the TCP
connection to the LDAP server to complete.</p>
- <p> If a connection is not successful with the timeout period, either an error will be
- returned or the LDAP client library will attempt to connect to a secondary LDAP
- server if one is specified (via a space-separated list of hostnames in the
+ <p> If a connection is not successful with the timeout period, either an error will be
+ returned or the LDAP client library will attempt to connect to a secondary LDAP
+ server if one is specified (via a space-separated list of hostnames in the
<directive module="mod_ldap">AuthLDAPURL</directive>).</p>
- <p>The default is 10 seconds, if the LDAP client library linked with the
+ <p>The default is 10 seconds, if the LDAP client library linked with the
server supports the LDAP_OPT_NETWORK_TIMEOUT option.</p>
<note>LDAPConnectionTimeout is only available when the LDAP client library linked
- with the server supports the LDAP_OPT_NETWORK_TIMEOUT
- (or LDAP_OPT_CONNECT_TIMEOUT) option, and the ultimate behavior is
+ with the server supports the LDAP_OPT_NETWORK_TIMEOUT
+ (or LDAP_OPT_CONNECT_TIMEOUT) option, and the ultimate behavior is
dictated entirely by the LDAP client library.
</note>
</usage>
<contextlist><context>server config</context></contextlist>
<usage>
- <p>Specifies whether to force the verification of a
- server certificate when establishing an SSL connection to the
+ <p>Specifies whether to force the verification of a
+ server certificate when establishing an SSL connection to the
LDAP server.</p>
</usage>
</directivesynopsis>
<usage>
<p>Specifies the maximum age, in seconds, that a pooled LDAP connection can remain idle
- and still be available for use. Connections are cleaned up when they are next needed,
+ and still be available for use. Connections are cleaned up when they are next needed,
not asynchronously.</p>
- <p>A setting of 0 causes connections to never be saved in the backend
- connection pool. The default value of -1, and any other negative value,
+ <p>A setting of 0 causes connections to never be saved in the backend
+ connection pool. The default value of -1, and any other negative value,
allows connections of any age to be reused.</p>
<note><p>This timeout defaults to units of seconds, but accepts
<contextlist><context>server config</context></contextlist>
<usage>
- <p>Turns on SDK-specific LDAP debug options that generally cause the LDAP
- SDK to log verbose trace information to the main Apache error log.
+ <p>Turns on SDK-specific LDAP debug options that generally cause the LDAP
+ SDK to log verbose trace information to the main Apache error log.
The trace messages from the LDAP SDK provide gory details that
can be useful during debugging of connectivity problems with backend LDAP servers</p>
- <p>This option is only configurable when Apache HTTP Server is linked with
- an LDAP SDK that implements <code>LDAP_OPT_DEBUG</code> or
- <code>LDAP_OPT_DEBUG_LEVEL</code>, such as OpenLDAP (a value of 7 is verbose)
+ <p>This option is only configurable when Apache HTTP Server is linked with
+ an LDAP SDK that implements <code>LDAP_OPT_DEBUG</code> or
+ <code>LDAP_OPT_DEBUG_LEVEL</code>, such as OpenLDAP (a value of 7 is verbose)
or Tivoli Directory Server (a value of 65535 is verbose).</p>
<note type="warning">
- <p>The logged information will likely contain plaintext credentials being used or
+ <p>The logged information will likely contain plaintext credentials being used or
validated by LDAP authentication, so care should be taken in protecting and purging
the error log when this directive is used.</p>
</note>
-
+
</usage>
</directivesynopsis>
<td>The process ID of the child that serviced the request.</td></tr>
<tr><td><code>%{<var>format</var>}P</code></td>
- <td>The process ID or thread ID of the child that serviced the
+ <td>The process ID or thread ID of the child that serviced the
request. Valid formats are <code>pid</code>, <code>tid</code>,
- and <code>hextid</code>. <code>hextid</code> requires APR 1.2.0 or
+ and <code>hextid</code>. <code>hextid</code> requires APR 1.2.0 or
higher.
</td></tr>
for the final status.</td></tr>
<tr><td><code>%t</code></td>
- <td>Time the request was received, in the format <code>[18/Sep/2011:19:18:28 -0400]</code>.
+ <td>Time the request was received, in the format <code>[18/Sep/2011:19:18:28 -0400]</code>.
The last number indicates the timezone offset from GMT</td></tr>
<tr><td><code>%{<var>format</var>}t</code></td>
comma-separated list of status codes immediately following the
"%". The status code list may be peceded by a "<code>!</code>" to
indicate negation.</p>
-
+
<table border="1" style="zebra">
<columnspec><column width=".2"/><column width=".8"/></columnspec>
<td>Logs <code>User-agent</code> on 400 errors and 501 errors only. For
other status codes, the literal string <code>"-"</code> will be
logged.</td></tr>
-
+
<tr><td><code>%!200,304,302{Referer}i</code></td>
- <td>Logs <code>Referer</code> on all requests that do
+ <td>Logs <code>Referer</code> on all requests that do
<em>not</em> return one of the three specified codes,
"<code>-</code>" otherwise.
</td></tr>
<note type="warning"><title>Note</title>
<p>When entering a file path on non-Unix platforms, care should be taken
to make sure that only forward slashed are used even though the platform
- may allow the use of back slashes. In general it is a good idea to always
+ may allow the use of back slashes. In general it is a good idea to always
use forward slashes throughout the configuration files.</p>
</note></dd>
</dl>
example, if you want to record requests for all GIF
images on your server in a separate logfile but not in your main
log, you can use:</p>
-
+
<example>
SetEnvIf Request_URI \.gif$ gif-image<br />
CustomLog gif-requests.log common env=gif-image<br />
previous <directive>LogFormat</directive> directive as described
below.</p>
- <p>The second form of the <directive>LogFormat</directive>
+ <p>The second form of the <directive>LogFormat</directive>
directive associates an explicit <var>format</var> with a
<var>nickname</var>. This <var>nickname</var> can then be used in
subsequent <directive>LogFormat</directive> or
<note><title>Note</title>
<p>When entering a file path on non-Unix platforms, care should be taken
to make sure that only forward slashes are used even though the platform
- may allow the use of back slashes. In general it is a good idea to always
+ may allow the use of back slashes. In general it is a good idea to always
use forward slashes throughout the configuration files.</p>
</note></dd>
</dl>
<compatibility>2.3 and later</compatibility>
<summary>
-<p>This module allows the server to be extended with scripts written in the
+<p>This module allows the server to be extended with scripts written in the
Lua programming language. The extension points (hooks) available with
<module>mod_lua</module> include many of the hooks available to
natively compiled Apache HTTP Server modules, such as mapping requests to
-files, generating dynamic responses, access control, authentication, and
+files, generating dynamic responses, access control, authentication, and
authorization</p>
-<p>More information on the Lua programming language can be found at the
+<p>More information on the Lua programming language can be found at the
<a href="http://www.lua.org/">the Lua website</a>.</p>
<note><code>mod_lua</code> is still in experimental state.
<section id="writinghandlers"><title>Writing Handlers</title>
<p> In the Apache HTTP Server API, the handler is a specific kind of hook
-responsible for generating the response. Examples of modules that include a
-handler are <module>mod_proxy</module>, <module>mod_cgi</module>,
+responsible for generating the response. Examples of modules that include a
+handler are <module>mod_proxy</module>, <module>mod_cgi</module>,
and <module>mod_status</module>.</p>
<p><code>mod_lua</code> always looks to invoke a Lua function for the handler, rather than
require "string"
---[[
- This is the default method name for Lua handlers, see the optional
- function-name in the LuaMapHandler directive to choose a different
+--[[
+ This is the default method name for Lua handlers, see the optional
+ function-name in the LuaMapHandler directive to choose a different
entry point.
--]]
function handle(r)
end
else
r:puts("unknown HTTP method " .. r.method)
- end
+ end
end
</pre></example>
<section id="writinghooks"><title>Writing Hooks</title>
<p>Hook functions are how modules (and Lua scripts) participate in the
-processing of requests. Each type of hook exposed by the server exists for
-a specific purposes such as mapping requests to the filesystem,
+processing of requests. Each type of hook exposed by the server exists for
+a specific purposes such as mapping requests to the filesystem,
performing access control, or setting mimetypes. General purpose hooks
that simply run at handy times in the request lifecycle exist as well.</p>
--[[ example hook that rewrites one URI to another URI. It returns a
apache2.DECLINED to give other URL mappers a chance to work on the
substitution, including the core translate_name hook which maps based
- on the DocumentRoot.
+ on the DocumentRoot.
Note: It is currently undefined as to whether this runs before or after
mod_alias.
<dd>
<p>The request_rec is mapped in as a userdata. It has a metatable
which lets you do useful things with it. For the most part it
- has the same fields as the request_rec struct (see httpd.h
+ has the same fields as the request_rec struct (see httpd.h
until we get better docs here) many of which are writeable as
well as readable. (The table fields' content can be changed, but the
fields themselves cannot be set to different tables.)</p>
<example>
r:addoutputfilter(name|function) -- add an output filter
</example>
-
+
<example>
r:parseargs() -- returns a lua table containing the request's
query string arguments
</example>
</dd>
</dl>
-
+
</section>
<section id="logging"><title>Logging Functions</title>
<usage>
<p>Specify the lifecycle scope of the Lua interpreter which will
be used by handlers in this "Directory." The default is "once"</p>
-
+
<dl>
<dt>once:</dt> <dd>use the interpreter once and throw it away.</dd>
-
- <dt>request:</dt> <dd>use the interpreter to handle anything based on
- the same file within this request, which is also
+
+ <dt>request:</dt> <dd>use the interpreter to handle anything based on
+ the same file within this request, which is also
request scoped.</dd>
-
+
<dt>conn:</dt> <dd>Same as request but attached to the connection_rec</dd>
-
+
<dt>server:</dt> <dd>This one is different than others because the
server scope is quite long lived, and multiple threads
will have the same server_rec. To accommodate this
to the file /scripts/photos.lua and invoke the
handler function handle_show on the lua vm after
loading that file.</p>
-
+
<example>
LuaMapHandler /bingo /scripts/wombat.lua
</example>
</contextlist>
<override>All</override>
<usage><p>Add a path to lua's module search path. Follows the same
- conventions as lua. This just munges the package.path in the
+ conventions as lua. This just munges the package.path in the
lua vms.</p>
-
+
<example><title>Examples:</title>
LuaPackagePath /scripts/lib/?.lua<br />
LuaPackagePath /scripts/lib/?/init.lua
<usage>
<p>Add a path to lua's shared library search path. Follows the same
- conventions as lua. This just munges the package.cpath in the
+ conventions as lua. This just munges the package.cpath in the
lua vms.</p>
-
+
</usage>
</directivesynopsis>
ones) each time that file is needed, and reloads it if the
modified time indicates it is newer than the one it has
already loaded. The other values cause it to keep the file
- cached forever (don't stat and replace) or to never cache the
+ cached forever (don't stat and replace) or to never cache the
file.</p>
-
+
<p>In general stat or forever is good for production, and stat or never
for development.</p>
-
+
<example><title>Examples:</title>
LuaCodeCache stat<br />
LuaCodeCache forever<br />
<usage><p>
Add a hook (at APR_HOOK_MIDDLE) to the translate name phase of
request processing. The hook function receives a single
- argument, the request_rec, and should return a status code,
+ argument, the request_rec, and should return a status code,
which is either an HTTP error code, or the constants defined
in the apache2 module: apache2.OK, apache2.DECLINED, or
apache2.DONE. </p>
displayed as such. This information, also, is transmitted in
HTTP headers.</p>
- <p>The character set, language, encoding and mime type are all
- used in the process of content negotiation (See
+ <p>The character set, language, encoding and mime type are all
+ used in the process of content negotiation (See
<module>mod_negotiation</module>) to determine
which document to give to the client, when there are
- alternative documents in more than one character set, language,
+ alternative documents in more than one character set, language,
encoding or mime type. All filename extensions associations
created with <directive module="mod_mime">AddCharset</directive>,
<directive module="mod_mime">AddEncoding</directive>, <directive
<note>
It is recommended that new media types be added using the
- <directive>AddType</directive> directive rather than changing the
+ <directive>AddType</directive> directive rather than changing the
<directive module="mod_mime">TypesConfig</directive> file.
</note>
-
+
<example><title>Example</title>
AddType image/gif .gif
</example>
the content returned by the server.</p>
<p>This directive primarily configures the content types generated for
- static files served out of the filesystem. For resources other than
- static files, where the generator of the response typically specifies
+ static files served out of the filesystem. For resources other than
+ static files, where the generator of the response typically specifies
a Content-Type, this directive has no effect.</p>
</usage>
<compatibility>RemoveInputFilter is only available in Apache 2.0.26 and
later.</compatibility>
-<usage>
+<usage>
<p>The <directive>RemoveInputFilter</directive> directive removes any
input <a href="../filter.html">filter</a> associations for files with
the given extensions.
<compatibility>RemoveOutputFilter is only available in Apache 2.0.26 and
later.</compatibility>
-<usage>
+<usage>
<p>The <directive>RemoveOutputFilter</directive> directive removes any
output <a href="../filter.html">filter</a> associations for files with
the given extensions.
<code>document.html.de</code>, respectively. The type map file will
be called <code>document.html.var</code>, and will contain the
following:</p>
-
+
<example>
URI: document.html<br />
<br />
<directivesynopsis>
<name>CacheNegotiatedDocs</name>
-<description>Allows content-negotiated documents to be
+<description>Allows content-negotiated documents to be
cached by proxy servers</description>
<syntax>CacheNegotiatedDocs On|Off</syntax>
<default>CacheNegotiatedDocs Off</default>
<directivesynopsis>
<name>ForceLanguagePriority</name>
-<description>Action to take if a single acceptable document is not
+<description>Action to take if a single acceptable document is not
found</description>
<syntax>ForceLanguagePriority None|Prefer|Fallback [Prefer|Fallback]</syntax>
<default>ForceLanguagePriority Prefer</default>
<summary>
<p>This module enables SSL encryption for a specified port. It
- takes advantage of the SSL encryption functionality that is
+ takes advantage of the SSL encryption functionality that is
built into the NetWare operating system.</p>
</summary>
<usage>
<p>Specifies a list of client certificate files (DER format)
that are used when creating a proxied SSL connection. Each
- client certificate used by a server must be listed separately
+ client certificate used by a server must be listed separately
in its own <code>.der</code> file.</p>
</usage>
</directivesynopsis>
<contextlist><context>server config</context></contextlist>
<usage>
- <p>Allow a connection that was created on the specified address
+ <p>Allow a connection that was created on the specified address
and/or port to be upgraded to an SSL connection upon request from
- the client. The address and/or port must have already be defined
- previously with a <directive module="mpm_common">Listen</directive>
+ the client. The address and/or port must have already be defined
+ previously with a <directive module="mpm_common">Listen</directive>
directive.</p>
</usage>
</directivesynopsis>
<summary>
<p>This module <em>requires</em> the service of <module
- >mod_proxy</module>. It provides support for the
+ >mod_proxy</module>. It provides support for the
<code>Apache JServ Protocol version 1.3</code> (hereafter
<em>AJP13</em>).</p>
<seealso><a href="../env.html">Environment Variable documentation</a></seealso>
<section id="env"><title>Environment Variables</title>
- <p>Environment variables whose names have the prefix <code>AJP_</code>
- are forwarded to the origin server as AJP request attributes
+ <p>Environment variables whose names have the prefix <code>AJP_</code>
+ are forwarded to the origin server as AJP request attributes
(with the AJP_ prefix removed from the name of the key).</p>
</section>
</pre></example>
<p>The <code>request_headers</code> have the following structure:
</p><example><pre>
-req_header_name :=
+req_header_name :=
sc_req_header_name | (string) [see below for how this is parsed]
sc_req_header_name := 0xA0xx (integer)
<tr><td>BASELINE_CONTROL</td><td>26</td></tr>
<tr><td>MKACTIVITY</td><td>27</td></tr>
</table>
- <p>Later version of ajp13, will transport
+ <p>Later version of ajp13, will transport
additional methods, even if they are not in this list.</p>
</section>
<section><title>protocol, req_uri, remote_addr, remote_host, server_name,
<p>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 <code>lbmethod</code> value of
- the Balancer definition. See the <directive module="mod_proxy">ProxyPass</directive>
+ the Balancer definition. See the <directive module="mod_proxy">ProxyPass</directive>
directive for more information, especially regarding how to
configure the Balancer and BalancerMembers.</p>
</section>
<!-- ============= BALANCER_SESSION_ROUTE ================ -->
<dt><var><a name="balancer_session_route" id="balancer_session_route">BALANCER_SESSION_ROUTE</a></var></dt>
<dd>
- <p>This is assigned the <var>route</var> parsed from the current
+ <p>This is assigned the <var>route</var> parsed from the current
request.</p>
</dd>
<!-- ============= BALANCER_NAME ========================= -->
<dt><var><a name="balancer_name" id="balancer_name">BALANCER_NAME</a></var></dt>
<dd>
- <p>This is assigned the name of the balancer used for the current
+ <p>This is assigned the name of the balancer used for the current
request. The value is something like <code>balancer://foo</code>.</p>
</dd>
<!-- ============= BALANCER_WORKER_ROUTE ================= -->
<dt><var><a name="balancer_worker_route" id="balancer_worker_route">BALANCER_WORKER_ROUTE</a></var></dt>
<dd>
- <p>This is assigned the <var>route</var> of the worker that will be
+ <p>This is assigned the <var>route</var> of the worker that will be
used for the current request.</p>
</dd>
<section id="balancer_manager">
<title>Enabling Balancer Manager Support</title>
- <p>This module <em>requires</em> the service of
+ <p>This module <em>requires</em> the service of
<module>mod_status</module>.
Balancer manager enables dynamic update of balancer
members. You can use balancer manager to change the balance
dynamic growth, but is intended to handle much, much
larger numbers of backends. It is ideally suited as a
front-end HTTP switch.</p>
-
+
<p>This module <em>requires</em> the service of <module
>mod_proxy</module>.</p>
</summary>
<seealso><module>mod_proxy</module></seealso>
-
+
<directivesynopsis>
<name>ProxyExpressEnable</name>
<description>Enable the module functionality.</description>
<note><title>Note</title>
<p>The file is constructed from a plain text file format using
- the <code><a href="../programs/httxt2dbm.html">httxt2dbm</a></code>
+ the <code><a href="../programs/httxt2dbm.html">httxt2dbm</a></code>
utility.</p>
<example><title>ProxyExpress map file</title>
<summary>
<p>This module <em>requires</em> the service of <module
- >mod_proxy</module>. It provides support for the
+ >mod_proxy</module>. It provides support for the
<a href="http://www.fastcgi.com/">FastCGI</a> protocol.</p>
<p>Thus, in order to get the ability of handling the <code>FastCGI</code>
<module>mod_proxy_fcgi</module> have to be present in the server.</p>
<p>Unlike <a href="http://httpd.apache.org/mod_fcgid/">mod_fcgid</a>
- and <a href="http://www.fastcgi.com/">mod_fastcgi</a>,
+ and <a href="http://www.fastcgi.com/">mod_fastcgi</a>,
<module>mod_proxy_fcgi</module> has no provision for starting the
application process; <program>fcgistarter</program> is provided for
that purpose.</p>
</example>
<p>This application should be able to handle multiple concurrent
- connections. <module>mod_proxy</module> enables connection reuse by
+ connections. <module>mod_proxy</module> enables connection reuse by
default, so after a request has been completed the connection will be
held open by that httpd child process and won't be reused until that
- httpd process routes another request to the application. If the
+ httpd process routes another request to the application. If the
FastCGI application is unable to handle enough concurrent connections
from httpd, requests can block waiting for the application to close
an existing connection. One way to resolve this is to disable connection
</example>
<p>The balanced gateway needs <module>mod_proxy_balancer</module> and
- at least one load balancer algorithm module, such as
+ at least one load balancer algorithm module, such as
<module>mod_lbmethod_byrequests</module>, in addition to the proxy
modules listed above. <module>mod_lbmethod_byrequests</module> is the
default, and will be used for this example configuration.</p>
>mod_proxy</module>. It provides support for the passing the socket of the
client to another process.</p>
- <p><code>mod_proxy_fdpass</code> uses the ability of AF_UNIX domain
- sockets to <a href="http://www.freebsd.org/cgi/man.cgi?query=recv">pass an
+ <p><code>mod_proxy_fdpass</code> uses the ability of AF_UNIX domain
+ sockets to <a href="http://www.freebsd.org/cgi/man.cgi?query=recv">pass an
open file descriptor</a> to allow another process to finish handling a request.
</p>
- <p>The module has a <code>proxy_fdpass_flusher</code> provider interface,
+ <p>The module has a <code>proxy_fdpass_flusher</code> 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.</p>
- <p>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
+ <p>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
<a href="http://www.kernel.org/doc/man-pages/online/pages/man3/cmsg.3.html"
><code>struct cmsghdr</code></a>. Future versions of this module may include
more data after the client socket, but this is not implemented at this time.
See the <directive>ProxyFtpListOnWildcard</directive> directive.
</p>
</section> <!-- /wildcard -->
-
+
<directivesynopsis>
<name>ProxyFtpListOnWildcard</name>
<description>Whether wildcards in requested filenames trigger a file listing</description>
</example>
<p>The balanced gateway needs <module>mod_proxy_balancer</module> and
- at least one load balancer algorithm module, such as
+ at least one load balancer algorithm module, such as
<module>mod_lbmethod_byrequests</module>, in addition to the proxy
modules listed above. <module>mod_lbmethod_byrequests</module> is the
default, and will be used for this example configuration.</p>
-<?xml version="1.0"?>
+<?xml version="1.0"?>
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
-<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
<!-- $LastChangedRevision$ -->
-<!--
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
- The ASF licenses this file to You under the Apache License, Version 2.0
+ The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
The sequence of tags is important and must be followed in order for
the document to validate. -->
-<modulesynopsis metafile="mod_ratelimit.xml.meta">
+<modulesynopsis metafile="mod_ratelimit.xml.meta">
<name>mod_ratelimit</name>
<description>Bandwidth Rate Limiting for Clients</description>
<status>Extension</status>
<summary>
-<p>Provides a <code>rate_limit</code> filter to limit client bandwidth.
-The connection speed to be simulated is specified, in kb/s, using the environment
+<p>Provides a <code>rate_limit</code> filter to limit client bandwidth.
+The connection speed to be simulated is specified, in kb/s, using the environment
variable <code>rate-limit</code>.</p>
<example><title>Example Configuration</title>
<modulesynopsis metafile="mod_remoteip.xml.meta">
<name>mod_remoteip</name>
-<description>Replaces the apparent client remote IP address and hostname
-for the request with the IP address list presented by a proxies or a load
+<description>Replaces the apparent client remote IP address and hostname
+for the request with the IP address list presented by a proxies or a load
balancer via the request headers.
</description>
<identifier>remoteip_module</identifier>
<summary>
- <p>This module is used to treat the remote host which initiated the
+ <p>This module is used to treat the remote host which initiated the
request as the originating remote host as identified by httpd for the
purposes of authorization and logging, even where that remote host is
behind a load balancer, front end server, or proxy server.</p>
- <p>The module replaces the apparent remote (client) IP/hostname for
+ <p>The module replaces the apparent remote (client) IP/hostname for
the request with the IP address reported in the request header
configured with the <directive>RemoteIPHeader</directive> directive.</p>
and <directive module="mod_authz_host" type="section">Require ip</directive>,
is reported by <module>mod_status</module>, and is recorded by
<module>mod_log_config</module> <code>%a</code> and <code>%h</code>
- directives. It also determines the machine probed for an inetd
- identity by <module>mod_ident</module> based on the
+ directives. It also determines the machine probed for an inetd
+ identity by <module>mod_ident</module> based on the
<directive module="mod_ident">IdentityCheck</directive> configuration.</p>
<note type="warning">It is critical to only enable this behavior from
<section id="processing"><title>Remote IP Processing</title>
<p>Apache identifies the client with the connection's remote_ip value,
- and the connection remote_host and remote_logname are derived from this
- value. These fields play a role in authentication, authorization and
+ 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.</p>
<p>mod_remoteip replaces the true remote_ip with the advertised remote_ip as
provided by a proxy, for every evaluation of the client that occurs in the
- server, and resets the remote_host and remote_logname values to trigger a
+ server, and resets the remote_host and remote_logname values to trigger a
fresh dns or ident query of the remote IP address.</p>
- <p>When multiple, comma delimited remote IP addresses are listed in the
+ <p>When multiple, comma delimited remote IP addresses are listed in the
header value, they are processed in Right-to-Left order. Processing
halts when a given remote IP address is not trusted to present the
- preceeding IP address. The header field is updated to this remaining
+ preceeding 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.</p>
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 <directive>RemoteIPInternalProxy</directive>
- internal (intranet) proxies are registered.</note>
+ internal (intranet) proxies are registered.</note>
</section>
<contextlist><context>server config</context><context>virtual host</context></contextlist>
<usage>
- <p>The <directive>RemoteIPHeader</directive> directive triggers
+ <p>The <directive>RemoteIPHeader</directive> directive triggers
<module>mod_remoteip</module> to treat the value of the specified
<var>header-field</var> header as the client IP address, or list
- of intermediate client IP addresses, subject to further configuration
+ of intermediate client IP addresses, subject to further configuration
of the <directive>RemoteIPInternalProxy</directive> and
<directive>RemoteIPTrustedProxy</directive> directives. Unless these
other directives are used, <module>mod_remoteip</module> will trust all
or more addresses (or address blocks) to trust as presenting a valid
RemoteIPHeader value of the client IP. Unlike the
<directive>RemoteIPTrustedProxy</directive> directive, any IP address
- presented in this header, including private intranet addresses, are
+ presented in this header, including private intranet addresses, are
trusted when passed from these proxies.</p>
<example><title>Internal (Load Balancer) Example</title>
a header into which <module>mod_remoteip</module> will collect a list of
all of the intermediate client IP addresses trusted to resolve the actual
remote IP. Note that intermediate <directive>RemoteIPTrustedProxy</directive>
- addresses are recorded in this header, while any intermediate
+ addresses are recorded in this header, while any intermediate
<directive>RemoteIPInternalProxy</directive> addresses are discarded.</p>
<example><title>Example</title>
<p>The <directive>RemoteIPTrustedProxy</directive> directive adds one
or more addresses (or address blocks) to trust as presenting a valid
RemoteIPHeader value of the client IP. Unlike the
- <directive>RemoteIPInternalProxy</directive> directive, any intranet
+ <directive>RemoteIPInternalProxy</directive> 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 remote IP, and are left in the
+ 2000::/3 block) are not trusted as the remote IP, and are left in the
<directive>RemoteIPHeader</directive> header's value.</p>
<example><title>Trusted (Load Balancer) Example</title>
<identifier>rewrite_module</identifier>
<summary>
- <p>The <module>mod_rewrite</module> module uses a rule-based rewriting
+ <p>The <module>mod_rewrite</module> module uses a rule-based rewriting
engine, based on a regular-expression parser, to rewrite requested URLs on
- the fly. By default, <module>mod_rewrite</module> maps a URL to a filesystem
+ the fly. By default, <module>mod_rewrite</module> 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.</p>
- <p><module>mod_rewrite</module> provides a flexible and powerful way to
- manipulate URLs using an unlimited number of rules. Each rule can have an
+ <p><module>mod_rewrite</module> 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
+ based on server variables, environment variables, HTTP headers, or time
stamps.</p>
<p><module>mod_rewrite</module> operates on the full URL path, including the
- path-info section. A rewrite rule can be invoked in
- <code>httpd.conf</code> or in <code>.htaccess</code>. 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
+ path-info section. A rewrite rule can be invoked in
+ <code>httpd.conf</code> or in <code>.htaccess</code>. 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.</p>
<p>Further details, discussion, and examples, are provided in the
<dl>
<dt><code>Inherit</code></dt>
<dd>
-
+
<p>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
of local rules - has no influence on this behavior. If local
rules forced the rewriting to stop, the inherited rules won't
be processed.</p>
-
+
<note type="warning">
Rules inherited from the parent scope are applied
<strong>after</strong> rules specified in the child scope.
<dt><code>InheritBefore</code></dt>
<dd>
<p> Like <code>Inherit</code> above, but the rules from the parent scope
- are applied <strong>before</strong> rules specified in the child scope.
+ are applied <strong>before</strong> rules specified in the child scope.
Available in Apache HTTP Server 2.3.10 and later.</p>
</dd>
-
+
</dl>
</usage>
<dt>dbm</dt>
<dd>Looks up an entry in a dbm file containing name, value
pairs. Hash is constructed from a plain text file format using
- the <code><a href="../programs/httxt2dbm.html">httxt2dbm</a></code>
+ the <code><a href="../programs/httxt2dbm.html">httxt2dbm</a></code>
utility. (<a href="../rewrite/rewritemap.html#dbm">Details ...</a>)</dd>
<dt>int</dt>
that result in the substitution of a relative path.
When you use a <directive module="mod_rewrite">RewriteRule</directive>
in a <code>.htaccess</code> file, <module>mod_rewrite</module> strips off
- the local directory prefix before processing, then rewrites the rest of
+ the local directory prefix before processing, then rewrites the rest of
the URL. When the rewrite is completed, <module>mod_rewrite</module>
automatically adds the local directory prefix (or the
- <directive>RewriteBase</directive> when set) back on to the substitution
+ <directive>RewriteBase</directive> when set) back on to the substitution
before handing it back to the core of the server as if it were the original
URL.</p>
-
+
<p>This directive is <em>required</em> for per-directory rewrites whose context
is a directory made available via the <directive module="mod_alias">Alias</directive>
directive, when the substitution uses a relative path.</p>
<code>.htaccess</code> file where you want to use <directive
module="mod_rewrite">RewriteRule</directive> directives.</p>
- <p>The example below demonstrates how to map
- http://example.com/myapp/index.html to
- /home/www/example/newsite.html, in a <code>.htaccess</code> file. This
+ <p>The example below demonstrates how to map
+ http://example.com/myapp/index.html to
+ /home/www/example/newsite.html, in a <code>.htaccess</code> file. This
assumes that the content available at
http://example.com/ is on disk at /home/www/example/</p>
<example>
Most are documented elsewhere in the Manual or in
the CGI specification.</p>
- <p>SERVER_NAME and SERVER_PORT depend on the values of
+ <p>SERVER_NAME and SERVER_PORT depend on the values of
<directive module="core">UseCanonicalName</directive> and
<directive module="core">UseCanonicalPhysicalPort</directive>
respectively.</p>
browser to the server (e.g., "<code>GET
/index.html HTTP/1.1</code>"). This does not
include any additional headers sent by the
- browser. This value has not been unescaped
+ browser. This value has not been unescaped
(decoded), unlike most other variables below.</dd>
<dt><code>REQUEST_URI</code></dt>
<dd>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
- <code>REQUEST_FILENAME</code> is referenced. Otherwise,
- such as when used in virtual host context, the same
+ been determined by the server at the time
+ <code>REQUEST_FILENAME</code> is referenced. Otherwise,
+ such as when used in virtual host context, the same
value as <code>REQUEST_URI</code>.</dd>
<dt><code>HTTPS</code></dt>
numerically compared to the <em>CondPattern</em>. True if
the <em>TestString</em> is numerically greater than or equal
to the <em>CondPattern</em>.</li>
-
+
<li>'<strong>-gt</strong>' (is numerically
<strong>g</strong>reater <strong>t</strong>han)<br />
The <em>TestString</em> is treated as an integer, and is
to the <em>CondPattern</em>. Avoid confusion with the
<strong>-l</strong> by using the <strong>-L</strong> or
<strong>-h</strong> variant.</li>
-
+
<li>'<strong>-lt</strong>' (is numerically
<strong>l</strong>ess <strong>t</strong>han)<br />
The <em>TestString</em> is treated as an integer, and is
RewriteRule.</p>
<note><title>What is matched?</title>
- <p>In <directive module="core">VirtualHost</directive> context,
+ <p>In <directive module="core">VirtualHost</directive> context,
The <em>Pattern</em> will initially be matched against the part of the
URL after the hostname and port, and before the query string (e.g. "/app1/index.html").</p>
<p>In <directive module="core">Directory</directive> and htaccess context,
- the <em>Pattern</em> will initially be matched against the
+ the <em>Pattern</em> will initially be matched against the
<em>filesystem</em> path, after removing the prefix that lead the server
- to the current <directive>RewriteRule</directive> (e.g. "app1/index.html"
+ to the current <directive>RewriteRule</directive> (e.g. "app1/index.html"
or "index.html" depending on where the directives are defined).</p>
-
+
<p>If you wish to match against the hostname, port, or query string, use a
<directive module="mod_rewrite">RewriteCond</directive> with the
<code>%{HTTP_HOST}</code>, <code>%{SERVER_PORT}</code>, or
per-directory prefix (which always is the same for a specific
directory) is automatically <em>removed</em> for the RewriteRule pattern matching
and automatically <em>added</em> after any relative (not starting with a
-slash or protocol name) substitution encounters the end of a rule set.
-See the <directive module="mod_rewrite">RewriteBase</directive>
-directive for more information regarding what prefix will be added back to
+slash or protocol name) substitution encounters the end of a rule set.
+See the <directive module="mod_rewrite">RewriteBase</directive>
+directive for more information regarding what prefix will be added back to
relative substutions.</li>
-<li> If you wish to match against the full URL-path in a per-directory
+<li> If you wish to match against the full URL-path in a per-directory
(htaccess) RewriteRule, use the <code>%{REQUEST_URI}</code> variable in
a <directive>RewriteCond</directive>.</li>
</tr>
<tr>
<td>cookie|CO=<em>NAME</em>:<em>VAL</em></td>
- <td>Sets a cookie in the client browser. Full syntax is:
+ <td>Sets a cookie in the client browser. Full syntax is:
CO=<em>NAME</em>:<em>VAL</em>:<em>domain</em>[:<em>lifetime</em>[:<em>path</em>[:<em>secure</em>[:<em>httponly</em>]]]] <em><a href="../rewrite/flags.html#flag_co">details ...</a></em>
</td>
</tr>
<tr>
<td>discardpath|DPI</td>
<td>Causes the PATH_INFO portion of the rewritten URI to be
- discarded. <em><a href="../rewrite/flags.html#flag_dpi">details
+ discarded. <em><a href="../rewrite/flags.html#flag_dpi">details
...</a></em></td>
</tr>
<tr>
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.</p>
-
+
<p>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
<p>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.</p>
-
+
</summary>
<seealso><module>mod_session_cookie</module></seealso>
<seealso><module>mod_session_crypto</module></seealso>
<section id="whatisasession"><title>What is a session?</title>
<p>At the core of the session interface is a table of key and value pairs
that are made accessible across browser requests.</p>
-
+
<p>These pairs can be set to any valid string, as needed by the
application making use of the session.</p>
-
+
</section>
<section id="whocanuseasession"><title>Who can use a session?</title>
<p>The session interface is primarily developed for the use by other
<p>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.</p>
-
+
<p>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.</p>
-
+
<p>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.</p>
-
+
<p>The <module>mod_session_dbd</module> module allows the storage of user
sessions within a SQL database via <module>mod_dbd</module>.</p>
</section> <!-- /serversession -->
-
+
<section id="browsersession"><title>Keeping sessions on the browser</title>
<p>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.</p>
-
+
<p>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.</p>
-
+
<p>The contents of the session however are exposed to the client, with a
corresponding risk of a loss of privacy. The
<module>mod_session_crypto</module> module can be configured to encrypt the
</section> <!-- /browsersession -->
<section id="basicexamples"><title>Basic Examples</title>
-
+
<p>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 <code>session</code>.</p>
-
+
<example><title>Browser based session</title>
Session On<br />
SessionCookieName session path=/<br />
following example shows how values can be injected into the session through
the use of a predetermined HTTP response header called
<code>X-Replace-Session</code>.</p>
-
+
<example><title>Writing to a session</title>
Session On<br />
SessionCookieName session path=/<br />
<p>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.</p>
-
+
<example><title>CGI to write to a session</title>
#!/bin/bash<br />
echo "Content-Type: text/plain"<br />
environment variable. By default, the session is kept private, so this
has to be explicitly turned on with the
<directive module="mod_session">SessionEnv</directive> directive.</p>
-
+
<example><title>Read from a session</title>
Session On<br />
SessionEnv On<br />
</section>
<section id="sessionprivacy"><title>Session Privacy</title>
-
+
<p>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.</p>
-
+
<p>The contents of the session can be optionally encrypted before being
placed on the browser using the <module>mod_session_crypto</module>
module.</p>
-
+
<example><title>Browser based encrypted session</title>
Session On<br />
SessionCryptoPassphrase secret<br />
SessionCookieName session path=/<br />
</example>
-
+
<p>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.</p>
-
+
<p>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 <module>mod_session_dbd</module> module.</p>
-
+
</section>
<section id="cookieprivacy"><title>Cookie Privacy</title>
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.</p>
-
+
<note type="warning"><title>Warning</title>
<p>Some of the HTTP cookie privacy features are either non-standard, or
are not implemented consistently across browsers. The session modules
<p>Standard cookie parameters can be specified after the name of the cookie,
as in the example below.</p>
-
+
<example><title>Setting cookie parameters</title>
Session On<br />
SessionCryptoPassphrase secret<br />
SessionCookieName session path=/private;domain=example.com;httponly;secure;<br />
</example>
-
+
<p>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 <directive module="mod_session_cookie">SessionCookieRemove</directive> directive.
AuthName realm<br />
...<br />
</example>
-
+
<p>See the <module>mod_auth_form</module> module for documentation and complete
examples.</p>
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.</p>
-
+
<p>Setting the maxage to zero disables session expiry.</p>
</usage>
</directivesynopsis>
<p>If set to <var>On</var>, the <directive>SessionEnv</directive> directive
causes the contents of the session to be written to a CGI environment
variable called <var>HTTP_SESSION</var>.</p>
-
+
<p>The string is written in the URL query format, for example:</p>
<example>
<p>The <directive>SessionHeader</directive> directive defines the name of an
HTTP response header which, if present, will be parsed and written to the
current session.</p>
-
+
<p>The header value is expected to be in the URL query format, for example:</p>
<example>
<code>key1=foo&key2=&key3=bar</code>
</example>
-
+
<p>Where a key is set to the empty string, that key will be removed from the
session.</p>
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.</p>
-
+
<note type="warning"><title>Warning</title>
<p>This directive has a similar purpose to the <var>path</var> attribute
in HTTP cookies, but should not be confused with this attribute. This
<p>This submodule of <module>mod_session</module> provides support for the
storage of user sessions on the remote browser within HTTP cookies.</p>
-
+
<p>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.</p>
-
+
<p>If session privacy is required, the <module>mod_session_crypto</module>
module can be used to encrypt the contents of the session before writing
the session to the client.</p>
-
+
<p>For more details on the session interface, see the documentation for
the <module>mod_session</module> module.</p>
-
+
</summary>
<seealso><module>mod_session</module></seealso>
<seealso><module>mod_session_crypto</module></seealso>
<seealso><module>mod_session_dbd</module></seealso>
<section id="basicexamples"><title>Basic Examples</title>
-
+
<p>To create a simple session and store it in a cookie called
<var>session</var>, configure the session as follows:</p>
-
+
<example><title>Browser based session</title>
Session On<br />
SessionCookieName session path=/<br />
</example>
-
+
<p>For more examples on how the session can be configured to be read
from and written to by a CGI application, see the
<module>mod_session</module> examples section.</p>
-
+
<p>For documentation on how the session can be used to store username
and password details, see the <module>mod_auth_form</module> module.</p>
optional attributes of an RFC2109 compliant cookie inside which the session will
be stored. RFC2109 cookies are set using the <code>Set-Cookie</code> HTTP header.
</p>
-
+
<p>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.
</p>
-
+
<example><title>Cookie with attributes</title>
Session On<br />
SessionCookieName session path=/private;domain=example.com;httponly;secure;version=1;<br />
optional attributes of an RFC2965 compliant cookie inside which the session will
be stored. RFC2965 cookies are set using the <code>Set-Cookie2</code> HTTP header.
</p>
-
+
<p>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.
</p>
-
+
<example><title>Cookie2 with attributes</title>
Session On<br />
SessionCookieName2 session path=/private;domain=example.com;httponly;secure;version=1;<br />
<usage>
<p>The <directive>SessionCookieRemove</directive> flag controls whether the cookies
containing the session will be removed from the headers during request processing.</p>
-
+
<p>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
<p>This submodule of <module>mod_session</module> 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.</p>
-
+
<p>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.</p>
-
+
<p>For more details on the session interface, see the documentation for
the <module>mod_session</module> module.</p>
-
+
</summary>
<seealso><module>mod_session</module></seealso>
<seealso><module>mod_session_cookie</module></seealso>
<seealso><module>mod_session_dbd</module></seealso>
<section id="basicusage"><title>Basic Usage</title>
-
+
<p>To create a simple encrypted session and store it in a cookie called
<var>session</var>, configure the session as follows:</p>
-
+
<example><title>Browser based encrypted session</title>
Session On<br />
SessionCookieName session path=/<br />
SessionCryptoPassphrase secret
</example>
-
+
<p>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.</p>
-
+
<p>If the encryption key is changed, sessions will be invalidated
automatically.</p>
-
+
<p>For documentation on how the session can be used to store username
and password details, see the <module>mod_auth_form</module> module.</p>
<p>The cipher can be set to <var>3des192</var> or <var>aes256</var> using the
<var>cipher</var> parameter as per the example below. If not set, the cipher defaults
to <var>aes256</var>.</p>
-
+
<example><title>Cipher</title>
SessionCryptoPassphrase secret cipher=aes256
</example>
<p>SQL based sessions are hidden from the browser, and so offer a measure of
privacy without the need for encryption.</p>
-
+
<p>Different webservers within a server farm may choose to share a database,
and so share sessions with one another.</p>
-
+
<p>For more details on the session interface, see the documentation for
the <module>mod_session</module> module.</p>
-
+
</summary>
<seealso><module>mod_session</module></seealso>
<seealso><module>mod_session_crypto</module></seealso>
<p>Before the <module>mod_session_dbd</module> module can be configured to maintain a
session, the <module>mod_dbd</module> module must be configured to make the various database queries
available to the server.</p>
-
+
<p>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.</p>
</section>
<section id="anonymous"><title>Anonymous Sessions</title>
-
+
<p>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.</p>
-
+
<p>To create a simple anonymous session and store it in a postgres database
table called <var>apachesession</var>, and save the session ID in a cookie
called <var>session</var>, configure the session as follows:</p>
-
+
<example><title>SQL based anonymous session</title>
Session On<br />
SessionDBDCookieName session path=/<br />
</example>
-
+
<p>For more examples on how the session can be configured to be read
from and written to by a CGI application, see the
<module>mod_session</module> examples section.</p>
-
+
<p>For documentation on how the session can be used to store username
and password details, see the <module>mod_auth_form</module> module.</p>
</section>
<section id="peruser"><title>Per User Sessions</title>
-
+
<p>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.</p>
-
+
<p>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
<module>mod_auth_form</module>.</p>
-
+
<p>To create a simple per user session and store it in a postgres database
table called <var>apachesession</var>, and with the session keyed to the
userid, configure the session as follows:</p>
-
+
<example><title>SQL based per user session</title>
Session On<br />
SessionDBDPerUser On<br />
</example>
-
+
</section>
<section id="housekeeping"><title>Database Housekeeping</title>
<p>Over the course of time, the database can be expected to start accumulating
expired sessions. At this point, the <module>mod_session_dbd</module> module
is not yet able to handle session expiry automatically.</p>
-
+
<note type="warning"><title>Warning</title>
<p>The administrator will need to set up an external process via cron to clean
out expired sessions.</p>
optional attributes of an RFC2965 compliant cookie inside which the session ID will
be stored. RFC2965 cookies are set using the <code>Set-Cookie2</code> HTTP header.
</p>
-
+
<p>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.
</p>
-
+
<example><title>Cookie2 with attributes</title>
Session On<br />
SessionDBDCookieName2 session path=/private;domain=example.com;httponly;secure;version=1;<br />
<code>User-Agent</code> HTTP request header. The following two
lines have the same effect:</p>
<example>
- BrowserMatchNoCase Robot is_a_robot<br />
- SetEnvIfNoCase User-Agent Robot is_a_robot<br />
+ BrowserMatchNoCase Robot is_a_robot<br />
+ SetEnvIfNoCase User-Agent Robot is_a_robot<br />
</example>
<p>Some additional examples:</p>
<li>An HTTP request header field (see <a
href="http://www.rfc-editor.org/rfc/rfc2616.txt">RFC2616</a>
for more information about these); for example: <code>Host</code>,
- <code>User-Agent</code>, <code>Referer</code>, and
+ <code>User-Agent</code>, <code>Referer</code>, and
<code>Accept-Language</code>. A regular expression may be
used to specify a set of request headers.</li>
<name>SetEnvIfNoCase</name>
<description>Sets environment variables based on attributes of the request
without respect to case</description>
-<syntax>SetEnvIfNoCase <em>attribute regex
+<syntax>SetEnvIfNoCase <em>attribute regex
[!]env-variable</em>[=<em>value</em>]
[[!]<em>env-variable</em>[=<em>value</em>]] ...</syntax>
<contextlist><context>server config</context>
<status>Extension</status>
<sourcefile>mod_so.c</sourcefile>
<identifier>so_module</identifier>
-<compatibility>This is a Base module (always included) on
+<compatibility>This is a Base module (always included) on
Windows</compatibility>
<summary>
<directivesynopsis>
<name>CheckSpelling</name>
-<description>Enables the spelling
+<description>Enables the spelling
module</description>
<syntax>CheckSpelling on|off</syntax>
<default>CheckSpelling Off</default>
<override>Options</override>
<usage>
- <p>When set, this directive limits the action of the spelling correction to lower/upper case changes.
+ <p>When set, this directive limits the action of the spelling correction to lower/upper case changes.
Other potential corrections are not performed.</p>
</usage>
<section id="envvars"><title>Environment Variables</title>
-<p>This module can be configured to provide several items of SSL information
+<p>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
-<directive>SSLOptions</directive> StdEnvVars, below.) The generated variables
+<directive>SSLOptions</directive> 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 <a
href="../ssl/ssl_compat.html">Compatibility</a> chapter for details on the
<dt><code>ENV:<em>variablename</em></code></dt>
<dd>This will expand to the standard environment
variable <em>variablename</em>.</dd>
-
+
<dt><code>HTTP:<em>headername</em></code></dt>
<dd>This will expand to the value of the request header with name
<em>headername</em>.</dd>
<p>When <module>mod_ssl</module> is built into Apache or at least
loaded (under DSO situation) additional functions exist for the <a
-href="mod_log_config.html#formats">Custom Log Format</a> of
+href="mod_log_config.html#formats">Custom Log Format</a> of
<module>mod_log_config</module>. First there is an
additional ``<code>%{</code><em>varname</em><code>}x</code>''
eXtension format function which can be used to expand any variables
<directivesynopsis>
<name>SSLPassPhraseDialog</name>
-<description>Type of pass phrase dialog for encrypted private
+<description>Type of pass phrase dialog for encrypted private
keys</description>
<syntax>SSLPassPhraseDialog <em>type</em></syntax>
<default>SSLPassPhraseDialog builtin</default>
dialog (i.e. when you use a single Pass Phrase for all N Private Key files
this Pass Phrase is queried only once).</p></li>
-<li><code>|/path/to/program [args...]</code>
+<li><code>|/path/to/program [args...]</code>
<p>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
<directivesynopsis>
<name>SSLRandomSeed</name>
-<description>Pseudo Random Number Generator (PRNG) seeding
+<description>Pseudo Random Number Generator (PRNG) seeding
source</description>
-<syntax>SSLRandomSeed <em>context</em> <em>source</em>
+<syntax>SSLRandomSeed <em>context</em> <em>source</em>
[<em>bytes</em>]</syntax>
<contextlist><context>server config</context></contextlist>
<directivesynopsis>
<name>SSLSessionCache</name>
-<description>Type of the global/inter-process SSL Session
+<description>Type of the global/inter-process SSL Session
Cache</description>
<syntax>SSLSessionCache <em>type</em></syntax>
<default>SSLSessionCache none</default>
...<br />
</VirtualHost>
</example>
-<p>In Apache 2.1 and later, <directive>SSLEngine</directive> can be set to
-<code>optional</code>. This enables support for
-<a href="http://www.ietf.org/rfc/rfc2817.txt">RFC 2817</a>, Upgrading to TLS
+<p>In Apache 2.1 and later, <directive>SSLEngine</directive> can be set to
+<code>optional</code>. This enables support for
+<a href="http://www.ietf.org/rfc/rfc2817.txt">RFC 2817</a>, Upgrading to TLS
Within HTTP/1.1. At this time no web browsers support RFC 2817.</p>
</usage>
</directivesynopsis>
<p>
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
+with conflicting settings (SSLFIPS on followed by SSLFIPS off or
similar). The mode applies to all SSL library operations.
</p>
<p>
<usage>
<p>
-This directive can be used to control which versions of the SSL protocol
+This directive can be used to control which versions of the SSL protocol
will be accepted in new connections.</p>
<p>
The available (case-insensitive) <em>protocol</em>s are:</p>
<li><code>SSLv3</code>
<p>
This is the Secure Sockets Layer (SSL) protocol, version 3.0, from
- the Netscape Corporation.
+ the Netscape Corporation.
It is the successor to SSLv2 and the predecessor to TLSv1. It's supported by
almost all popular browsers.</p></li>
<li><code>TLSv1</code>
<p>
This is the Transport Layer Security (TLS) protocol, version 1.0. It is the
- successor to SSLv3 and is defined in <a href="http://www.ietf.org/rfc/rfc2246.txt">RFC2246</a>.
+ successor to SSLv3 and is defined in <a href="http://www.ietf.org/rfc/rfc2246.txt">RFC2246</a>.
Which has been obsoleted by <a href="http://www.ietf.org/rfc/rfc4346.txt">RFC4346</a>.</p></li>
<li><code>All</code>
<p>
This is a shortcut for ``<code>+SSLv2 +SSLv3 +TLSv1</code>'' and a
convenient way for enabling all protocols except one when used in
- combination with the minus sign on a protocol as the example above
+ combination with the minus sign on a protocol as the example above
shows.</p></li>
</ul>
<example><title>Example</title>
<directivesynopsis>
<name>SSLCipherSuite</name>
-<description>Cipher Suite available for negotiation in SSL
+<description>Cipher Suite available for negotiation in SSL
handshake</description>
<syntax>SSLCipherSuite <em>cipher-spec</em></syntax>
<default>SSLCipherSuite DEFAULT (depends on OpenSSL version)</default>
<directivesynopsis>
<name>SSLCACertificatePath</name>
-<description>Directory of PEM-encoded CA Certificates for
+<description>Directory of PEM-encoded CA Certificates for
Client Auth</description>
<syntax>SSLCACertificatePath <em>directory-path</em></syntax>
<contextlist><context>server config</context>
<directivesynopsis>
<name>SSLCACertificateFile</name>
-<description>File of concatenated PEM-encoded CA Certificates
+<description>File of concatenated PEM-encoded CA Certificates
for Client Auth</description>
<syntax>SSLCACertificateFile <em>file-path</em></syntax>
<contextlist><context>server config</context>
Certificates of Certification Authorities (CA) whose <em>clients</em> 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
+preference. This can be used alternatively and/or additionally to
<directive module="mod_ssl">SSLCACertificatePath</directive>.</p>
<example><title>Example</title>
SSLCACertificateFile /usr/local/apache2/conf/ssl.crt/ca-bundle-client.crt
<directivesynopsis>
<name>SSLCADNRequestFile</name>
-<description>File of concatenated PEM-encoded CA Certificates
+<description>File of concatenated PEM-encoded CA Certificates
for defining acceptable CA names</description>
<syntax>SSLCADNRequestFile <em>file-path</em></syntax>
<contextlist><context>server config</context>
<directivesynopsis>
<name>SSLCADNRequestPath</name>
-<description>Directory of PEM-encoded CA Certificates for
+<description>Directory of PEM-encoded CA Certificates for
defining acceptable CA names</description>
<syntax>SSLCADNRequestPath <em>directory-path</em></syntax>
<contextlist><context>server config</context>
<directivesynopsis>
<name>SSLCARevocationPath</name>
-<description>Directory of PEM-encoded CA CRLs for
+<description>Directory of PEM-encoded CA CRLs for
Client Auth</description>
<syntax>SSLCARevocationPath <em>directory-path</em></syntax>
<contextlist><context>server config</context>
<directivesynopsis>
<name>SSLCARevocationFile</name>
-<description>File of concatenated PEM-encoded CA CRLs for
+<description>File of concatenated PEM-encoded CA CRLs for
Client Auth</description>
<syntax>SSLCARevocationFile <em>file-path</em></syntax>
<contextlist><context>server config</context>
<directivesynopsis>
<name>SSLVerifyDepth</name>
-<description>Maximum depth of CA Certificates in Client
+<description>Maximum depth of CA Certificates in Client
Certificate verification</description>
<syntax>SSLVerifyDepth <em>number</em></syntax>
<default>SSLVerifyDepth 1</default>
<directivesynopsis>
<name>SSLRequireSSL</name>
-<description>Deny access when SSL is not used for the
+<description>Deny access when SSL is not used for the
HTTP request</description>
<syntax>SSLRequireSSL</syntax>
<contextlist><context>directory</context>
<directivesynopsis>
<name>SSLRequire</name>
-<description>Allow access only when an arbitrarily complex
+<description>Allow access only when an arbitrarily complex
boolean expression is true</description>
<syntax>SSLRequire <em>expression</em></syntax>
<contextlist><context>directory</context>
</note>
<example><title>Example</title>
SSLProxyMachineCertificatePath /usr/local/apache2/conf/proxy.crt/
-</example>
-</usage>
+</example>
+</usage>
</directivesynopsis>
<directivesynopsis>
<name>SSLProxyCipherSuite</name>
-<description>Cipher Suite available for negotiation in SSL
+<description>Cipher Suite available for negotiation in SSL
proxy handshake</description>
<syntax>SSLProxyCipherSuite <em>cipher-spec</em></syntax>
<default>SSLProxyCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP</default>
</directivesynopsis>
<directivesynopsis>
<name>SSLProxyCACertificatePath</name>
-<description>Directory of PEM-encoded CA Certificates for
+<description>Directory of PEM-encoded CA Certificates for
Remote Server Auth</description>
<syntax>SSLProxyCACertificatePath <em>directory-path</em></syntax>
<contextlist><context>server config</context>
<directivesynopsis>
<name>SSLProxyCACertificateFile</name>
-<description>File of concatenated PEM-encoded CA Certificates
+<description>File of concatenated PEM-encoded CA Certificates
for Remote Server Auth</description>
<syntax>SSLProxyCACertificateFile <em>file-path</em></syntax>
<contextlist><context>server config</context>
Certificates of Certification Authorities (CA) whose <em>remote servers</em> 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
+preference. This can be used alternatively and/or additionally to
<directive module="mod_ssl">SSLProxyCACertificatePath</directive>.</p>
<example><title>Example</title>
SSLProxyCACertificateFile /usr/local/apache2/conf/ssl.crt/ca-bundle-remote-server.crt
<directivesynopsis>
<name>SSLProxyCARevocationPath</name>
-<description>Directory of PEM-encoded CA CRLs for
+<description>Directory of PEM-encoded CA CRLs for
Remote Server Auth</description>
<syntax>SSLProxyCARevocationPath <em>directory-path</em></syntax>
<contextlist><context>server config</context>
<directivesynopsis>
<name>SSLProxyCARevocationFile</name>
-<description>File of concatenated PEM-encoded CA CRLs for
+<description>File of concatenated PEM-encoded CA CRLs for
Remote Server Auth</description>
<syntax>SSLProxyCARevocationFile <em>file-path</em></syntax>
<contextlist><context>server config</context>
<li>The current hosts and requests being processed (*)</li>
</ul>
- <p>The lines marked "(*)" are only available if
- <directive module="core">ExtendedStatus</directive>
+ <p>The lines marked "(*)" are only available if
+ <directive module="core">ExtendedStatus</directive>
is <code>On</code>. In version 2.3.6, loading mod_status will
toggle <directive module="core">ExtendedStatus</directive> On
by default.</p>
accessing the page
<code>http://your.server.name/server-status?auto</code>. This
is useful when automatically run, see the Perl program
- <code>log_server_status</code>, which you will find in the
+ <code>log_server_status</code>, which you will find in the
<code>/support</code> directory of your Apache HTTP Server installation.</p>
<note>
<section id="troubleshoot">
<title>Using server-status to troubleshoot</title>
-
+
<p>The <code>server-status</code> 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
<usage>
<p>The <directive>Substitute</directive> directive specifies a
search and replace pattern to apply to the response body.</p>
-
+
<p>The meaning of the pattern can be modified by using any
combination of these flags:</p>
-
+
<dl>
<dt><code>i</code></dt>
<dd>Perform a case-insensitive match.</dd>
that the result of one substitution will ever match a pattern
or regex of a subsequent one.</dd>
</dl>
-
+
<example><title>Example</title>
<Location />
<indent>
</indent>
</Location>
</example>
-
+
<p>If either the pattern or the substitution contain a slash
character then an alternative delimiter should be used:</p>
-
+
<example><title>Example of using an alternate delimiter</title>
<Location />
<indent>
directive was present.</p>
<note><title>Merging details</title>
- <p> Lists of specific enabled and disabled users are replaced, not merged,
+ <p> Lists of specific enabled and disabled users are replaced, not merged,
from global to virtual host scope</p></note>
</usage>
<p>The domain string <strong>must</strong> begin with a dot, and
<strong>must</strong> include at least one embedded dot. That is,
- <code>.example.com</code> is legal, but <code>www.example.com</code> and
+ <code>.example.com</code> is legal, but <code>www.example.com</code> and
<code>.com</code> are not.</p>
<note>Most browsers in use today will not allow cookies to be set
- for a two-part top level domain, such as <code>.co.uk</code>,
+ for a two-part top level domain, such as <code>.co.uk</code>,
although such a domain ostensibly fulfills the requirements
- above.<br />
-
+ above.<br />
+
These domains are equivalent to top level domains such as
<code>.com</code>, 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 <code>.example.co.uk</code>).
- </note>
+ </note>
<example>
CookieDomain .example.com
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
- <module>mod_usertrack</module> will <strong>not</strong>
+ <module>mod_usertrack</module> will <strong>not</strong>
activate cookies. </p>
<example>
</IfVersion>
</example>
- <p>Besides the numerical comparison it is possible to match a
- <glossary ref="regex">regular expression</glossary>
+ <p>Besides the numerical comparison it is possible to match a
+ <glossary ref="regex">regular expression</glossary>
against the httpd version. There are two ways to write it:</p>
<table style="zebra" border="1">
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.</p>
-
+
<note><title>Note</title>
<p>If <module>mod_alias</module> or <module>mod_userdir</module> are
used for translating URIs to filenames, they will override the
</summary>
<seealso><directive module="core">UseCanonicalName</directive></seealso>
-<seealso><a href="../vhosts/mass.html">Dynamically configured mass
+<seealso><a href="../vhosts/mass.html">Dynamically configured mass
virtual hosting</a></seealso>
<section id="interpol">
<tr><td><code>%N.M</code></td>
<td>insert (part of) the name</td></tr>
-
+
</table>
<p><code>N</code> and <code>M</code> are used to specify
<code>http://www.example.com/directory/file.html</code> will be
satisfied by the file
<code>/usr/local/apache/vhosts/www.example.com/directory/file.html</code>.
- </p>
+ </p>
<p>For a very large number of virtual hosts it is a good idea
to arrange the files to reduce the size of the
<code>http://www.domain.example.com/directory/file.html</code>
will be satisfied by the file
<code>/usr/local/apache/vhosts/domain.example/directory/file.html</code>.</p>
-
+
<p>The <directive module="mod_log_config">LogFormat</directive>
directives <code>%V</code> and <code>%A</code> are useful
in conjunction with this module.</p>
value of the server name. The result of expanding
<em>interpolated-directory</em> is used as the root of the
document tree in a similar manner to the <directive
- module="core">DocumentRoot</directive> directive's argument.
+ module="core">DocumentRoot</directive> directive's argument.
If <em>interpolated-directory</em> is <code>none</code> then
- <directive>VirtualDocumentRoot</directive> is turned off. This directive
+ <directive>VirtualDocumentRoot</directive> is turned off. This directive
cannot be used in the same context as <directive
module="mod_vhost_alias">VirtualDocumentRootIP</directive>.</p>
<usage>
<p>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,
+ create core files in the working directory of the crashing process,
<directive>CoreDumpDirectory</directive> is necessary to change working
- directory from the default <directive module="core">ServerRoot</directive>
+ directory from the default <directive module="core">ServerRoot</directive>
directory, which should not be writable by the user the server runs as.</p>
- <p>If you want a core dump for debugging, you can use this directive to
+ <p>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.</p>
-
+
<note><title>Core Dumps on Linux</title>
<p>If Apache httpd starts as root and switches to another user, the
Linux kernel <em>disables</em> core dumps even if the directory is
</note>
<note><title>Specific signals</title>
- <p><directive>CoreDumpDirectory</directive> processing only occurs for
- a select set of fatal signals: SIGFPE, SIGILL, SIGABORT,
+ <p><directive>CoreDumpDirectory</directive> processing only occurs for
+ a select set of fatal signals: SIGFPE, SIGILL, SIGABORT,
SIGSEGV, and SIGBUS.</p>
<p>On some operating systems, SIGQUIT also results in a core dump but
does not go through <directive>CoreDumpDirectory</directive> or
configured with the <code>--enable-exception-hook</code> option. It
enables a hook that allows external modules to plug in and do something
after a child crashed.</p>
-
+
<p>There are already two modules, <code>mod_whatkilledus</code> and
<code>mod_backtrace</code> that make use of this hook. Please have a
look at Jeff Trawick's <a
<usage>
<p>The <directive>GracefulShutdownTimeout</directive> specifies
- how many seconds after receiving a "graceful-stop" signal, a
+ how many seconds after receiving a "graceful-stop" signal, a
server should continue to run, handling the existing connections.</p>
<p>Setting this value to zero means that the server will wait
Listen [2001:db8::a00:20ff:fea7:ccea]:80
</example>
- <p>The optional <var>protocol</var> argument is not required for most
- configurations. If not specified, <code>https</code> is the default for
- port 443 and <code>http</code> the default for all other ports. The
+ <p>The optional <var>protocol</var> argument is not required for most
+ configurations. If not specified, <code>https</code> is the default for
+ port 443 and <code>http</code> 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
+ to apply protocol specific optimizations with the
<directive module="core">AcceptFilter</directive> directive.</p>
- <p>You only need to set the protocol if you are running on non-standard
+ <p>You only need to set the protocol if you are running on non-standard
ports. For example, running an <code>https</code> site on port 8443:</p>
<example>
<p>Maximum number of idle threads. Different MPMs deal with this
directive differently.</p>
- <p>For <module>worker</module>, the default is
+ <p>For <module>worker</module>, the default is
<code>MaxSpareThreads 250</code>. This MPM deals with idle threads
on a server-wide basis. If there are too many idle threads in the
server then child processes are killed until the number of idle
<usage>
<p>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 conections
+ default value on high speed, high latency conections
(<em>i.e.</em>, 100ms or so, such as transcontinental fast pipes).</p>
<p>If set to the value of <code>0</code>, the server will use the
there is usually little reason to adjust this parameter.</p>
<p>The default value differs from MPM to MPM. <module>worker</module>
- defaults to <code>StartServers 3</code>; <module>prefork</module>
+ defaults to <code>StartServers 3</code>; <module>prefork</module>
defaults to <code>5</code>; <module>mpmt_os2</module> defaults to
<code>2</code>.</p>
</usage>
<directivesynopsis>
<name>ThreadStackSize</name>
-<description>The size in bytes of the stack used by threads handling
-client connections</description>
+<description>The size in bytes of the stack used by threads handling
+client connections</description>
<syntax>ThreadStackSize <var>size</var></syntax>
<default>65536 on NetWare; varies on other operating systems</default>
<contextlist><context>server config</context></contextlist>
<compatibility>Available in Apache HTTP Server 2.1 and later</compatibility>
<usage>
- <p>The <directive>ThreadStackSize</directive> directive sets the
+ <p>The <directive>ThreadStackSize</directive> 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
+ 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:</p>
<ul>
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 <directive>ThreadStackSize</directive> to a
- value higher than the operating system default. This type of
- adjustment is necessary only if the provider of the third-party
+ resolved by setting <directive>ThreadStackSize</directive> 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.</li>
- <li>On platforms where the default thread stack size is
+ <li>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 <directive>ThreadStackSize</directive> is
the current <directive>ThreadStackSize</directive> setting.</li>
<li>On Linux, this directive can only be used to increase the default
- stack size, as the underlying system call uses the value as a
- <em>minimum</em> stack size. The (often large) soft limit for
- <code>ulimit -s</code> (8MB if unlimited) is used as the default stack
+ stack size, as the underlying system call uses the value as a
+ <em>minimum</em> stack size. The (often large) soft limit for
+ <code>ulimit -s</code> (8MB if unlimited) is used as the default stack
size.</li>
</ul>
involves spawning children as required to ensure there are always
<directive module="mpm_common">StartServers</directive> processes
accepting connections.</p>
-
+
<p>Each child process consists of a 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
<seealso><a href="../bind.html">Setting which addresses and ports Apache HTTP Server uses</a></seealso>
<section id="how-it-works"><title>How it Works</title>
- <p>A single control process (the parent) is responsible for launching
+ <p>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 <directive
+ threads as specified in the <directive
module="mpm_common">ThreadsPerChild</directive> directive, as well
as a listener thread which listens for connections and passes them
to a server thread for processing when they arrive.</p>
<p>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
+ and can only be changed by fully stopping the server and then
starting it again. <directive module="mpm_common">ServerLimit
- </directive> is a hard limit on the number of active child
- processes, and must be greater than or equal to the
+ </directive> is a hard limit on the number of active child
+ processes, and must be greater than or equal to the
<directive module="mpm_common">MaxRequestWorkers</directive>
directive divided by the <directive module="mpm_common">
- ThreadsPerChild</directive> directive.
+ ThreadsPerChild</directive> directive.
<directive module="mpm_common">ThreadLimit</directive> is a hard
limit of the number of server threads, and must be greater than
- or equal to the <directive
+ or equal to the <directive
module="mpm_common">ThreadsPerChild</directive> directive.</p>
- <p>In addition to the set of active child processes, there may
+ <p>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 <directive
- module="mpm_common">MaxRequestWorkers</directive> terminating processes
- may be present, though the actual number can be expected to be
- much smaller. This behavior can be avoided by disabling the
+ connection. Up to <directive
+ module="mpm_common">MaxRequestWorkers</directive> 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:</p>
<li>The server can be better customized for the needs of the
particular site. For example, sites that need a great deal of
- scalability can choose to use a threaded MPM like
+ scalability can choose to use a threaded MPM like
<module>worker</module> or <module>event</module>, while sites requiring
stability or compatibility with older software can use a
<module>prefork</module>.</li>
<columnspec><column width=".2"/><column width=".2"/></columnspec>
<tr><td>Netware</td><td><module>mpm_netware</module></td></tr>
<tr><td>OS/2</td><td><module>mpmt_os2</module></td></tr>
-<tr><td>Unix</td><td><module>prefork</module>, <module>worker</module>, or
+<tr><td>Unix</td><td><module>prefork</module>, <module>worker</module>, or
<module>event</module>, depending on platform capabilities</td></tr>
<tr><td>Windows</td><td><module>mpm_winnt</module></td></tr>
</table>
<p>On Unix and similar platforms, MPMs can be built as DSO modules and
dynamically loaded into the server in the same manner as other DSO
modules. Building MPMs as DSO modules allows the MPM to be changed by
- updating the <directive module="mod_so">LoadModule</directive> directive
+ updating the <directive module="mod_so">LoadModule</directive> directive
for the MPM instead of by rebuilding the server.</p>
<p>This feature is enabled using the
<dd>It is now possible to specify <directive module="core"
>KeepAliveTimeout</directive> in milliseconds.
</dd>
-
+
<dt>Loadable MPMs</dt>
- <dd>Multiple MPMs can now be built as loadable modules at compile time.
+ <dd>Multiple MPMs can now be built as loadable modules at compile time.
The MPM of choice can be configured at run time.</dd>
-
+
<dt>Per-module and per-directory LogLevel configuration</dt>
<dd>The <directive module="core">LogLevel</directive> can now be
configured per module and per directory. New levels <code>trace1</code>
<dt>Event MPM</dt>
<dd>The Event MPM is no longer experimental but is now fully supported.</dd>
-
+
<dt>Asynchronous support</dt>
<dd>Better support for asynchronous read/write for supporting MPMs and
platforms.</dd>
<dt>Per-request configuration sections</dt>
- <dd><<directive module="core">If</directive>> sections can be used to
+ <dd><<directive module="core">If</directive>> sections can be used to
set the configuration based on per-request criteria</dd>
<dt>NameVirtualHost directive</dt>
<dd>Convert response body into an RFC2397 data URL</dd>
<dt><module>mod_lua</module></dt>
- <dd>Embeds the <a href="http://www.lua.org/">Lua</a> language into httpd,
+ <dd>Embeds the <a href="http://www.lua.org/">Lua</a> language into httpd,
for configuration and small business logic functions.</dd>
<dt><module>mod_proxy_express</module></dt>
certificate. The default responder is configurable, along with
the decision on whether to prefer the responder designated in
the client certificate itself.</dd>
-
- <dd><module>mod_ssl</module> now also supports OCSP stapling, where the
- server pro-actively obtains an OCSP verification of its certificate and
+
+ <dd><module>mod_ssl</module> now also supports OCSP stapling, where the
+ server pro-actively obtains an OCSP verification of its certificate and
transmits that to the client during the handshake. </dd>
-
- <dd><module>mod_ssl</module> can now be configured to share SSL Session
+
+ <dd><module>mod_ssl</module> can now be configured to share SSL Session
data between servers through memcached</dd>
-
+
<dt><module>mod_proxy</module></dt>
<dd>The <directive module="mod_proxy">ProxyPass</directive> directive
<dt><module>mod_cgi</module>, <module>mod_include</module>,
<module>mod_isapi</module>, ...</dt>
- <dd>Translation of headers to environment variables is more strict than
+ <dd>Translation of headers to environment variables is more strict than
before to mitigate some possible cross-site-scripting attacks via header
injection. Headers containing invalid characters (including underscores)
are now silently dropped. <a href="env.html">Environment Variables
<module>mod_ssl</module>.</dd>
<dt>Authorization Logic Containers</dt>
-
+
<dd>Authorization modules now register as a provider, via
ap_register_auth_provider(), to support advanced authorization logic,
such as <directive module="mod_authz_core" type="section"
supported.</dd>
<dt>Cache Status Hook Added</dt>
-
+
<dd>The <module>mod_cache</module> module now includes a new
<code>cache_status</code> hook, which is called when the caching
decision becomes known. A default implementation is provided
<title>Requirements</title>
- <p>Apache 2.0 is designed to run on NetWare 6.0 service pack 3
+ <p>Apache 2.0 is designed to run on NetWare 6.0 service pack 3
and above. If you are running a service pack less
- than SP3, you must install the latest
+ than SP3, you must install the latest
<a href="http://developer.novell.com/ndk/libc.htm">NetWare Libraries
for C (LibC)</a>.</p>
<p>Apache 2.0 for NetWare can also be run in a NetWare 5.1 environment
as long as the latest service pack or the latest version
of the <a href="http://developer.novell.com/ndk/libc.htm">NetWare Libraries
- for C (LibC)</a> has been installed . <strong>WARNING:</strong> Apache 2.0
+ for C (LibC)</a> has been installed . <strong>WARNING:</strong> Apache 2.0
for NetWare has not been targeted for or tested in this environment.</p>
</section>
will list the current release, any more recent alpha or
beta-test releases, together with details of mirror web and
anonymous ftp sites. Binary builds of the latest releases of
- Apache 2.0 for NetWare can be downloaded from
+ Apache 2.0 for NetWare can be downloaded from
<a href="http://www.apache.org/dist/httpd/binaries/netware">here</a>.</p>
</section>
<title>Installing Apache for NetWare</title>
<p>There is no Apache install program for NetWare currently. If you
- are building Apache 2.0 for NetWare from source, you will need to
+ are building Apache 2.0 for NetWare from source, you will need to
copy the files over to the server manually.</p>
<p>Follow these steps to install Apache on NetWare from the
<li>Create a directory under <code>SYS:/APACHE2</code>
called <code>BIN</code></li>
- <li>Copy <code>HTDIGEST.NLM</code>, <code>HTPASSWD.NLM</code>,
+ <li>Copy <code>HTDIGEST.NLM</code>, <code>HTPASSWD.NLM</code>,
<code>HTDBM.NLM</code>, <code>LOGRES.NLM</code>, <code>ROTLOGS.NLM</code>
to <code>SYS:/APACHE2/BIN</code></li>
<code>SYS:/APACHE2/CONF</code> directory and rename to
<code>HTTPD.CONF</code></li>
- <li>Copy the <code>MIME.TYPES</code>, <code>CHARSET.CONV</code> and
+ <li>Copy the <code>MIME.TYPES</code>, <code>CHARSET.CONV</code> and
<code>MAGIC</code> files to <code>SYS:/APACHE2/CONF</code> directory</li>
<li>Copy all files and subdirectories in <code>\HTTPD-2.0\DOCS\ICONS</code>
<p>Apache may be installed to other volumes besides the default <code>SYS</code> volume.</p>
<p>During the build process, adding the keyword "install" to the makefile command line
- will automatically produce a complete distribution package under the subdirectory
- <code>DIST</code>. Install Apache by simply copying the distribution that was produced
- by the makfiles to the root of a NetWare volume (see: <a href="#comp">Compiling Apache for
+ will automatically produce a complete distribution package under the subdirectory
+ <code>DIST</code>. Install Apache by simply copying the distribution that was produced
+ by the makfiles to the root of a NetWare volume (see: <a href="#comp">Compiling Apache for
NetWare</a> below).</p>
</section>
<p>Apache 2.0 for NetWare includes a set of command line directives that can
be used to modify or display information about the running instance of the
- web server. These directives are only available while Apache is running. Each
+ web server. These directives are only available while Apache is running. Each
of these directives must be preceded by the keyword <code>APACHE2</code>.</p>
<dl>
<dt>SETTINGS</dt>
<dd>Enables or disables the thread status display
- on the console. When enabled, the state of each running threads is displayed
+ on the console. When enabled, the state of each running threads is displayed
on the Apache console screen.</dd>
<dt>SHUTDOWN</dt>
<title>Configuring Apache for NetWare</title>
<p>Apache is configured by reading configuration files usually stored
- in the <code>conf</code> directory. These are the same as files used
+ in the <code>conf</code> directory. These are the same as files used
to configure the Unix version, but there are a few different directives for
Apache on NetWare. See the <a href="../">Apache
documentation</a> for all the available directives.</p>
</li>
<li>
- <p>The directives that accept filenames as arguments must use
- NetWare filenames instead of Unix names. However, because Apache
- uses Unix-style names internally, forward slashes must be used
- rather than backslashes. It is recommended that all rooted file paths
- begin with a volume name. If omitted, Apache will assume the
+ <p>The directives that accept filenames as arguments must use
+ NetWare filenames instead of Unix names. However, because Apache
+ uses Unix-style names internally, forward slashes must be used
+ rather than backslashes. It is recommended that all rooted file paths
+ begin with a volume name. If omitted, Apache will assume the
<code>SYS:</code> volume which may not be correct.</p>
</li>
<title>Compiling Apache for NetWare</title>
- <p>Compiling Apache requires MetroWerks CodeWarrior 6.x or higher. Once
- Apache has been built, it can be installed to the root of any NetWare
+ <p>Compiling Apache requires MetroWerks CodeWarrior 6.x or higher. Once
+ Apache has been built, it can be installed to the root of any NetWare
volume. The default is the <code>sys:/Apache2</code> directory.</p>
<p>Before running the server you must fill out the <code>conf</code>
for example:
<example>Set ZLIBSDK=D:\NOVELL\zlib</example>
</li>
-
+
<li>Set the environment variable <code>PCRESDK</code> to the location
where you installed the source code for the PCRE Library, for example:
<example>Set PCRESDK=D:\NOVELL\pcre</example>
<li>Change directory to <code>\httpd-2.0</code> and build the prebuild utilities
by running "<code>gmake -f nwgnumakefile prebuild</code>". This target will create
- the directory <code>\httpd-2.0\nwprebuild</code> and copy each of the utilities
+ the directory <code>\httpd-2.0\nwprebuild</code> and copy each of the utilities
to this location that are necessary to complete the following build steps.
</li>
- <li>Copy the files <code>\httpd-2.0\nwprebuild\GENCHARS.nlm</code> and
+ <li>Copy the files <code>\httpd-2.0\nwprebuild\GENCHARS.nlm</code> and
<code>\httpd-2.0\nwprebuild\DFTABLES.nlm</code> to the <code>SYS:</code> volume of a
NetWare server and run them using the following commands:
<example>
<title>Additional environment variable options</title>
<ul>
- <li>To build all of the experimental modules, set the environment
+ <li>To build all of the experimental modules, set the environment
variable <code>EXPERIMENTAL</code>:
<example>Set EXPERIMENTAL=1</example>
</li>
<title>Building mod_ssl for the NetWare platform</title>
- <p>By default Apache for NetWare uses the built-in module
+ <p>By default Apache for NetWare uses the built-in module
<module>mod_nw_ssl</module> to provide SSL services. This module
simply enables the native SSL services implemented in NetWare OS
to handle all encryption for a given port. Alternatively, mod_ssl
can also be used in the same manner as on other platforms.</p>
<p>Before mod_ssl can be built for the NetWare platform, the OpenSSL
- libraries must be provided. This can be done through the following
+ libraries must be provided. This can be done through the following
steps:</p>
<ul>
page (older 0.9.7 versions need to be patched and are therefore not
recommended).</li>
- <li>Edit the file <code>NetWare/set_env.bat</code> and modify any
- tools and utilities paths so that they correspond to your build
+ <li>Edit the file <code>NetWare/set_env.bat</code> and modify any
+ tools and utilities paths so that they correspond to your build
environment.</li>
<li>From the root of the OpenSSL source directory, run the following
</example>
For performance reasons you should enable to build with ASM code.
Download NASM from the <a href="http://nasm.sourceforge.net/">SF site</a>.
- Then configure OpenSSL to use ASM code:
+ Then configure OpenSSL to use ASM code:
<example>
Netware\build netware-libc nw-nasm enable-mdc2 enable-md5
</example>
a newer or different version of the Platform SDK.</p>
<p>To use Visual C++ 6.0 or 7.0 (Studio 2000 .NET), the Platform SDK
- environment must be prepared using the <code>setenv.bat</code>
+ environment must be prepared using the <code>setenv.bat</code>
script (installed by the Platform SDK) before starting the command
line build or launching the msdev/devenv GUI environment. Installing
the Platform SDK for Visual Studio Express versions (2003 and later)
<p>Several steps recommended here require a perl interpreter during
the build preparation process, but it is otherwise not required.</p>
-
+
<p>To install Apache within the build system, several files are
modified using the <code>awk.exe</code> utility. awk was chosen since
it is a very small download (compared with Perl or WSH/VB) and
awk.exe is in your system path.</note>
<note>Also note that if you are using Cygwin tools
- (<a href="http://www.cygwin.com/">http://www.cygwin.com/</a>)
- the awk utility is named <code>gawk.exe</code> and that the file
+ (<a href="http://www.cygwin.com/">http://www.cygwin.com/</a>)
+ the awk utility is named <code>gawk.exe</code> and that the file
<code>awk.exe</code> is really a symlink to the <code>gawk.exe</code>
- file. The Windows command shell does not recognize symlinks, and
- because of this building InstallBin will fail. A workaround is
- to delete <code>awk.exe</code> from the cygwin installation and
+ file. The Windows command shell does not recognize symlinks, and
+ because of this building InstallBin will fail. A workaround is
+ to delete <code>awk.exe</code> from the cygwin installation and
copy <code>gawk.exe</code> to <code>awk.exe</code>. Also note the
cygwin/mingw ports of gawk 3.0.x were buggy, please upgrade to 3.1.x
before attempting to use any gawk port.</note>
<p>[Optional] zlib library (for <module>mod_deflate</module>)</p>
<p>Zlib must be installed into a <code>srclib</code> subdirectory named
- <code>zlib</code>. This must be built in-place. Zlib can be obtained
+ <code>zlib</code>. This must be built in-place. Zlib can be obtained
from <a href="http://www.zlib.net/">http://www.zlib.net/</a> -- the
- <module>mod_deflate</module> is confirmed to work correctly with
+ <module>mod_deflate</module> is confirmed to work correctly with
version 1.2.3.</p>
<example>
software. BEFORE using any encryption software, please check your
country's laws, regulations and policies concerning the import,
possession, or use, and re-export of encryption software, to see
- if this is permitted. See
+ if this is permitted. See
<a href="http://www.wassenaar.org/">http://www.wassenaar.org/</a>
for more information.</note>
<p>Configuring and building OpenSSL requires perl to be installed.</p>
- <p>OpenSSL must be installed into a <code>srclib</code> subdirectory
- named <code>openssl</code>, obtained from
+ <p>OpenSSL must be installed into a <code>srclib</code> subdirectory
+ named <code>openssl</code>, obtained from
<a href="http://www.openssl.org/source/"
- >http://www.openssl.org/source/</a>, in order to compile
+ >http://www.openssl.org/source/</a>, in order to compile
<module>mod_ssl</module> or the <code>abs.exe</code> project, which
- is ab.c with SSL support enabled. To prepare OpenSSL to be linked
+ is ab.c with SSL support enabled. To prepare OpenSSL to be linked
to Apache mod_ssl or abs.exe, and disable patent encumbered features
in OpenSSL, you might use the following build commands:</p>
<example>
- perl Configure no-rc5 no-idea enable-mdc2 enable-zlib VC-WIN32
+ perl Configure no-rc5 no-idea enable-mdc2 enable-zlib VC-WIN32
-Ipath/to/srclib/zlib -Lpath/to/srclib/zlib<br />
ms\do_masm.bat<br />
nmake -f ms\ntdll.mak
load the zlib dll. Note the suggested patch enables the -L flag to
work with windows builds, corrects the name of zdll.lib and ensures
.pdb files are generated for troubleshooting. If the assembler is
- not installed, you would add no-asm above and use ms\do_ms.bat
+ not installed, you would add no-asm above and use ms\do_ms.bat
instead of the ms\do_masm.bat script.</note>
</li>
step the code to find bugs and track down problems.</p>
<p>You can add your apr-util dbd and dbm provider choices with the
- additional make (environment) variables DBD_LIST and DBM_LIST,
+ additional make (environment) variables DBD_LIST and DBM_LIST,
see the comments about [Optional] Database libraries, above.
Review the initial comments in Makefile.win for additional options
that can be provided when invoking the build.</p>
<p>Visual Studio 2002 (.NET) and later users should also use the Build
menu, Configuration Manager dialog to uncheck both the <code>Debug</code>
- and <code>Release</code> Solution modules <code>abs</code>,
+ and <code>Release</code> Solution modules <code>abs</code>,
<module>mod_deflate</module> and <module>mod_ssl</module> components, as
well as every component starting with <code>apr_db*</code>. These modules
are built by invoking <code>nmake</code>, or the IDE directly with the
<module>mod_deflate</module>. The .mak files also support a broader
range of C++ tool chain distributions, such as Visual Studio Express.</p>
- <p>You must first build all projects in order to create all dynamic
- auto-generated targets, so that dependencies can be parsed correctly.
+ <p>You must first build all projects in order to create all dynamic
+ auto-generated targets, so that dependencies can be parsed correctly.
Build the entire project from within the Visual Studio 6.0 (98) IDE,
using the <code>BuildAll</code> target, then use the Project Menu Export
for all makefiles (checking on "with dependencies".) Run the following
a <code>sysincl.dat</code> file, which lists all exceptions. Update
this file (including both forward and backslashed paths, such as both
<code>sys/time.h</code> and <code>sys\time.h</code>) to ignore such
- newer dependencies. Including local-install paths in a distributed
+ newer dependencies. Including local-install paths in a distributed
<code>.mak</code> file will cause the build to fail completely.</p>
<p>If you contribute back a patch that revises project files, we
<p>This document explains how to install, configure and run
Apache 2.3 under Microsoft Windows. If you have questions after
reviewing the documentation (and any event and error logs), you
- should consult the peer-supported
+ should consult the peer-supported
<a href="http://httpd.apache.org/userslist.html">users' mailing
list</a>.</p>
<p>There is a choice between an *-openssl-*.msi flavor and
a *-no_ssl.msi flavor. The *-openssl-*.msi flavor is distributed
- by the Apache Software Foundation under ECCN 5D002 pursuant to
+ by the Apache Software Foundation under ECCN 5D002 pursuant to
US Export Law license exception TSU. This law may or may not
apply to your circumstance, please review the httpd README as
well as the <a href="http://www.apache.org/licenses/exports/">ASF
<li><p><strong>Where to install.</strong> The default path is
<code>C:\Program Files\Apache Software Foundation</code>
- under which a directory called
+ under which a directory called
<code>Apache2.3</code> will be created by default.</p></li>
</ol>
<p>The installation options above can be customized by users familiar
with msiexec.exe options and silent installation. The actual installer
- sources are available in the httpd/httpd/win32-msi/ tree of the httpd
+ sources are available in the httpd/httpd/win32-msi/ tree of the httpd
project subversion respository. For reference, some of the more common
variables which may be modified are;</p>
<li><code>SetupType</code> (default "Typical")</li>
</ul>
- <p>The installation level of various features, which may be individually
+ <p>The installation level of various features, which may be individually
toggled, include;</p>
<ul>
<li><p>The directives that accept filenames as arguments must use
Windows filenames instead of Unix ones. However, because Apache
may interpret backslashes as an "escape character" sequence, you
- should consistently use forward slashes in path names, not
+ should consistently use forward slashes in path names, not
backslashes. Drive letters can be used; if omitted, the drive
of the SystemRoot directive (or -d command line option) becomes
the default.</p></li>
<dt><code>graceful-stop</code></dt>
-<dd>Gracefully stops the Apache <program>httpd</program> daemon.
-This differs from a normal stop in that currently open connections are not
-aborted. A side effect is that old log files will not be closed immediately.
+<dd>Gracefully stops the Apache <program>httpd</program> daemon.
+This differs from a normal stop in that currently open connections are not
+aborted. A side effect is that old log files will not be closed immediately.
This is equivalent to <code>apachectl -k graceful-stop</code>.</dd>
<dt><code>configtest</code></dt>
<section id="options.query"><title>Query Options</title>
<dl>
<dt><code>-q</code></dt>
- <dd>Performs a query for variables and environment settings used to
- build <code>httpd</code>. When invoked without <var>query</var> parameters,
- it prints all known variables and their values. The optional <code>-v</code>
+ <dd>Performs a query for variables and environment settings used to
+ build <code>httpd</code>. When invoked without <var>query</var> parameters,
+ it prints all known variables and their values. The optional <code>-v</code>
parameter formats the list output.
- <p>Use this to manually determine settings used to build the
+ <p>Use this to manually determine settings used to build the
<code>httpd</code> that will load your module. For instance use</p>
<example>
INC=-I`apxs -q INCLUDEDIR`
<dl>
<dt><code>--with-mpm=MPM</code></dt>
<dd>
- <p>Choose the default MPM for your server. If MPMs are built as DSO
+ <p>Choose the default MPM for your server. If MPMs are built as DSO
modules (see <code>--enable-mpms-shared</code>), this directive
selects the MPM which will be loaded in the default configuration
file. Otherwise, this directive selects the only available MPM,
<dt><code>add</code></dt>
<dd>Adds an entry for <var>username</var> to <var>filename</var> using the
encrypted password <var>encpasswd</var>.
-
+
<example>dbmmanage passwords.dat add rbowen foKntnEF3KSXA</example>
</dd>
<dt><code>adduser</code></dt>
<dd>Asks for a password and then adds an entry for <var>username</var> to
<var>filename</var>.
-
+
<example>dbmmanage passwords.dat adduser krietz</example>
</dd>
<dt><code>check</code></dt>
<dd>Asks for a password and then checks if <var>username</var> is in
<var>filename</var> and if it's password matches the specified one.
-
+
<example>dbmmanage passwords.dat check rbowen</example>
</dd>
<dt><code>delete</code></dt>
<dd>Deletes the <var>username</var> entry from <var>filename</var>.
-
+
<example>dbmmanage passwords.dat delete rbowen</example>
</dd>
<dt><code>update</code></dt>
<dd>Same as the <code>adduser</code> command, except that it makes
sure <var>username</var> already exists in <var>filename</var>.
-
+
<example>dbmmanage passwords.dat update rbowen</example>
</dd>
<dt><code>view</code></dt>
<dd>Just displays the contents of the DBM file. If you specify a
<var>username</var>, it displays the particular record only.
-
+
<example>dbmmanage passwords.dat view</example>
</dd>
</dl>
-<strong>p</strong><var>path</var>
[-<strong>l</strong><var>limit</var>|
-<strong>L</strong><var>limit</var>]</code></p>
-
+
<p><code><strong>htcacheclean</strong>
[ -<strong>n</strong> ]
[ -<strong>t</strong> ]
removed, however with some configurations the large number of
directories created may require attention. If your configuration
requires a very large number of directories, to the point that
- inode or file allocation table exhaustion may become an issue, use
+ inode or file allocation table exhaustion may become an issue, use
of this option is advised.</dd>
<dt><code>-p<var>path</var></code></dt>
[ -<strong>m</strong> |
-<strong>d</strong> |
-<strong>p</strong> |
- -<strong>s</strong> ]
+ -<strong>s</strong> ]
[ -<strong>D</strong> ] <var>passwdfile</var> <var>username</var>
<var>password</var></code></p>
<dt><code>-D</code></dt>
<dd>Delete user. If the username exists in the specified htpasswd file, it
will be deleted.</dd>
-
+
<dt><code><var>passwdfile</var></code></dt>
<dd>Name of the file to contain the user name and password. If
<code>-c</code> is given, this file is created if it does not already exist,
[ -<strong>C</strong> <var>directive</var> ] [ -<strong>c</strong>
<var>directive</var> ] [ -<strong>D</strong> <var>parameter</var> ]
[ -<strong>e</strong> <var>level</var> ] [ -<strong>E</strong>
- <var>file</var> ]
+ <var>file</var> ]
[ <strong>-k</strong> start|restart|graceful|stop|graceful-stop ]
[ -<strong>R</strong> <var>directory</var> ] [ -<strong>h</strong> ]
[ -<strong>l</strong> ] [ -<strong>L</strong> ] [ -<strong>S</strong> ]
<dt><code>-w</code></dt>
-<dd>Keep the console window open on error so that the error message can
+<dd>Keep the console window open on error so that the error message can
be read.</dd>
</dl>
<summary>
<p><code>httxt2dbm</code> is used to generate dbm files from text input, for
- use in <directive module="mod_rewrite">RewriteMap</directive> with the
+ use in <directive module="mod_rewrite">RewriteMap</directive> with the
<code>dbm</code> map type.
</p>
</summary>
<manualpage metafile="logresolve.xml.meta">
<parentdocument href="./">Programs</parentdocument>
- <title>logresolve - Resolve IP-addresses to hostnames in Apache
+ <title>logresolve - Resolve IP-addresses to hostnames in Apache
log files</title>
<summary>
combined_plus_vhost<br />
CustomLog logs/access_log combined_plus_vhost
</example>
-
+
<p>Log files will be created, in the directory where are running the
- script, for each virtual host name that appears in the combined log file.
+ script, for each virtual host name that appears in the combined log file.
These logfiles will named after the hostname, with a
<code>.log</code> file extension.</p>
[ -<strong>v</strong> ]
[ -<strong>e</strong> ]
<var>logfile</var>
- <var>rotationtime</var>|<var>filesize</var>(B|K|M|G)
+ <var>rotationtime</var>|<var>filesize</var>(B|K|M|G)
[ <var>offset</var> ]</code></p>
</section>
<dt><code>-l</code></dt>
<dd>Causes the use of local time rather than GMT as the base for the
-interval or for <code>strftime(3)</code> formatting with size-based
+interval or for <code>strftime(3)</code> formatting with size-based
rotation.</dd>
<dt><code>-L</code> <var>linkname</var></dt>
<dd>Causes a hard link to be made from the current logfile
to the specified link name. This can be used to watch
-the log continuously across rotations using a command like
+the log continuously across rotations using a command like
<code>tail -F linkname</code>.</dd>
<dt><code>-p</code> <var>program</var></dt>
be sure the log file format has enough granularity to produce
a different file name each time the logs are rotated. Otherwise
rotation will overwrite the same file instead of starting a new
-one. For example, if <var>logfile</var> was
+one. For example, if <var>logfile</var> was
<code>/var/logs/errorlog.%Y-%m-%d</code> with log rotation at 5
megabytes, but 5 megabytes was reached twice in the same day, the
same log file name would be produced and log rotation would keep
reaches a size of 5 megabytes, and the suffix to the logfile name
will be created of the form
<code>errorlog.YYYY-mm-dd-HH_MM_SS</code>.</p>
-
+
<example>
CustomLog "|bin/rotatelogs -t /var/logs/logfile 86400" common
</example>
<tr><td><code>%m</code></td><td>2-digit month</td></tr>
<tr><td><code>%p</code></td><td>am/pm of 12 hour clock (localized)</td></tr>
<tr><td><code>%S</code></td><td>2-digit second</td></tr>
-<tr><td><code>%U</code></td><td>2-digit week of year
+<tr><td><code>%U</code></td><td>2-digit week of year
(Sunday first day of week)</td></tr>
-<tr><td><code>%W</code></td><td>2-digit week of year
+<tr><td><code>%W</code></td><td>2-digit week of year
(Monday first day of week)</td></tr>
-<tr><td><code>%w</code></td><td>1-digit weekday
+<tr><td><code>%w</code></td><td>1-digit weekday
(Sunday first day of week)</td></tr>
<tr><td><code>%X</code></td><td>time (localized)</td></tr>
<tr><td><code>%x</code></td><td>date (localized)</td></tr>
<summary>
-<p>This document supplements the <module>mod_rewrite</module>
+<p>This document supplements the <module>mod_rewrite</module>
<a href="../mod/mod_rewrite.html">reference documentation</a>. It describes
how you can use <module>mod_rewrite</module> to control access to
various resources, and other related techniques.
</section>
-</manualpage>
+</manualpage>
<summary>
-<p>This document supplements the <module>mod_rewrite</module>
-<a href="../mod/mod_rewrite.html">reference documentation</a>. It provides
+<p>This document supplements the <module>mod_rewrite</module>
+<a href="../mod/mod_rewrite.html">reference documentation</a>. It provides
a few advanced techniques using mod_rewrite.</p>
<note type="warning">Note that many of these examples won't work unchanged in your
<dt>Description:</dt>
<dd>
- <p>A common technique for distributing the burden of
- server load or storage space is called "sharding".
+ <p>A common technique for distributing the burden of
+ server load or storage space is called "sharding".
When using this method, a front-end server will use the
url to consistently "shard" users or objects to separate
backend servers.</p>
the CGI program <code>/regenerate_page.cgi</code>, which generates
the requested resource and saves it into the document directory, so
that the next time it is requested, a static copy can be served.</p>
-
+
<p>In this way, documents that are infrequently updated can be served in
static form. if documents need to be refreshed, they can be deleted
from the document directory, and they will then be regenerated the
</dd>
<dt>Discussion:</dt>
- <dd>This technique will of course also work with other
+ <dd>This technique will of course also work with other
special characters that mod_rewrite, by default, URL-encodes.</dd>
</dl>
</section>
-</manualpage>
+</manualpage>
<summary>
-<p>This document supplements the <module>mod_rewrite</module>
+<p>This document supplements the <module>mod_rewrite</module>
<a href="../mod/mod_rewrite.html">reference documentation</a>. It describes
perhaps one of the most important concepts about mod_rewrite - namely,
when to avoid using it.</p>
</section>
-</manualpage>
+</manualpage>
a longer form, such as <code>cookie</code>. Some flags take one or more
arguments. Flags are not case sensitive.</p>
-<p>Each flag (with a few exceptions)
+<p>Each flag (with a few exceptions)
has a long and short form. While it is most common to use
the short form, it is recommended that you familiarize yourself with the
long form, so that you remember what each flag is supposed to do.</p>
<section id="flag_f"><title>F|forbidden</title>
<p>Using the [F] flag causes the server to return a 403 Forbidden status
code to the client. While the same behavior can be accomplished using
-the <directive module="mod_access">Deny</directive> directive, this
+the <directive module="mod_access">Deny</directive> directive, this
allows more flexibility in assigning a Forbidden status.</p>
<p>The following rule will forbid <code>.exe</code> files from being
<p>If you are using <directive
module="mod_rewrite">RewriteRule</directive> in either
-<code>.htaccess</code> files or in
+<code>.htaccess</code> files or in
<directive type="section" module="core">Directory</directive> sections,
it is important to have some understanding of how the rules are
processed. The simplified form of this is that once the rules have been
processed, the rewritten request is handed back to the URL parsing
engine to do what it may with it. It is possible that as the rewritten
-request is handled, the <code>.htaccess</code> file or
+request is handled, the <code>.htaccess</code> file or
<directive type="section" module="core">Directory</directive> section
may be encountered again, and thus the ruleset may be run again from the
start. Most commonly this will happen if one of the rules causes a
<p>The example given here will rewrite any request to
<code>index.php</code>, giving the original request as a query string
argument to <code>index.php</code>, however, the <directive
-module="mod_rewrite">RewriteCond</directive> ensures that if the request
+module="mod_rewrite">RewriteCond</directive> ensures that if the request
is already for <code>index.php</code>, the <directive
module="mod_rewrite">RewriteRule</directive> will be skipped.</p>
the complete set of rules are applied. Use this flag to exclude
problematic rules.</p>
-<p>To decide whether or not to use this rule: if you prefix URLs with
+<p>To decide whether or not to use this rule: if you prefix URLs with
CGI-scripts, to force them to be processed by the CGI-script, it's
likely that you will run into problems (or significant overhead)
on sub-requests. In these cases, use this flag.</p>
module="mod_rewrite">RewriteRule</directive> to be passed back through
URL mapping, so that location-based mappings, such as <directive
module="mod_alias">Alias</directive>, <directive
-module="core">Redirect</directive>, or <directive
-module="mod_alias">ScriptAlias</directive>, for example, might have a
+module="core">Redirect</directive>, or <directive
+module="mod_alias">ScriptAlias</directive>, for example, might have a
chance to take effect.
</p>
<p>
-If, for example, you have an
+If, for example, you have an
<directive module="mod_alias">Alias</directive>
for /icons, and have a <directive
module="mod_rewrite">RewriteRule</directive> pointing there, you should
-use the [PT] flag to ensure that the
+use the [PT] flag to ensure that the
<directive module="mod_alias">Alias</directive> is evaluated.
</p>
</p>
<p>
-<em>Any</em> valid HTTP response status code may be specified,
-using the syntax [R=305], with a 302 status code being used by
+<em>Any</em> valid HTTP response status code may be specified,
+using the syntax [R=305], with a 302 status code being used by
default if none is specified. The status code specified need not
necessarily be a redirect (3xx) status code.
</p>
the <code>L</code> were used.</p>
<p>In addition to response status codes, you may also specify redirect
-status using their symbolic names: <code>temp</code> (default),
+status using their symbolic names: <code>temp</code> (default),
<code>permanent</code>, or <code>seeother</code>.</p>
<p>
<directive module="mod_rewrite">RewriteRule</directive> immediately
following it. Thus, if you want to make a <code>RewriteCond</code> apply
to several <code>RewriteRule</code>s, one possible technique is to
-negate those conditions and use a [Skip] flag. So, you can
-use this to make pseudo if-then-else constructs: The last rule of
-the then-clause becomes <code>skip=N</code>, where N is the
+negate those conditions and use a [Skip] flag. So, you can
+use this to make pseudo if-then-else constructs: The last rule of
+the then-clause becomes <code>skip=N</code>, where N is the
number of rules in the else-clause.</p>
</section>
<p>
If used in per-directory context, use only <code>-</code> (dash)
-as the substitution <em>for the entire round of mod_rewrite processing</em>,
-otherwise the MIME-type set with this flag is lost due to an internal
+as the substitution <em>for the entire round of mod_rewrite processing</em>,
+otherwise the MIME-type set with this flag is lost due to an internal
re-processing (including subsequent rounds of mod_rewrite processing).
-The <code>L</code> flag can be useful in this context to end the
+The <code>L</code> flag can be useful in this context to end the
<em>current</em> round of mod_rewrite processing.</p>
</section>
<summary>
-<p>This document supplements the <module>mod_rewrite</module>
+<p>This document supplements the <module>mod_rewrite</module>
<a href="../mod/mod_rewrite.html">reference documentation</a>. It describes
the way that the rules change when you use mod_rewrite in .htaccess files,
and how to deal with these changes.</p>
<seealso><a href="advanced.html">Advanced techniques</a></seealso>
<seealso><a href="avoid.html">When not to use mod_rewrite</a></seealso>
-</manualpage>
+</manualpage>
<summary>
<p><module>mod_rewrite</module> provides a way to modify incoming
- URL requests, dynamically, based on <a href="intro.html#regex">regular
+ URL requests, dynamically, based on <a href="intro.html#regex">regular
expression</a> rules. This allows you to map arbitrary URLs onto
your internal URL structure in any way you like.</p>
character</td><td><code>c.t</code> will match <code>cat</code>,
<code>cot</code>, <code>cut</code>, etc.</td></tr>
<tr><td><code>+</code></td><td>Repeats the previous match one or more
-times</td><td><code>a+</code> matches <code>a</code>, <code>aa</code>,
+times</td><td><code>a+</code> matches <code>a</code>, <code>aa</code>,
<code>aaa</code>, etc</td></tr>
<tr><td><code>*</code></td><td>Repeats the previous match zero or more
times.</td><td><code>a*</code> matches all the same things
the string.</td><td><code>a$</code> matches a string that ends with
<code>a</code>.</td></tr>
<tr><td><code>( )</code></td><td>Groups several characters into a single
-unit, and captures a match for use in a backreference.</td><td><code>(ab)+</code>
+unit, and captures a match for use in a backreference.</td><td><code>(ab)+</code>
matches <code>ababab</code> - that is, the <code>+</code> applies to the group.
For more on backreferences see <a href="#InternalBackRefs">below</a>.</td></tr>
<tr><td><code>[ ]</code></td><td>A character class - matches one of the
RewriteRule, RewriteCond matching.</p>
<p class="figure">
- <img src="../images/rewrite_rule_flow.png"
+ <img src="../images/rewrite_rule_flow.png"
alt="Flow of RewriteRule and RewriteCond matching" /><br />
<dfn>Figure 1:</dfn> The back-reference flow through a rule.
</p>
the beginning of a query string).</p>
<p class="figure">
- <img src="../images/syntax_rewriterule.png"
+ <img src="../images/syntax_rewriterule.png"
alt="Syntax of the RewriteRule directive" /><br />
<dfn>Figure 2:</dfn> Syntax of the RewriteRule directive.
</p>
argument is a list of flags that modify how the match is evaluated.</p>
<p class="figure">
- <img src="../images/syntax_rewritecond.png"
+ <img src="../images/syntax_rewritecond.png"
alt="Syntax of the RewriteCond directive" /><br />
<dfn>Figure 3:</dfn> Syntax of the RewriteCond directive
</p>
<summary>
-<p>This document supplements the <module>mod_rewrite</module>
+<p>This document supplements the <module>mod_rewrite</module>
<a href="../mod/mod_rewrite.html">reference documentation</a>. It describes
how to use the RewriteRule's [P] flag to proxy content to another server.
A number of recipes are provided that describe common scenarios.</p>
module="mod_proxy">ProxyPassReverse</directive> directive to ensure
that any redirects issued by the backend are correctly passed on to
the client.</p>
-
+
<p>Consider using either <directive
module="mod_proxy">ProxyPass</directive> or <directive
module="mod_rewrite">ProxyPassMatch</directive> whenever possible in
</section>
-</manualpage>
+</manualpage>
<summary>
-<p>This document supplements the <module>mod_rewrite</module>
+<p>This document supplements the <module>mod_rewrite</module>
<a href="../mod/mod_rewrite.html">reference documentation</a>. It describes
how you can use <module>mod_rewrite</module> to redirect and remap
request. This includes many examples of common uses of mod_rewrite,
</VirtualHost>
</example>
-<p>You can alternatively accomplish this using the
+<p>You can alternatively accomplish this using the
<directive module="core" type="section">If</directive>
directive:</p>
</example>
<p>If, for whatever reason, you still want to use <code>mod_rewrite</code>
-- if, for example, you need this to work with a larger set of RewriteRules -
+- if, for example, you need this to work with a larger set of RewriteRules -
you might use one of the recipes below.</p>
<p>For sites running on a port other than 80:</p>
<dt>Discussion</dt>
<dd>
- <note type="warning">This ruleset relies on
- <directive module="core">HostNameLookups</directive>
+ <note type="warning">This ruleset relies on
+ <directive module="core">HostNameLookups</directive>
being set <code>on</code>, which can be
a significant performance hit.</note>
<p>We redirect the URL <code>/</code> to
<code>/about/</code>:
</p>
-
+
<example>
RewriteEngine on<br />
RewriteRule <strong>^/$</strong> /about/ [<strong>R</strong>]
<p>Note also that the example rewrites only the root URL. That is, it
rewrites a request for <code>http://example.com/</code>, but not a
-request for <code>http://example.com/page.html</code>. If you have in
-fact changed your document root - that is, if <strong>all</strong> of
-your content is in fact in that subdirectory, it is greatly preferable
+request for <code>http://example.com/page.html</code>. If you have in
+fact changed your document root - that is, if <strong>all</strong> of
+your content is in fact in that subdirectory, it is greatly preferable
to simply change your <directive module="core">DocumentRoot</directive>
directive, or move all of the content up one directory,
rather than rewriting URLs.</p>
</section>
-</manualpage>
+</manualpage>
<title>Using RewriteMap</title>
<summary>
- <p>This document supplements the <module>mod_rewrite</module>
+ <p>This document supplements the <module>mod_rewrite</module>
<a href="../mod/mod_rewrite.html">reference documentation</a>. It describes
the use of the <directive module="mod_rewrite">RewriteMap</directive> directive,
and provides examples of each of the various <code>RewriteMap</code> types.</p>
<example>
RewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em>
</example>
-
+
<p>The <a id="mapfunc" name="mapfunc"><em>MapName</em></a> is an
arbitray name that you assign to the map, and which you will use in
directives later on. Arguments are passed to the map via the
<title>int: Internal Function</title>
<p>When a MapType of <code>int</code> is used, the MapSource is one
- of the available internal RewriteMap functions. Module authors can provide
+ of the available internal RewriteMap functions. Module authors can provide
additional internal functions by registering them with the
- <code>ap_register_rewrite_mapfunc</code> API.
+ <code>ap_register_rewrite_mapfunc</code> API.
The functions that are provided by default are:
</p>
once. For each mapping-function use one
<directive>RewriteMap</directive> directive to declare its rewriting
mapfile.</p>
-
+
<p>While you cannot <strong>declare</strong> a map in
per-directory context (<code>.htaccess</code> files or
<Directory> blocks) it is possible to
the <code>RewriteBase</code> directive below for the
trick to achieve this) and then initiates a new internal
sub-request with the new URL. This restarts processing of
- the API phases.
+ the API phases.
<p>Again mod_rewrite tries hard to make this complicated
step totally transparent to the user, but you should
</section>
<section id="InternalRuleset"><title>Ruleset Processing</title>
-
+
<p>Now when mod_rewrite is triggered in these two API phases, it
reads the configured rulesets from its configuration
structure (which itself was either created on startup for
<summary>
-<p>This document supplements the <module>mod_rewrite</module>
+<p>This document supplements the <module>mod_rewrite</module>
<a href="../mod/mod_rewrite.html">reference documentation</a>. It describes
-how you can use <module>mod_rewrite</module> to create dynamically
+how you can use <module>mod_rewrite</module> to create dynamically
configured virtual hosts.</p>
<note type="warning">mod_rewrite is not the best way to configure
<dt>Discussion</dt>
<dd>
- <note type="warning">You will need to take care of the DNS
+ <note type="warning">You will need to take care of the DNS
resolution - Apache does
- not handle name resolution. You'll need either to create CNAME
+ not handle name resolution. You'll need either to create CNAME
records for each hostname, or a DNS wildcard record. Creating DNS
records is beyond the scope of this document.</note>
isn't the best way to accomplish this task. You should, instead,
consider using <module>mod_vhost_alias</module> instead, as it will much
more gracefully handle anything beyond serving static files, such as any
-dynamic content, and Alias resolution.
+dynamic content, and Alias resolution.
</p>
</dd>
</dl>
</section>
-</manualpage>
+</manualpage>
parts of the filesystem. Directives enclosed in a <directive
type="section" module="core">Directory</directive> section apply to
the named filesystem directory and all subdirectories of that
-directory (as well as the files in those directories).
+directory (as well as the files in those directories).
The same effect can be obtained using <a
href="howto/htaccess.html">.htaccess files</a>. For example, in the
following configuration, directory indexes will be enabled for the
ProxyPass /special-area http://special.example.com smax=5 max=10<br />
ProxyPass / balancer://mycluster/ stickysession=JSESSIONID|jsessionid nofailover=On
</example>
-</section>
+</section>
<section id="wildcards"><title>Wildcards and Regular Expressions</title>
<p>To find out what directives are allowed in what types of
configuration sections, check the <a
href="mod/directive-dict.html#Context">Context</a> of the directive.
-Everything that is allowed in
+Everything that is allowed in
<directive type="section" module="core">Directory</directive>
sections is also syntactically allowed in
<directive type="section" module="core">DirectoryMatch</directive>,
<tr><td><code>SSLLogFile</code> <em>file</em></td><td><code>SSLLog</code> <em>file</em></td><td>compactified</td></tr>
<tr><td><code>SSLRequiredCiphers</code> <em>spec</em></td><td><code>SSLCipherSuite</code> <em>spec</em></td><td>renamed</td></tr>
-<tr><td><code>SSLRequireCipher</code> <em>c1</em> ...</td><td><code>SSLRequire %{SSL_CIPHER} in {"</code><em>c1</em><code>",
+<tr><td><code>SSLRequireCipher</code> <em>c1</em> ...</td><td><code>SSLRequire %{SSL_CIPHER} in {"</code><em>c1</em><code>",
...}</code></td><td>generalized</td></tr>
-<tr><td><code>SSLBanCipher</code> <em>c1</em> ...</td><td><code>SSLRequire not (%{SSL_CIPHER} in {"</code><em>c1</em><code>",
+<tr><td><code>SSLBanCipher</code> <em>c1</em> ...</td><td><code>SSLRequire not (%{SSL_CIPHER} in {"</code><em>c1</em><code>",
...})</code></td><td>generalized</td></tr>
<tr><td><code>SSLFakeBasicAuth</code></td><td><code>SSLOptions +FakeBasicAuth</code></td><td>merged</td></tr>
<tr><td><code>SSLCacheServerPath</code> <em>dir</em></td><td>-</td><td>functionality removed</td></tr>
</section>
</section>
-<section id="variables"><title>Environment Variables</title>
+<section id="variables"><title>Environment Variables</title>
<p>The mapping between environment variable names used by the older
SSL solutions and the names used by mod_ssl is given in <a
<section id="installation"><title>Installation</title>
<ul>
-<li><a href="#mutex">Why do I get permission errors related to
+<li><a href="#mutex">Why do I get permission errors related to
SSLMutex when I start Apache?</a></li>
-<li><a href="#entropy">Why does mod_ssl stop with the error "Failed to
+<li><a href="#entropy">Why does mod_ssl stop with the error "Failed to
generate temporary 512 bit RSA private key" when I start Apache?</a></li>
</ul>
-<section id="mutex"><title>Why do I get permission errors related to
+<section id="mutex"><title>Why do I get permission errors related to
SSLMutex when I start Apache?</title>
<p>Errors such as ``<code>mod_ssl: Child could not open
SSLMutex lockfile /opt/apache/logs/ssl_mutex.18332 (System error follows)
</section>
<section id="entropy"><title>Why does mod_ssl stop with the error
- "Failed to generate temporary 512 bit RSA private key" when I start
+ "Failed to generate temporary 512 bit RSA private key" when I start
Apache?</title>
<p>Cryptographic software needs a source of unpredictable data
to work correctly. Many open source operating systems provide
encryption. As of version 0.9.5, the OpenSSL functions that need
randomness report an error if the PRNG has not been seeded with
at least 128 bits of randomness.</p>
- <p>To prevent this error, <module>mod_ssl</module> has to provide
- enough entropy to the PRNG to allow it to work correctly. This can
- be done via the <directive module="mod_ssl">SSLRandomSeed</directive>
+ <p>To prevent this error, <module>mod_ssl</module> has to provide
+ enough entropy to the PRNG to allow it to work correctly. This can
+ be done via the <directive module="mod_ssl">SSLRandomSeed</directive>
directive.</p>
</section>
</section>
<section id="aboutconfig"><title>Configuration</title>
<ul>
-<li><a href="#parallel">Is it possible to provide HTTP and HTTPS from
+<li><a href="#parallel">Is it possible to provide HTTP and HTTPS from
the same server?</a></li>
<li><a href="#ports">Which port does HTTPS use?</a></li>
-<li><a href="#httpstest">How do I speak HTTPS manually for testing
+<li><a href="#httpstest">How do I speak HTTPS manually for testing
purposes?</a></li>
-<li><a href="#hang">Why does the connection hang when I connect to my
+<li><a href="#hang">Why does the connection hang when I connect to my
SSL-aware Apache server?</a></li>
-<li><a href="#refused">Why do I get ``Connection Refused'' errors, when
+<li><a href="#refused">Why do I get ``Connection Refused'' errors, when
trying to access my newly installed Apache+mod_ssl server via HTTPS?</a></li>
<li><a href="#envvars">Why are the <code>SSL_XXX</code> variables not
available to my CGI & SSI scripts?</a></li>
-<li><a href="#relative">How can I switch between HTTP and HTTPS in
+<li><a href="#relative">How can I switch between HTTP and HTTPS in
relative hyperlinks?</a></li>
</ul>
-<section id="parallel"><title>Is it possible to provide HTTP and HTTPS
+<section id="parallel"><title>Is it possible to provide HTTP and HTTPS
from the same server?</title>
- <p>Yes. HTTP and HTTPS use different server ports (HTTP binds to
- port 80, HTTPS to port 443), so there is no direct conflict between
- them. You can either run two separate server instances bound to
- these ports, or use Apache's elegant virtual hosting facility to
- create two virtual servers, both served by the same instance of Apache
- - one responding over HTTP to requests on port 80, and the other
+ <p>Yes. HTTP and HTTPS use different server ports (HTTP binds to
+ port 80, HTTPS to port 443), so there is no direct conflict between
+ them. You can either run two separate server instances bound to
+ these ports, or use Apache's elegant virtual hosting facility to
+ create two virtual servers, both served by the same instance of Apache
+ - one responding over HTTP to requests on port 80, and the other
responding over HTTPS to requests on port 443.</p>
</section>
<section id="httpstest"><title>How do I speak HTTPS manually for testing purposes?</title>
<p>While you usually just use</p>
-
+
<example>$ telnet localhost 80<br />
GET / HTTP/1.0</example>
<p>for simple testing of Apache via HTTP, it's not so easy for
HTTPS because of the SSL protocol between TCP and HTTP. With the
- help of OpenSSL's <code>s_client</code> command, however, you can
+ help of OpenSSL's <code>s_client</code> command, however, you can
do a similar check via HTTPS:</p>
-
+
<example>$ openssl s_client -connect localhost:443 -state -debug<br />
GET / HTTP/1.0</example>
$ curl https://localhost/</example>
</section>
-<section id="hang"><title>Why does the connection hang when I connect
+<section id="hang"><title>Why does the connection hang when I connect
to my SSL-aware Apache server?</title>
<p>This can happen when you try to connect to a HTTPS server (or virtual
or which supports it on a non-standard port). Make sure that you're
connecting to a (virtual) server that supports SSL.</p></section>
-<section id="refused"><title>Why do I get ``Connection Refused'' messages,
+<section id="refused"><title>Why do I get ``Connection Refused'' messages,
when trying to access my newly installed Apache+mod_ssl server via HTTPS?</title>
<p>
This error can be caused by an incorrect configuration.
Please make sure that your <directive module="mpm_common"
- >Listen</directive> directives match your
+ >Listen</directive> directives match your
<directive type="section" module="core">VirtualHost</directive>
- directives. If all else fails, please start afresh, using the default
+ directives. If all else fails, please start afresh, using the default
configuration provided by <module>mod_ssl</module>.</p>
</section>
-<section id="envvars"><title>Why are the <code>SSL_XXX</code> variables
+<section id="envvars"><title>Why are the <code>SSL_XXX</code> variables
not available to my CGI & SSI scripts?</title>
<p>Please make sure you have ``<code>SSLOptions +StdEnvVars</code>''
enabled for the context of your CGI/SSI requests.</p>
</section>
<section id="relative">
-<title>How can I switch between HTTP and HTTPS in relative
+<title>How can I switch between HTTP and HTTPS in relative
hyperlinks?</title>
-<p>Usually, to switch between HTTP and HTTPS, you have to use
- fully-qualified hyperlinks (because you have to change the URL
- scheme). Using <module>mod_rewrite</module> however, you can
+<p>Usually, to switch between HTTP and HTTPS, you have to use
+ fully-qualified hyperlinks (because you have to change the URL
+ scheme). Using <module>mod_rewrite</module> however, you can
manipulate relative hyperlinks, to achieve the same effect.</p>
<example>
RewriteEngine on<br />
<section id="aboutcerts"><title>Certificates</title>
<ul>
-<li><a href="#keyscerts">What are RSA Private Keys, CSRs and
+<li><a href="#keyscerts">What are RSA Private Keys, CSRs and
Certificates?</a></li>
<li><a href="#startup">Is there a difference on startup between
a non-SSL-aware Apache and an SSL-aware Apache?</a></li>
-<li><a href="#selfcert">How do I create a self-signed SSL
+<li><a href="#selfcert">How do I create a self-signed SSL
Certificate for testing purposes?</a></li>
<li><a href="#realcert">How do I create a real SSL Certificate?</a></li>
-<li><a href="#ownca">How do I create and use my own Certificate
+<li><a href="#ownca">How do I create and use my own Certificate
Authority (CA)?</a></li>
-<li><a href="#passphrase">How can I change the pass-phrase on my private
+<li><a href="#passphrase">How can I change the pass-phrase on my private
key file?</a></li>
-<li><a href="#removepassphrase">How can I get rid of the pass-phrase
+<li><a href="#removepassphrase">How can I get rid of the pass-phrase
dialog at Apache startup time?</a></li>
-<li><a href="#verify">How do I verify that a private key matches its
+<li><a href="#verify">How do I verify that a private key matches its
Certificate?</a></li>
-<li><a href="#badcert">Why do connections fail with an "alert bad
+<li><a href="#badcert">Why do connections fail with an "alert bad
certificate" error?</a></li>
-<li><a href="#pemder">How can I convert a certificate from PEM to DER
+<li><a href="#pemder">How can I convert a certificate from PEM to DER
format?</a></li>
<li><a href="#gid">Why do browsers complain that they cannot
verify my Verisign Global ID server certificate?</a></li>
you.</p>
<p>A Certificate Signing Request (CSR) is a digital file which contains
your public key and your name. You send the CSR to a Certifying Authority
- (CA), who will convert it into a real Certificate, by signing it.</p>
+ (CA), who will convert it into a real Certificate, by signing it.</p>
<p>A Certificate contains your
RSA public key, your name, the name of the CA, and is digitally signed by
the CA. Browsers that know the CA can verify the signature on that
description of the SSL protocol.</p>
</section>
-<section id="startup"><title>Is there a difference on startup between
+<section id="startup"><title>Is there a difference on startup between
a non-SSL-aware Apache and an SSL-aware Apache?</title>
-<p>Yes. In general, starting Apache with
- <module>mod_ssl</module> built-in is just like starting Apache
- without it. However, if you have a passphrase on your SSL private
- key file, a startup dialog will pop up which asks you to enter the
+<p>Yes. In general, starting Apache with
+ <module>mod_ssl</module> built-in is just like starting Apache
+ without it. However, if you have a passphrase on your SSL private
+ key file, a startup dialog will pop up which asks you to enter the
pass phrase.</p>
-
- <p>Having to manually enter the passphrase when starting the server
- can be problematic - for example, when starting the server from the
+
+ <p>Having to manually enter the passphrase when starting the server
+ can be problematic - for example, when starting the server from the
system boot scripts. In this case, you can follow the steps
<a href="#removepassphrase">below</a> to remove the passphrase from
your private key. Bear in mind that doing so brings additional security
risks - proceed with caution!</p>
</section>
-<section id="selfcert"><title>How do I create a self-signed SSL
+<section id="selfcert"><title>How do I create a self-signed SSL
Certificate for testing purposes?</title>
<ol>
<li>Make sure OpenSSL is installed and in your <code>PATH</code>.<br />
</li>
<li>Run the following command, to create <code>server.key</code> and
<code>server.crt</code> files:<br />
- <code><strong>$ openssl req -new -x509 -nodes -out server.crt
+ <code><strong>$ openssl req -new -x509 -nodes -out server.crt
-keyout server.key</strong></code><br />
- These can be used as follows in your <code>httpd.conf</code>
+ These can be used as follows in your <code>httpd.conf</code>
file:
<pre>
SSLCertificateFile /path/to/this/server.crt
SSLCertificateKeyFile /path/to/this/server.key
</pre>
</li>
- <li>It is important that you are aware that this
+ <li>It is important that you are aware that this
<code>server.key</code> does <em>not</em> have any passphrase.
- To add a passphrase to the key, you should run the following
+ To add a passphrase to the key, you should run the following
command, and enter & verify the passphrase as requested.<br />
- <p><code><strong>$ openssl rsa -des3 -in server.key -out
+ <p><code><strong>$ openssl rsa -des3 -in server.key -out
server.key.new</strong></code><br />
<code><strong>$ mv server.key.new server.key</strong></code><br /></p>
- Please backup the <code>server.key</code> file, and the passphrase
+ Please backup the <code>server.key</code> file, and the passphrase
you entered, in a secure location.
</li>
</ol>
<br />
<code><strong>$ openssl rsa -noout -text -in server.key</strong></code><br />
<br />
- If necessary, you can also create a decrypted PEM version (not
+ If necessary, you can also create a decrypted PEM version (not
recommended) of this RSA private key with:<br />
<br />
<code><strong>$ openssl rsa -in server.key -out server.key.unsecure</strong></code><br />
<br />
</li>
<li>You now have to send this Certificate Signing Request (CSR) to
- a Certifying Authority (CA) to be signed. Once the CSR has been
+ a Certifying Authority (CA) to be signed. Once the CSR has been
signed, you will have a real Certificate, which can be used by
- Apache. You can have a CSR signed by a commercial CA, or you can
+ Apache. You can have a CSR signed by a commercial CA, or you can
create your own CA to sign it.<br />
- Commercial CAs usually ask you to post the CSR into a web form,
- pay for the signing, and then send a signed Certificate, which
+ Commercial CAs usually ask you to post the CSR into a web form,
+ pay for the signing, and then send a signed Certificate, which
you can store in a server.crt file.<br />
For details on how to create your own CA, and use this to sign
a CSR, see <a href="#ownca">below</a>.<br />
-
- Once your CSR has been signed, you can see the details of the
+
+ Once your CSR has been signed, you can see the details of the
Certificate as follows:<br />
<br />
<code><strong>$ openssl x509 -noout -text -in server.crt</strong></code><br />
<section id="ownca"><title>How do I create and use my own Certificate Authority (CA)?</title>
<p>The short answer is to use the <code>CA.sh</code> or <code>CA.pl</code>
- script provided by OpenSSL. Unless you have a good reason not to,
+ script provided by OpenSSL. Unless you have a good reason not to,
you should use these for preference. If you cannot, you can create a
self-signed Certificate as follows:</p>
-
+
<ol>
<li>Create a RSA private key for your server
(will be Triple-DES encrypted and PEM formatted):<br />
<br />
Please backup this <code>host.key</code> file and the
pass-phrase you entered in a secure location.
- You can see the details of this RSA private key by using the
+ You can see the details of this RSA private key by using the
command:<br />
<code><strong>$ openssl rsa -noout -text -in server.key</strong></code><br />
<br />
- If necessary, you can also create a decrypted PEM version (not
+ If necessary, you can also create a decrypted PEM version (not
recommended) of this RSA private key with:<br />
<br />
<code><strong>$ openssl rsa -in server.key -out server.key.unsecure</strong></code><br />
<li>Create a self-signed Certificate (X509 structure)
with the RSA key you just created (output will be PEM formatted):<br />
<br />
- <code><strong>$ openssl req -new -x509 -nodes -sha1 -days 365
+ <code><strong>$ openssl req -new -x509 -nodes -sha1 -days 365
-key server.key -out server.crt</strong></code><br />
<br />
This signs the server CSR and results in a <code>server.crt</code> file.<br />
specifying the new pass-phrase. You can accomplish this with the following
commands:</p>
-
+
<p><code><strong>$ openssl rsa -des3 -in server.key -out server.key.new</strong></code><br />
<code><strong>$ mv server.key.new server.key</strong></code><br /></p>
-
+
<p>The first time you're asked for a PEM pass-phrase, you should
- enter the old pass-phrase. After that, you'll be asked again to
+ enter the old pass-phrase. After that, you'll be asked again to
enter a pass-phrase - this time, use the new pass-phrase. If you
- are asked to verify the pass-phrase, you'll need to enter the new
+ are asked to verify the pass-phrase, you'll need to enter the new
pass-phrase a second time.</p>
</section>
<p>The reason this dialog pops up at startup and every re-start
is that the RSA private key inside your server.key file is stored in
encrypted format for security reasons. The pass-phrase is needed to decrypt
- this file, so it can be read and parsed. Removing the pass-phrase
+ this file, so it can be read and parsed. Removing the pass-phrase
removes a layer of security from your server - proceed with caution!</p>
<ol>
<li>Remove the encryption from the RSA private key (while
file are such that only root or the web server user can read it
(preferably get your web server to start as root but run as another
user, and have the key readable only by root).</p>
-
+
<p>As an alternative approach you can use the ``<code>SSLPassPhraseDialog
exec:/path/to/program</code>'' facility. Bear in mind that this is
neither more nor less secure, of course.</p>
key" bits are included when you generate a CSR, and subsequently form
part of the associated Certificate.</p>
<p>To check that the public key in your Certificate matches the public
- portion of your private key, you simply need to compare these numbers.
+ portion of your private key, you simply need to compare these numbers.
To view the Certificate and the key run the commands:</p>
-
+
<p><code><strong>$ openssl x509 -noout -text -in server.crt</strong></code><br />
<code><strong>$ openssl rsa -noout -text -in server.key</strong></code></p>
-
+
<p>The `modulus' and the `public exponent' portions in the key and the
Certificate must match. As the public exponent is usually 65537
and it's difficult to visually check that the long modulus numbers
are the same, you can use the following approach:</p>
-
+
<p><code><strong>$ openssl x509 -noout -modulus -in server.crt | openssl md5</strong></code><br />
<code><strong>$ openssl rsa -noout -modulus -in server.key | openssl md5</strong></code></p>
-
+
<p>This leaves you with two rather shorter numbers to compare. It is,
- in theory, possible that these numbers may be the same, without the
- modulus numbers being the same, but the chances of this are
+ in theory, possible that these numbers may be the same, without the
+ modulus numbers being the same, but the chances of this are
overwhelmingly remote.</p>
- <p>Should you wish to check to which key or certificate a particular
- CSR belongs you can perform the same calculation on the CSR as
+ <p>Should you wish to check to which key or certificate a particular
+ CSR belongs you can perform the same calculation on the CSR as
follows:</p>
-
+
<p><code><strong>$ openssl req -noout -modulus -in server.csr | openssl md5</strong></code></p>
</section>
<code><strong>$ openssl x509 -in cert.pem -out cert.der -outform DER</strong></code></p>
</section>
-<section id="gid"><title>Why do browsers complain that they cannot
+<section id="gid"><title>Why do browsers complain that they cannot
verify my Verisign Global ID server certificate?</title>
-<p>Verisign uses an intermediate CA certificate between the root CA
- certificate (which is installed in the browsers) and the server
- certificate (which you installed on the server). You should have
+<p>Verisign uses an intermediate CA certificate between the root CA
+ certificate (which is installed in the browsers) and the server
+ certificate (which you installed on the server). You should have
received this additional CA certificate from Verisign.
If not, complain to them. Then, configure this certificate with the
- <directive module="mod_ssl">SSLCertificateChainFile</directive>
- directive. This ensures that the intermediate CA certificate is
+ <directive module="mod_ssl">SSLCertificateChainFile</directive>
+ directive. This ensures that the intermediate CA certificate is
sent to the browser, filling the gap in the certificate chain.</p>
</section>
</section>
<section id="aboutssl"><title>The SSL Protocol</title>
<ul>
-<li><a href="#random">Why do I get lots of random SSL protocol
+<li><a href="#random">Why do I get lots of random SSL protocol
errors under heavy server load?</a></li>
<li><a href="#load">Why does my webserver have a higher load, now
that it serves SSL encrypted traffic?</a></li>
trying to use Anonymous Diffie-Hellman (ADH) ciphers?</a></li>
<li><a href="#sharedciphers">Why do I get a 'no shared ciphers'
error when connecting to my newly installed server?</a></li>
-<li><a href="#vhosts">Why can't I use SSL with name-based/non-IP-based
+<li><a href="#vhosts">Why can't I use SSL with name-based/non-IP-based
virtual hosts?</a></li>
<li><a href="#vhosts2">Is it possible to use Name-Based Virtual
Hosting to identify different SSL virtual hosts?</a></li>
the lock icon in Netscape browsers stays unlocked when the dialog pops up.
Does this mean the username/password is being sent unencrypted?</a></li>
<li><a href="#msie">Why do I get I/O errors when connecting via
-HTTPS to an Apache+mod_ssl server with Microsoft Internet Explorer
+HTTPS to an Apache+mod_ssl server with Microsoft Internet Explorer
(MSIE)?</a></li>
</ul>
-<section id="random"><title>Why do I get lots of random SSL protocol
+<section id="random"><title>Why do I get lots of random SSL protocol
errors under heavy server load?</title>
<p>There can be a number of reasons for this, but the main one
is problems with the SSL session Cache specified by the
no cache at all) may help.</p>
</section>
-<section id="load"><title>Why does my webserver have a higher load, now
+<section id="load"><title>Why does my webserver have a higher load, now
that it serves SSL encrypted traffic?</title>
<p>SSL uses strong cryptographic encryption, which necessitates a lot of
number crunching. When you request a webpage via HTTPS, everything (even
traffic leads to load increases.</p>
</section>
-<section id="establishing"><title>Why do HTTPS connections to my server
+<section id="establishing"><title>Why do HTTPS connections to my server
sometimes take up to 30 seconds to establish a connection?</title>
<p>This is usually caused by a <code>/dev/random</code> device for
- <directive module="mod_ssl">SSLRandomSeed</directive> which blocks the
- read(2) call until enough entropy is available to service the
+ <directive module="mod_ssl">SSLRandomSeed</directive> which blocks the
+ read(2) call until enough entropy is available to service the
request. More information is available in the reference
manual for the <directive module="mod_ssl">SSLRandomSeed</directive>
directive.</p>
</section>
<section id="ciphers"><title>What SSL Ciphers are supported by mod_ssl?</title>
-<p>Usually, any SSL ciphers supported by the version of OpenSSL in use,
- are also supported by <module>mod_ssl</module>. Which ciphers are
- available can depend on the way you built OpenSSL. Typically, at
+<p>Usually, any SSL ciphers supported by the version of OpenSSL in use,
+ are also supported by <module>mod_ssl</module>. Which ciphers are
+ available can depend on the way you built OpenSSL. Typically, at
least the following ciphers are supported:</p>
-
+
<ol>
<li>RC4 with SHA1</li>
<li>AES with SHA1</li>
<li>Triple-DES with SHA1</li>
</ol>
-
- <p>To determine the actual list of ciphers available, you should run
+
+ <p>To determine the actual list of ciphers available, you should run
the following:</p>
<example>$ openssl ciphers -v</example>
</section>
-<section id="adh"><title>Why do I get ``no shared cipher'' errors, when
+<section id="adh"><title>Why do I get ``no shared cipher'' errors, when
trying to use Anonymous Diffie-Hellman (ADH) ciphers?</title>
<p>By default, OpenSSL does <em>not</em> allow ADH ciphers, for security
- reasons. Please be sure you are aware of the potential side-effects
+ reasons. Please be sure you are aware of the potential side-effects
if you choose to enable these ciphers.</p>
- <p>In order to use Anonymous Diffie-Hellman (ADH) ciphers, you must
+ <p>In order to use Anonymous Diffie-Hellman (ADH) ciphers, you must
build OpenSSL with ``<code>-DSSL_ALLOW_ADH</code>'', and then add
``<code>ADH</code>'' into your <directive module="mod_ssl"
>SSLCipherSuite</directive>.</p>
</section>
-<section id="sharedciphers"><title>Why do I get a 'no shared ciphers'
+<section id="sharedciphers"><title>Why do I get a 'no shared ciphers'
error when connecting to my newly installed server?</title>
-<p>Either you have made a mistake with your
+<p>Either you have made a mistake with your
<directive module="mod_ssl">SSLCipherSuite</directive>
directive (compare it with the pre-configured example in
<code>extra/httpd-ssl.conf</code>) or you chose to use DSA/DH
algorithms instead of RSA when you generated your private key
and ignored or overlooked the warnings. If you have chosen
- DSA/DH, then your server cannot communicate using RSA-based SSL
+ DSA/DH, then your server cannot communicate using RSA-based SSL
ciphers (at least until you configure an additional RSA-based
- certificate/key pair). Modern browsers like NS or IE can only
- communicate over SSL using RSA ciphers. The result is the
- "no shared ciphers" error. To fix this, regenerate your server
+ certificate/key pair). Modern browsers like NS or IE can only
+ communicate over SSL using RSA ciphers. The result is the
+ "no shared ciphers" error. To fix this, regenerate your server
certificate/key pair, using the RSA algorithm.</p>
</section>
<section id="vhosts"><title>Why can't I use SSL with name-based/non-IP-based virtual hosts?</title>
-<p>The reason is very technical, and a somewhat "chicken and egg" problem.
- The SSL protocol layer stays below the HTTP protocol layer and
+<p>The reason is very technical, and a somewhat "chicken and egg" problem.
+ The SSL protocol layer stays below the HTTP protocol layer and
encapsulates HTTP. When an SSL connection (HTTPS) is established
Apache/mod_ssl has to negotiate the SSL protocol parameters with the
client. For this, mod_ssl has to consult the configuration of the virtual
certificate, etc.). But in order to go to the correct virtual server
Apache has to know the <code>Host</code> HTTP header field. To do this, the
HTTP request header has to be read. This cannot be done before the SSL
- handshake is finished, but the information is needed in order to
+ handshake is finished, but the information is needed in order to
complete the SSL handshake phase. See the next question for how to
circumvent this issue.</p>
</section>
specification added, called Server Name Indication (SNI).</p>
<p>The reason is that the SSL protocol is a separate layer which
- encapsulates the HTTP protocol. So the SSL session is a separate
- transaction, that takes place before the HTTP session has begun.
- The server receives an SSL request on IP address X and port Y
- (usually 443). Since the SSL request did not contain any Host:
+ encapsulates the HTTP protocol. So the SSL session is a separate
+ transaction, that takes place before the HTTP session has begun.
+ The server receives an SSL request on IP address X and port Y
+ (usually 443). Since the SSL request did not contain any Host:
field, the server had no way to decide which SSL virtual host to use.
- Usually, it just used the first one it found which matched the
+ Usually, it just used the first one it found which matched the
port and IP address specified.</p>
<p>If you are using a version of the web server and OpenSSL that
web server can select the correct SSL virtual host.</p>
<p>You can, of course, use Name-Based Virtual Hosting to identify many
- non-SSL virtual hosts (all on port 80, for example) and then
+ non-SSL virtual hosts (all on port 80, for example) and then
have a single SSL virtual host (on port 443). But if you do this,
you must make sure to put the non-SSL port number on the NameVirtualHost
- directive, e.g.</p>
+ directive, e.g.</p>
<example>
NameVirtualHost 192.168.1.1:80
</example>
-
+
<p>Other workaround solutions include: </p>
- <p>Using separate IP addresses for different SSL hosts.
- Using different port numbers for different SSL hosts.</p>
+ <p>Using separate IP addresses for different SSL hosts.
+ Using different port numbers for different SSL hosts.</p>
</section>
<section id="comp"><title>How do I get SSL compression working?</title>
SSLv2 Hello. As SSLv2 did not include an array of prefered compression algorithms
in its handshake, compression cannot be negotiated with these clients.
If the client disables support for SSLv2, either an SSLv3 or TLS Hello
-may be sent, depending on which SSL library is used, and compression may
-be set up. You can verify whether clients make use of SSL compression by
+may be sent, depending on which SSL library is used, and compression may
+be set up. You can verify whether clients make use of SSL compression by
logging the <code>%{SSL_COMPRESS_METHOD}x</code> variable.
</p>
</section>
-<section id="lockicon"><title>When I use Basic Authentication over HTTPS
-the lock icon in Netscape browsers stays unlocked when the dialog pops up.
+<section id="lockicon"><title>When I use Basic Authentication over HTTPS
+the lock icon in Netscape browsers stays unlocked when the dialog pops up.
Does this mean the username/password is being sent unencrypted?</title>
<p>No, the username/password is transmitted encrypted. The icon in
Netscape browsers is not actually synchronized with the SSL/TLS layer.
- It only toggles to the locked state when the first part of the actual
- webpage data is transferred, which may confuse people. The Basic
- Authentication facility is part of the HTTP layer, which is above
- the SSL/TLS layer in HTTPS. Before any HTTP data communication takes
- place in HTTPS, the SSL/TLS layer has already completed its handshake
+ It only toggles to the locked state when the first part of the actual
+ webpage data is transferred, which may confuse people. The Basic
+ Authentication facility is part of the HTTP layer, which is above
+ the SSL/TLS layer in HTTPS. Before any HTTP data communication takes
+ place in HTTPS, the SSL/TLS layer has already completed its handshake
phase, and switched to encrypted communication. So don't be
confused by this icon.</p>
</section>
-<section id="msie"><title>Why do I get I/O errors when connecting via
+<section id="msie"><title>Why do I get I/O errors when connecting via
HTTPS to an Apache+mod_ssl server with older versions of Microsoft Internet
Explorer (MSIE)?</title>
<p>The first reason is that the SSL implementation in some MSIE versions has
some subtle bugs related to the HTTP keep-alive facility and the SSL close
notify alerts on socket connection close. Additionally the interaction
- between SSL and HTTP/1.1 features are problematic in some MSIE versions.
- You can work around these problems by forcing Apache not to use HTTP/1.1,
- keep-alive connections or send the SSL close notify messages to MSIE clients.
- This can be done by using the following directive in your SSL-aware
+ between SSL and HTTP/1.1 features are problematic in some MSIE versions.
+ You can work around these problems by forcing Apache not to use HTTP/1.1,
+ keep-alive connections or send the SSL close notify messages to MSIE clients.
+ This can be done by using the following directive in your SSL-aware
virtual host section:</p>
<example>
SetEnvIf User-Agent "MSIE [2-5]" \<br />
nokeepalive ssl-unclean-shutdown \<br />
downgrade-1.0 force-response-1.0
</example>
- <p>Further, some MSIE versions have problems with particular ciphers.
- Unfortunately, it is not possible to implement a MSIE-specific
- workaround for this, because the ciphers are needed as early as the
- SSL handshake phase. So a MSIE-specific
- <directive module="mod_setenvif">SetEnvIf</directive> won't solve these
+ <p>Further, some MSIE versions have problems with particular ciphers.
+ Unfortunately, it is not possible to implement a MSIE-specific
+ workaround for this, because the ciphers are needed as early as the
+ SSL handshake phase. So a MSIE-specific
+ <directive module="mod_setenvif">SetEnvIf</directive> won't solve these
problems. Instead, you will have to make more drastic
adjustments to the global parameters. Before you decide to do
- this, make sure your clients really have problems. If not, do not
+ this, make sure your clients really have problems. If not, do not
make these changes - they will affect <em>all</em> your clients, MSIE
or otherwise.</p>
</section>
<section id="support"><title>mod_ssl Support</title>
<ul>
-<li><a href="#resources">What information resources are available in
+<li><a href="#resources">What information resources are available in
case of mod_ssl problems?</a></li>
-<li><a href="#contact">What support contacts are available in case of
+<li><a href="#contact">What support contacts are available in case of
mod_ssl problems?</a></li>
-<li><a href="#reportdetails">What information should I
+<li><a href="#reportdetails">What information should I
provide when writing a bug report?</a></li>
<li><a href="#coredumphelp">I had a core dump, can you help me?</a></li>
<li><a href="#backtrace">How do I get a backtrace, to help find the reason
</dl>
</section>
-<section id="contact"><title>What support contacts are available in case
+<section id="contact"><title>What support contacts are available in case
of mod_ssl problems?</title>
<p>The following lists all support possibilities for mod_ssl, in order of
- preference. Please go through these possibilities
+ preference. Please go through these possibilities
<em>in this order</em> - don't just pick the one you like the look of. </p>
<ol>
<dt>The details on how you built and installed Apache httpd and OpenSSL</dt>
<dd>For this you can provide a logfile of your terminal session which shows
- the configuration and install steps. If this is not possible, you
+ the configuration and install steps. If this is not possible, you
should at least provide the <program>configure</program> command line you used.
</dd>
<dt>In case of core dumps please include a Backtrace</dt>
<dd>If your Apache httpd dumps its core, please attach
- a stack-frame ``backtrace'' (see <a href="#backtrace">below</a>
+ a stack-frame ``backtrace'' (see <a href="#backtrace">below</a>
for information on how to get this). This information is required
in order to find a reason for your core dump.
</dd>
-
+
<dt>A detailed description of your problem</dt>
- <dd>Don't laugh, we really mean it! Many problem reports don't
+ <dd>Don't laugh, we really mean it! Many problem reports don't
include a description of what the actual problem is. Without this,
- it's very difficult for anyone to help you. So, it's in your own
- interest (you want the problem be solved, don't you?) to include as
+ it's very difficult for anyone to help you. So, it's in your own
+ interest (you want the problem be solved, don't you?) to include as
much detail as possible, please. Of course, you should still include
all the essentials above too.
</dd>
fixing it.</p>
</section>
-<section id="backtrace"><title>How do I get a backtrace, to help find
+<section id="backtrace"><title>How do I get a backtrace, to help find
the reason for my core dump?</title>
<p>Following are the steps you will need to complete, to get a backtrace:</p>
<ol>
want to use a directive like ``<code>CoreDumpDirectory /tmp</code>'' to
make sure that the core-dump file can be written. This should result
in a <code>/tmp/core</code> or <code>/tmp/httpd.core</code> file. If you
- don't get one of these, try running your server under a non-root UID.
+ don't get one of these, try running your server under a non-root UID.
Many modern kernels do not allow a process to dump core after it has
done a <code>setuid()</code> (unless it does an <code>exec()</code>) for
security reasons (there can be privileged information left over in
</li>
<li>Analyze the core-dump. For this, run <code>gdb /path/to/httpd
- /tmp/httpd.core</code> or a similar command. In GDB, all you
+ /tmp/httpd.core</code> or a similar command. In GDB, all you
have to do then is to enter <code>bt</code>, and voila, you get the
- backtrace. For other debuggers consult your local debugger manual.
+ backtrace. For other debuggers consult your local debugger manual.
</li>
</ol>
</section>
<title>Cipher Suites and Enforcing Strong Security</title>
<ul>
<li><a href="#onlystrong">How can I create an SSL server which accepts strong encryption only?</a></li>
-<li><a href="#strongurl">How can I create an SSL server which accepts all types of ciphers in general, but
+<li><a href="#strongurl">How can I create an SSL server which accepts all types of ciphers in general, but
requires a strong cipher for access to a particular URL?</a></li>
</ul>
in general, but requires a strong ciphers for access to a particular
URL?</title>
<p>Obviously, a server-wide <directive
- module="mod_ssl">SSLCipherSuite</directive> which restricts
- ciphers to the strong variants, isn't the answer here. However,
+ module="mod_ssl">SSLCipherSuite</directive> which restricts
+ ciphers to the strong variants, isn't the answer here. However,
<module>mod_ssl</module> can be reconfigured within <code>Location</code>
blocks, to give a per-directory solution, and can automatically force
a renegotiation of the SSL parameters to meet the new configuration.
<title>Client Authentication and Access Control</title>
<ul>
<li><a href="#allclients">How can I force clients to authenticate using certificates?</a></li>
-<li><a href="#arbitraryclients">How can I force clients to authenticate using certificates for a
+<li><a href="#arbitraryclients">How can I force clients to authenticate using certificates for a
particular URL, but still allow arbitrary clients to access the rest of the server?</a></li>
<li><a href="#certauthenticate">How can I allow only clients who have certificates to access a
particular URL, but allow all clients to access the rest of the server?</a></li>
matches what you expect. Usually this means checking all or part of the
Distinguished Name (DN), to see if it contains some known string.
There are two ways to do this, using either <module>mod_auth_basic</module> or
- <directive module="mod_ssl">SSLRequire</directive>.</p>
-
+ <directive module="mod_ssl">SSLRequire</directive>.</p>
+
<p>The <module>mod_auth_basic</module> method is generally required when
the certificates are completely arbitrary, or when their DNs have
no common fields (usually the organisation, etc.). In this case,
you should establish a password database containing <em>all</em>
clients allowed, as follows:</p>
-
+
<example><title>httpd.conf</title><pre>
SSLVerifyClient none
<Directory /usr/local/apache2/htdocs/secure/area>
Require valid-user
</Directory></pre>
</example>
-
+
<p>The password used in this example is the DES encrypted string "password".
- See the <directive module="mod_ssl">SSLOptions</directive> docs for more
+ See the <directive module="mod_ssl">SSLOptions</directive> docs for more
information.</p>
-
+
<example><title>httpd.passwd</title><pre>
/C=DE/L=Munich/O=Snake Oil, Ltd./OU=Staff/CN=Foo:xxj31ZMTZzkVA
/C=US/L=S.F./O=Snake Oil, Ltd./OU=CA/CN=Bar:xxj31ZMTZzkVA
authentication or client certificates, for access to part of the
Intranet website, for clients coming from the Internet? I still want to allow
plain HTTP access for clients on the Intranet.</title>
-
- <p>These examples presume that clients on the Intranet have IPs in the range
+
+ <p>These examples presume that clients on the Intranet have IPs in the range
192.168.1.0/24, and that the part of the Intranet website you want to allow
- internet access to is <code>/usr/local/apache2/htdocs/subarea</code>.
+ internet access to is <code>/usr/local/apache2/htdocs/subarea</code>.
This configuration should remain outside of your HTTPS virtual host, so
that it applies to both HTTPS and HTTP.</p>
specific techniques for managing certificates in an organization, or the
important legal issues of patents and import and export restrictions.
Rather, it is intended to provide a common background to <module
->mod_ssl</module> users by pulling together various concepts, definitions,
+>mod_ssl</module> users by pulling together various concepts, definitions,
and examples as a starting point for further exploration.</p>
<p>The presented content is mainly derived, with the author's permission,
solution is to use a cryptographic algorithm, a technique that would
transform her message into an encrypted form, unreadable until it is
decrypted. Once in this form, the message can only be
- decrypted by using a secret key. Without the key the message is useless:
+ decrypted by using a secret key. Without the key the message is useless:
good cryptographic algorithms make it so difficult
for intruders to decode the original text that it isn't worth their
effort.</p>
<dt>Conventional cryptography</dt>
<dd>also known as symmetric cryptography, requires the sender and
receiver to share a key: a secret piece of information that may be
- used to encrypt or decrypt a message. As long as this key is kept
- secret, nobody other than the sender or recipient can read the message.
+ used to encrypt or decrypt a message. As long as this key is kept
+ secret, nobody other than the sender or recipient can read the message.
If Alice and the bank know a secret key, then they can send each other
private messages. The task of sharing a key between sender and recipient
- before communicating, while also keeping it secret from others, can be
+ before communicating, while also keeping it secret from others, can be
problematic.</dd>
<dt>Public key cryptography</dt>
is still a concern that someone might modify her original message or
substitute it with a different one, in order to transfer the money
to themselves, for instance. One way of guaranteeing the integrity
- of Alice's message is for her to create a concise summary of her
- message and send this to the bank as well. Upon receipt of the message,
- the bank creates its own summary and compares it with the one Alice
+ of Alice's message is for her to create a concise summary of her
+ message and send this to the bank as well. Upon receipt of the message,
+ the bank creates its own summary and compares it with the one Alice
sent. If the summaries are the same then the message has been received
intact.</p>
function</em> or <em>hash function</em>. Message digests are used to create
a short, fixed-length representation of a longer, variable-length message.
Digest algorithms are designed to produce a unique digest for each
- message. Message digests are designed to make it impractically difficult
- to determine the message from the digest and (in theory) impossible to
- find two different messages which create the same digest -- thus
- eliminating the possibility of substituting one message for another while
+ message. Message digests are designed to make it impractically difficult
+ to determine the message from the digest and (in theory) impossible to
+ find two different messages which create the same digest -- thus
+ eliminating the possibility of substituting one message for another while
maintaining the same digest.</p>
<p>Another challenge that Alice faces is finding a way to send the digest
be compromised and with it the possibility for the bank to determine the
integrity of the original message. Only if the digest is sent securely can
the integrity of the associated message be determined.</p>
-
- <p>One way to send the digest securely is to include it in a digital
+
+ <p>One way to send the digest securely is to include it in a digital
signature.</p>
</section>
<p>Although Alice could have sent a private message to the bank, signed
it and ensured the integrity of the message, she still needs to be sure
that she is really communicating with the bank. This means that she needs
-to be sure that the public key she is using is part of the bank's key-pair,
+to be sure that the public key she is using is part of the bank's key-pair,
and not an intruder's. Similarly, the bank needs to verify that the message
signature really was signed by the private key that belongs to Alice.</p>
distinguished field names are optional and which are required. It
may also place requirements upon the field contents, as may users of
certificates. For example, a Netscape browser requires that the
- Common Name for a certificate representing a server matches a wildcard
+ Common Name for a certificate representing a server matches a wildcard
pattern for the domain name of that server, such
as <code>*.snakeoil.com</code>.</p>
<title>Certificate Authorities</title>
<p>By verifying the information in a certificate request
before granting the certificate, the Certificate Authority assures
- itself of the identity of the private key owner of a key-pair.
- For instance, if Alice requests a personal certificate, the
- Certificate Authority must first make sure that Alice really is the
+ itself of the identity of the private key owner of a key-pair.
+ For instance, if Alice requests a personal certificate, the
+ Certificate Authority must first make sure that Alice really is the
person the certificate request claims she is.</p>
<section id="certificatechains">
they also manage them -- that is, they determine for how long
certificates remain valid, they renew them and keep lists of
certificates that were issued in the past but are no longer valid
- (Certificate Revocation Lists, or CRLs).</p>
+ (Certificate Revocation Lists, or CRLs).</p>
- <p>For example, if Alice is entitled to a certificate as an
+ <p>For example, if Alice is entitled to a certificate as an
employee of a company but has now left
that company, her certificate may need to be revoked.
Because certificates are only issued after the subject's identity has
- been verified and can then be passed around to all those with whom
- the subject may communicate, it is impossible to tell from the
- certificate alone that it has been revoked.
- Therefore when examining certificates for validity
- it is necessary to contact the issuing Certificate Authority to
+ been verified and can then be passed around to all those with whom
+ the subject may communicate, it is impossible to tell from the
+ certificate alone that it has been revoked.
+ Therefore when examining certificates for validity
+ it is necessary to contact the issuing Certificate Authority to
check CRLs -- this is usually not an automated part of the process.</p>
<note><title>Note</title>
</table>
</section>
-<p>There are a number of versions of the SSL protocol, as shown in
+<p>There are a number of versions of the SSL protocol, as shown in
<a href="#table4">Table 4</a>. As noted there, one of the benefits in
SSL 3.0 is that it adds support of certificate chain loading. This feature
allows a server to pass a server certificate along with issuer certificates
to the browser. Chain loading also permits the browser to validate the
server certificate, even if Certificate Authority certificates are not
installed for the intermediate issuers, since they are included in the
-certificate chain. SSL 3.0 is the basis for the Transport Layer Security
+certificate chain. SSL 3.0 is the basis for the Transport Layer Security
[<a href="#TLS1">TLS</a>] protocol standard, currently in development by
the Internet Engineering Task Force (IETF).</p>
<p>One variable in the choice of key exchange methods is digital
signatures -- whether or not to use them, and if so, what kind of
- signatures to use. Signing with a private key provides protection
+ signatures to use. Signing with a private key provides protection
against a man-in-the-middle-attack during the information exchange
used to generating the shared key [<a href="#AC96">AC96</a>, p516].</p>
</section>
<section id="ciphertransfer">
<title>Cipher for Data Transfer</title>
- <p>SSL uses conventional symmetric cryptography, as described earlier,
+ <p>SSL uses conventional symmetric cryptography, as described earlier,
for encrypting messages in a session.
There are nine choices of how to encrypt, including the option not to
encrypt:</p>
portion of the previously encrypted cipher text is used in the
encryption of the current block. "DES" refers to the Data Encryption
Standard [<a href="#AC96">AC96</a>, ch12], which has a number of
- variants (including DES40 and 3DES_EDE). "Idea" is currently one of
- the best and cryptographically strongest algorithms available,
+ variants (including DES40 and 3DES_EDE). "Idea" is currently one of
+ the best and cryptographically strongest algorithms available,
and "RC2" is a proprietary algorithm from RSA DSI [<a href="#AC96"
>AC96</a>, ch13].</p>
</section>
<p>The encapsulation of SSL control protocols by the record protocol
means that if an active session is renegotiated the control protocols
- will be transmitted securely. If there was no previous session,
+ will be transmitted securely. If there was no previous session,
the Null cipher suite is used, which means there will be no encryption and
messages will have no integrity digests, until the session has been
established.</p>
<title>Securing HTTP Communication</title>
<p>One common use of SSL is to secure Web HTTP communication between
a browser and a webserver. This does not preclude the use of
- non-secured HTTP - the secure version (called HTTPS) is the same as
- plain HTTP over SSL, but uses the URL scheme <code>https</code>
+ non-secured HTTP - the secure version (called HTTPS) is the same as
+ plain HTTP over SSL, but uses the URL scheme <code>https</code>
rather than <code>http</code>, and a different server port (by default,
port 443). This functionality is a large part of what <module
>mod_ssl</module> provides for the Apache webserver.</p>
</dd>
<dt><a id="PKCS" name="PKCS">[PKCS]</a></dt>
-<dd><q>Public Key Cryptography Standards (PKCS)</q>,
+<dd><q>Public Key Cryptography Standards (PKCS)</q>,
RSA Laboratories Technical Notes, See <a
href="http://www.rsasecurity.com/rsalabs/pkcs/"
>http://www.rsasecurity.com/rsalabs/pkcs/</a>.</dd>
been created, then create enough to pick up the slack. Hence the
code tries to maintain both the number of children appropriate for
the current load on the server, and respect your wishes with the
- <directive module="mpm_common">StartServers</directive>
+ <directive module="mpm_common">StartServers</directive>
parameter.</p>
<p>Users of <module>mod_status</module>
ensure that there are no errors in the configuration files.
If your configuration file has errors in it, you will get an
error message about that syntax error, and the server will refuse to
- restart. This avoids the situation where the server halts and then
+ restart. This avoids the situation where the server halts and then
cannot restart, leaving you with a non-functioning server.</p>
<p>This still will not
<p>The <code>WINCH</code> or <code>graceful-stop</code> signal causes
the parent process to <em>advise</em> the children to exit after
their current request (or to exit immediately if they're not
- serving anything). The parent will then remove its <directive
+ serving anything). The parent will then remove its <directive
module="mpm_common">PidFile</directive> and cease listening on
all ports. The parent will continue to run, and monitor children
which are handling requests. Once all children have finalised
- and exited or the timeout specified by the <directive
+ and exited or the timeout specified by the <directive
module="mpm_common">GracefulShutdownTimeout</directive> has been
reached, the parent will also exit. If the timeout is reached,
any remaining children will be sent the <code>TERM</code> signal
to force them to exit.</p>
-
- <p>A <code>TERM</code> signal will immediately terminate the
+
+ <p>A <code>TERM</code> signal will immediately terminate the
parent process and all children when in the "graceful" state. However
as the <directive module="mpm_common">PidFile</directive> will
- have been removed, you will not be able to use
+ have been removed, you will not be able to use
<code>apachectl</code> or <code>httpd</code> to send this signal.</p>
<note><p>The <code>graceful-stop</code> signal allows you to run multiple
- identically configured instances of <program>httpd</program> at the
- same time. This is a powerful feature when performing graceful
- upgrades of httpd, however it can also cause deadlocks and race
- conditions with some configurations.</p>
+ identically configured instances of <program>httpd</program> at the
+ same time. This is a powerful feature when performing graceful
+ upgrades of httpd, however it can also cause deadlocks and race
+ conditions with some configurations.</p>
<p>Care has been taken to ensure that on-disk files such as lock files
(<directive module="core">Mutex</directive>) and Unix socket files
(<directive module="mod_cgid">ScriptSock</directive>) contain the server
PID, and should coexist without problem. However, if a configuration
- directive, third-party module or persistent CGI utilises any other on-disk
- lock or state files, care should be taken to ensure that multiple running
- instances of <program>httpd</program> do not clobber each other's files.</p>
+ directive, third-party module or persistent CGI utilises any other on-disk
+ lock or state files, care should be taken to ensure that multiple running
+ instances of <program>httpd</program> do not clobber each other's files.</p>
<p>You should also be wary of other potential race conditions, such as
using <program>rotatelogs</program> style piped logging. Multiple running
<!-- Used for glossary link titles -->
<message id="glossarylink">siehe Glossar</message>
-
+
<!-- Used in headers and footers -->
<message id="apachetitle">- Apache HTTP Server</message>
<message id="apachehttpserver">Apache HTTP Server Version
<message id="before-license">Autorisé sous</message>
<message id="after-license"></message>
<message id="langavail">Langues Disponibles</message>
-
+
<!-- not up to date -->
<message id="outofdate">Cette traduction peut être périmée. Vérifiez la version
anglaise pour les changements récents.</message>
<message id="before-license">Licenciado sob a</message>
<message id="after-license"></message>
<message id="langavail">Línguas Disponíveis</message>
-
+
<!-- not up to date -->
- <message id="outofdate">Esta tradução pode estar desatualizada.
+ <message id="outofdate">Esta tradução pode estar desatualizada.
Confira a versão em Inglês para mudanças recentes.</message>
<!-- directive not translated yet -->
<message id="nottranslated">The documentation for this directive has
found in <code>build/config.nice</code> in the installed server
directory) can be used in most cases. There are some changes in
the default settings. Some details of changes:</p>
-
+
<ul>
<li>These modules have been removed: mod_authn_default,
mod_authz_default, mod_mem_cache. If you were using
<p>The address can be specified as
<code>*</code>, which will match a request if no
other vhost has the explicit address on which the request was
- received. </p>
+ received. </p>
<p>The address appearing in the <code>VirtualHost</code>
directive can have an optional port. If the port is unspecified,
Use the <directive module="core">Listen</directive> directive to
control the addresses and ports on which the server listens.)
</p>
-
+
<p>Collectively the
- entire set of addresses (including multiple
+ entire set of addresses (including multiple
results from DNS lookups) are called the vhost's
<em>address set</em>.</p>
whenever the most specific match for an IP address and port combination
is listed in multiple virtual hosts.</p>
- <p>The
+ <p>The
<directive module="core">ServerName</directive> directive
may appear anywhere within the definition of a server. However,
each appearance overrides the previous appearance (within that
<p>If there are multiple <code>VirtualHost</code> directives listing
the IP address and port combination that was determined to be the
- best match, the "list" in the remaining steps refers to the list of vhosts
+ best match, the "list" in the remaining steps refers to the list of vhosts
that matched, in the order they were in the configuration file.</p>
<p>If the connection is using SSL, the server supports <glossary
the client sent the request.</li>
<li>If two vhosts have an address in common, those common addresses
- act as name-based virtual hosts implicitly. This is new behavior as of
+ act as name-based virtual hosts implicitly. This is new behavior as of
2.3.11.</li>
<li>The main server is only used to serve a request if the IP
- address and port number to which the client connected
+ address and port number to which the client connected
does not match any vhost (including a
<code>*</code> vhost). In other words, the main server
only catches a request for an unspecified address/port
<li>The number of file descriptors required exceeds the hard
limit.</li>
-
+
<li>Your system imposes other limits on file descriptors,
such as a limit on stdio streams only using file descriptors
below 256. (Solaris 2)</li>
most commonly used to set them up), and/or using multiple
port numbers.</p>
- <p> In the terminology of Apache HTTP Server, using a single IP address
+ <p> In the terminology of Apache HTTP Server, using a single IP address
but multiple TCP ports, is also IP-based virtual hosting.</p>
</section>
<p> Specific IP addresses or ports have precedence over their wildcard
equivalents, and any virtual host that matches has precedence over
- the servers base configuration.</p>
+ the servers base configuration.</p>
<p>Almost <strong>any</strong> configuration directive can be
put in the VirtualHost directive, with the exception of
<p>The main disadvantage is that you cannot have a different log file for
each virtual host; however, if you have many virtual hosts, doing
this can be a bad idea anyway, because of the <a
- href="fd-limits.html">number of file descriptors needed</a>.
+ href="fd-limits.html">number of file descriptors needed</a>.
It is better to <a href="../logs.html#piped">log to a pipe or a fifo</a>,
and arrange for the process at the other end to split up the log
files into one per virtual host. One example of such a process can
in the HTTP request. The dynamic mass virtual hosting technique
used here is based on automatically inserting this information into the
pathname of the file that is used to satisfy the request. This
- can be most easily done by using <module>mod_vhost_alias</module>
- with Apache httpd. Alternatively,
- <a href="../rewrite/vhosts.html">mod_rewrite can
+ can be most easily done by using <module>mod_vhost_alias</module>
+ with Apache httpd. Alternatively,
+ <a href="../rewrite/vhosts.html">mod_rewrite can
be used</a>.</p>
<p>Both of these modules are disabled by default; you must enable
one of them when configuring and building Apache httpd if you want to
<title>Note</title>
<p>If the first VirtualHost block does <em>not</em> include a
<directive module="core">ServerName</directive> directive, the reverse
- DNS of the relevant IP will be used instead.
+ DNS of the relevant IP will be used instead.
If this is not the server name you
wish to use, a bogus entry (eg. <code>ServerName
none.example.com</code>) can be added to get around this
determine the correct virtual host to serve. Therefore you need to
have a separate IP address for each host.</p>
- <p>With name-based virtual hosting, the server relies on the client to
- report the hostname as part of the HTTP headers. Using this technique,
+ <p>With name-based virtual hosting, the server relies on the client to
+ report the hostname as part of the HTTP headers. Using this technique,
many different hosts can share the same IP address.</p>
<p>Name-based virtual hosting is usually simpler, since you need
after narrowing down the candidates to the best IP-based match. Using a wildcard (*)
for the IP address in all of the VirtualHost directives makes this
IP-based mapping irrelevant.</p>
-
- <p>When a request arrives, the server will find the best (most specific) matching
+
+ <p>When a request arrives, the server will find the best (most specific) matching
<directive type="section" module="core">VirtualHost</directive> argument based on
the IP address and port used by the request. If there is more than one virtual host
containing this best-match address and port combination, Apache will further
- compare the <directive module="core" >ServerName</directive> and <directive
+ compare the <directive module="core" >ServerName</directive> and <directive
module="core">ServerAlias</directive> directives to the server name
present in the request.</p>
<section id="defaultvhost"><title>The default name-based vhost for an IP and port combination </title>
- <p> If no matching ServerName or ServerAlias is found in the set of
- virtual hosts containing the most specific matching IP address and port
- combination, then <strong>the first listed virtual host</strong> that
+ <p> If no matching ServerName or ServerAlias is found in the set of
+ virtual hosts containing the most specific matching IP address and port
+ combination, then <strong>the first listed virtual host</strong> that
matches that will be used.</p></section>
</section>
module="core">VirtualHost</directive> is handled by the global
server configuration, regardless of the hostname or ServerName.</p>
- <p> When you add a name-based virtual host to an existing server, and
- the virtual host arguments match preexisting IP and port combinations,
+ <p> When you add a name-based virtual host to an existing server, and
+ the virtual host arguments match preexisting IP and port combinations,
requests will now be handled by an explicit virtual host. In this case,
it's usually wise to create a <a href="#defaultvhost">default virtual host</a>
- with a <directive module="core">ServerName</directive> matching that of
+ with a <directive module="core">ServerName</directive> matching that of
the base server. New domains on the same interface and port, but
requiring separate configurations, can then be added as subsequent (non-default)
virtual hosts.</p>
projects / apache / commitdiff