DragonFly On-Line Manual Pages
HTTPD.CONF(5) DragonFly File Formats Manual HTTPD.CONF(5)
NAME
httpd.conf - XS-httpd configuration file
DESCRIPTION
The httpd.conf configuration file has the following general layout:
... global options ...
<System>
... options for main site ...
</System>
<Virtual>
... options for virtual host ...
</Virtual>
<Users>
... options for user homedirs ...
</Users>
<Socket>
... options for binding specific sockets ...
</Socket>
The file can have only one System and one Users section, but multiple
Virtual sections (one per virtual hostname). Keep in mind that there are
fall-back defaults for all options: you are not required to use a
configuration file and leaving out an option does not mean it will be
automatically disabled.
Option names and their values must be separated by whitespace. Option
values in the configuration file should not be quoted using single or
double quotation marks. Note that a boolean value in the configuration
file should always be entered as `true' or `false'.
The overview below includes default values listed in angle brackets,
however these defaults may be different on your system, depending on
compile time selections and detected system features. Any command line
options will override settings in your configuration file.
Global Options
The following options can be set in the global section:
PidFile filename </var/run/httpd.pid>
The file to store the current pid and the last startup command
line. This will be used by httpdc(1) for restarting and other
maintenance commands.
UserId username <nobody>
The username or numeric uid that will be used to process all
requests. This must not be the `root' superuser, however `nobody'
or `http' are good candidates.
GroupId groupname <nogroup>
The groupname or numeric gid that will be used to process all
requests.
ExecAsUser boolean <true>
If enabled, filenames and CGIs in a user directory will be read
and executed with the permissions of that user.
DefaultCharset charset <us-ascii>
The character set in which text documents will be displayed by
default. This can be overridden locally by .charset files. The
.charset file should contain one line which specifies the
character set that is used for all text files in that directory
(and any subdirectories).
UseVirtualUid boolean <false>
If enabled, files in virtual host directories will be retrieved
with the permissions of the owner over the virtual host rootdir.
This can be useful if different users maintain different sites.
VirtualHostDir directory </usr/local/lib/httpd>
When virtual hosts are enabled, the server also supports
"automatic" detection of virtual hostnames - that is without
specific Virtual blocks in the configuration file. If the given
directory contains subdirectories with names that match a
requested hostname, then this subdirectory will be used as the
HTML root directory for the virtual host data. The directory must
be an absolute path.
UseServerSideInclude boolean <true>
By default, all HTML files will be parsed for server-side include
directives. The output of CGI scripts with the filename prefix
`ssi-' will also be checked for server-side includes. However if
this setting is turned off, SSI directives will be ignored and
files are not checked (which may slightly increase performance of
the webserver).
UseLocalScript boolean <true>
If enabled, all directories will be checked for the presence of a
.xsscripts file - or the presence of Execute directives in
xsconf(5) files. These can be used to specify how files with
certain extensions should be handled by the webserver.
.xsscripts files use the exact same syntax as the global
script.methods file, see httpd(1) for details.
UseScriptArgs boolean <false>
If enabled, parameters passed to scripts with a GET request will
be passed as command line options to the CGI script, unless they
contain `=' (common name-value pairs). This is a mandatory, but
little-used, requirement of the CGI/1.1 standard. It is now
disabled by default, because many script writers don't seem to
expect command line arguments. Instead scripts tend to rely
exclusively on the QUERY_STRING environment variable for its
arguments, which always gets set, regardless of the parameter
contents.
For example, passing the -s option to a PHP-interpreted script,
could lead to the webserver inadvertently returning the script
source.
UseDnsLookup boolean <true>
By default, the IP addresses of incoming connections are resolved
through DNS and logged with hostname information. You can
disable this features by setting UseDnsLookup to `false'. Note
that this will also make the environment variable REMOTE_HOST
useless.
UseStrictHostname boolean <false>
Setting this option will disable the use of VirtualHostDir and
the fallback default site: only if the requested host exactly
matches a HostName or HostAlias entry, will the request be
accepted and any content displayed.
UseAcceptFilter boolean <false>
Some systems offer kernel support to delay an accept(2) call
until (appropriate) data has actually arrived on the socket. On
FreeBSD the accf_http(9) module can be used. Linux only has an
option to wait for any queued data. Both mechanisms can
effectively reduce the workload of the webserver, especially when
you are experiencing bogus connects. Only enable this option if
your system has indeed such a system.
UseETag boolean <false>
If this option is enabled, entity tags will be used for static
documents (anything that is not a CGI binary or contains server-
side include directives). Browsers and web-proxies can use this
tag to determine if their cached entries are still up-to-date.
Entity tag information is based on the file properties (such as
size and modification time) rather than the file contents.
Therefore it's fast to determine, but not perfect.
UseCoreDump boolean <false>
This option is used for debugging only and disabled by default.
If enabled, then coredumps may be generated when the program
triggers a segmentation fault, illegal instruction, bus error or
similar fatal error condition. Whether the core image is indeed
created will depend on other factors as well: write access for
the actual uid in the working directory (often /), available disk
space and system preferences about the desirability of uid-
shifting programs dumping their state on disk.
UseSendfile boolean <true>
Specify if sendfile(2) should be used to transfer (binary) data
files over an unencrypted connection (images, style sheets,
etc.). This may speed-up transfers of such files. However on some
systems it hinders rather than improves performance, so it is
possible to turn this off. This option has no effect when
sendfile is not available on your system.
UseContentMD5 boolean <false>
HTTP supports checksums to validate content integrity. At the
moment only MD5 checksums are supported in HTTP/1.1. If this
option is enabled (it's disabled by default), then all data will
include a Content-MD5 header, containing the base64 encoded
md5-checksum of the content. For dynamically generated data (CGI
of SSI chunked transfers) the md5 checksum will be added to the
trailers (headers following content). This option is only
available on systems with libmd.
UseTimestamp boolean <true>
This setting will disable timestamp-related functionality, such
as Date and Last-modified HTTP headers. This option is mandatory
to comply with RFC 2616. However, for (embedded) systems without
a reliable system clock, it make be useful to turn this off
anyway.
UsePut boolean <true>
Allow users to handle HTTP PUT and DELETE requests with local CGI
scripts. The actual handles must be set locally with the
PutScript and/or DeleteScript configuration directives as
explained in xsconf(5).
UseTrace boolean <false>
Allow handling of HTTP TRACE requests. This is a standard
(mandatory) HTTP command, but it may be considered a security
risk. Disabling this avoids exposing request information, such
as client cookies, but it can be enabled in development
environments.
UseSSLSessionTickets boolean <true>
Enable signed session tickets, which may be cached by clients.
This enables SSL session resumption, which may speed up the
initialisation of HTTPS connections.
UseSSLSessionStore boolean <false>
Maintain a local store with SSL session history. This enables
SSL session resumption, which may speed up the initialisation of
HTTPS connections. However, maintaining a consistent state
between server processes increases local I/O and may actually be
slower in some cases. This feature is still experimental.
Priority level <0>
The system priority that the daemon will be running at. A lower
priority causes more favorable scheduling.
ScriptPriority level <20>
The CPU priority that user CGI scripts will be running at. A
lower priority causes more favorable scheduling. The default
value is PRIO_MAX, which may cause scripts to respond quite
slowly, but at least your other processes won't be suffering too
much from broken scripts.
ScriptTimeout minutes <6>
The time a CGI script is allowed to run before it will be
considered runaway and killed by the server. The time should be
specified in minutes. Note that several browsers will kill a
connection even earlier than this.
ScriptCpuLimit minutes <2>
The amount of CPU time a CGI script is allowed to use before it
will be considered runaway and killed by the server. The time
should be specified in minutes.
ScriptEnvPath path
</bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin>
The PATH environment variable that should be presented to CGI
binaries. This must be a colon separated list of directories; no
sanity checking is done. A reasonable default is provided.
ScriptUmask mask <>
The umask that should be used when executing CGI scripts. The
umask(2) mode determines the default permissions of files that
are created. For example a umask value of `022' causes scripts to
be created with mode `644', which means they will only be
writable by the owner, but readable by all.
This setting has no effect on the permission mode of the logfiles
created by the webserver. By default, the system umask setting
will be used - that is the value that was active in the process
from which the webserver was started.
ServerIdent {full | branch | name | none} <full>
Set how much of the webserver version details should be included
in the Server header that is sent with every HTTP response. When
set to branch the major version number will be show (up to the
first space), with name only the software name will be revealed
(up to the first slash). The default behaviour is to send the
full release version details.
ProxyIdent {full | branch | name | none} <full>
Set how much of the webserver version details should be included
in the Via header that is sent with every proxy response where
data is obtained from another webserver. The options are the same
as for the ServerIdent directive.
Modules module [module ...] <*>
A list with the names of all dynamic modules that should be
loaded with the webserver (e.g. `perl, ldap'). When this option
is not present or specified as the special value `*' then a
default list of modules will be loaded. The list of default
modules can be queried with the command `httpd -v'.
The following options from old versions have been removed and are no
longer used in the installed version.
SystemRoot directory </usr/local/www/xshttpd>
Used to set the installation version for data and configuration
files. Files are now installed in diverse locations, specified
at compilation time. Per virtual host file locations (HTML data,
CGI scripts, icons, log files) can be set using directives listed
in the Section Options paragraph below.
Global module options
If webserver modules are enabled, additional configuration options may be
available in the global section. If the relevant module is not available,
then using such an option will generate a fatal error.
mod_perl
PerlPersistentScript <contrib/persistent.pl>
Location of the script that is used for internal handling
of Perl CGIs.
mod_bzip
UseGzipCompression <false>
Compress all data using gzip before sending it to the
client - if the client supports the gzip content
encoding. Enabling this option will affect performance,
but it should reduce bandwidth usage. There is currently
no setting to exclude certain (types of) files from this
compression once enabled.
mod_magic
MimeMagicFile <>
Location of the libmagic configuration file. If this is
set, then libmagic will be used as an alternative for
finding the MIME type of a file when the standard
mime.types(5) file doesn't give a conclusive result, for
instance when the requested filename does not include an
extension. This option should point to the main
configuration file, without any .mime or .mgc extension,
for example /usr/share/misc/magic.
mod_rpaf
RpafProxyIPs <>
List of IP addresses of reverse proxies sitting in front
of the webserver. The webserver will fake the connection
address for incoming connections coming from any of these
addresses. In stead of the proxy address, the IP address
from one of the request headers will be set as
REMOTE_ADDR on the webserver; so that scripts will think
connections come directly from the faked address.
RpafHeader <Client-IP>
Name of the header set by a reverse proxy that contains
the original IP address of an incoming connection. For
incoming connections from any of the reverse proxies
listed in RpafProxyIPs the address from this header will
be set as the connection address.
Socket Options
It is possible to bind to multiple sockets at the same time (e.g. http
and https, or IPv4 and IPv6), using multiple Socket blocks in the
configuration. The following options are valid within a Socket block:
ListenAddress hostname <>
The hostname or IP-address the webserver should bind on. If the
hostname resolves to multiple IP-addresses, the webserver will
only bind to the first address resolved.
ListenPort port <http>
The service name or port number to bind on. If you want to listen
to multiple ports, you can add more Socket blocks. The port may
be either a number or a service name; it defaults to https (443)
when SSL is enabled for this socket and http (80) otherwise.
ListenFamily {IPv4 | IPv6} <>
The address family to use: IPv6 may not be available on all
systems. The default is to leave the family unspecified - which
means that your operating system can choose: in this case the
httpd can even listen to both IPv4 and IPv6 addresses. Note that
most operation systems don't allow binding to multi-family
sockets, in which case you will need separate Socket blocks for
IPv4 and IPv6.
ListenProtocol {TCP | SCTP} <>
The IP protocol to use. The default is to use TCP. SCTP may not
be available on all systems.
SocketName key <>
A socket name is optional and should usually not be specified. If
such a key is present, then connections to this socket will not
use the default settings from the System section, but instead use
the settings from the Virtual section(s) with a matching
HostName.
Instances number <20>
The number of parallel services to run.
UseSSL boolean <false>
If enabled, use SSL instead of plain text. This can only be used
if SSL support is enabled at compile time. If this option is set
then the https (443) port will be used by default, instead of
http (80). Note that you may include both blocks with and without
UseSSL.
SSLCertificate filename <cert.pem>
The location of the X.509 certificate to be used for SSL
connections. This may be an absolute path or relative to the
configuration directory (/usr/local/etc/xshttpd). This file may
include a full certificate chain up to a trusted root. When
intermedicate certificates are used by the CA, they must be
listed in this file as well.
SSLPrivateKey filename <key.pem>
The location of the X.509 certificate's key to be used for SSL
connections. This may be contained in the same file as the
SSLCertificate file. Note that this key may be protected with a
secret passphrase. In that case the server will prompt for this
passphrase when started. Do not use passphrase protection when
you expect the server to start up automatically.
It is possible to list multiple certificates and private keys for
the same (virtual) host, but for different authentication
ciphers. These pairs must be listed with SSLCertificate and
SSLPrivateKey in matching order. Support for this is limited by
OpenSSL and does not work with certificate chains or OCSP. Avoid
using multiple keys whenever possible.
SSLNoCert boolean <false>
Enable SSL without using a server certificate. This will offer
encryption, but no authentication (aNULL, ADH). Setting this
option generally makes no sense for public websites and makes the
service vulnerable to man-in-the-middle attacks. This setting is
not compatible with SSLCertificate and SSLPrivateKey or SSL
virtual hosts. This option is only available within a Socket
block.
SSLAuthentication {none|optional|strict} <none>
This setting indicates whether clients connecting using https
should sent a client certificate to authenticate themselves. The
certificate exchange is part of the SSL handshake and thus
applies to all connections to the socket in which it is
specified.
The default is none: don't request a client certificate. When set
to optional, the client must send an identifying cert, but this
certificate won't be checked in any way (it may be self-signed).
The most secure setting is strict: all client certificates will
be checked and must validate against the list of root Certificate
Authorities. This implies SSLCAfile or SSLCApath: if neither is
set, checks will automatically (without further warning) fall
back to optional mode.
When SSLAuthentication is enabled, extra environment variables
are available in the CGI environment to offer details about the
client certificate subject and issuing organisation; see
httpd_cgi(7).
SSLCAfile filename <>
The location of the list of X.509 root certificates to be used
for validation of client certificates. This is unset by default;
although an example caroot.pem file is included in the
distribution. This may be an absolute path or a path relative to
the configuration directory (/usr/local/etc/xshttpd).
SSLCApath directory <>
The location of the list of files containing X.509 root
certificates to be used for validation of client certs. This is
unset by default. This may be an absolute path or a path
relative to the configuration directory (/usr/local/etc/xshttpd).
Both SSLCAfile and SSLCApath may be set, in which case both
locations will be checked for certification authority
certificates.
SSLCRLfile filename <>
The location of the certificate revocation lists to be used for
validation of client certificates. This is unset by default.
This may be an absolute path or a path relative to the
configuration directory (/usr/local/etc/xshttpd).
SSLCRLpath directory <>
The location of the certificate revocation lists to be used for
validation of client certs. This is unset by default. This may
be an absolute path or a path relative to the configuration
directory (/usr/local/etc/xshttpd). Both SSLCRLfile and
SSLCRLpath may be set, in which case both locations will be
checked for certificate revocation lists.
SSLOCSPfile filename <>
The location of the up-to-date OCSP file to be used for
validation of the server certificate via `OCSP Stapling'. When
`OCSP Stapling' is used, the signed OCSP information will be
presented to the client with the server certificate. Clients do
not need to contact the OCSP information from a server
themselves. In this configuration, an external process must
assure that the SSLOCSPfile is frequently refreshed, as these
tend to have short expiry times (typically between a day and a
week). This may be an absolute path or a path relative to the
database directory (/var/db/xshttpd).
SSLinfofile filename <>
The location of the server certificate information file.
Certificate info may contain data such as Certificate
Transparancy extensions or OCSP status information. This option
is only available when linked with a modern OpenSSL library. See
SSL_CTX_use_serverinfo_file(3) for details. This may be an
absolute path or a path relative to the database directory
(/var/db/xshttpd).
SSLCAlist
Sets the list of acceptable certificate authorities sent to the
client when requesting a client certificate. This only has any
effect when client certificates are requested by setting
SSLAuthentication to `optional' or `strict'.
SSLMatchSDN pcre <>
If SSLAuthentication is enabled (`optional' or `strict')and PCRE
support is compiled in, this expression should match the client
certificate subject as presented in the environment variable
SSL_CLIENT_S_DN. Otherwise the client certificate will be
rejected.
SSLMatchIDN pcre <>
If SSLAuthentication is enabled (`optional' or `strict')and PCRE
support is compiled in, this expression should match the client
certificate issuer as presented in the environment variable
SSL_CLIENT_I_DN. Otherwise the client certificate will be
rejected.
SSLCipherList ciphers <>
Restrict or extend the encryption ciphers that should be used for
SSL connections. The possible values for this setting are
described in ciphers(1).
Section Options
The following options can be set in any of the System, Virtual and Users
sections:
SSLTicketKey string <>
This value (in combination with the SSL private key) is used to
seed the key that protects SSL session tickets. When serving a
domain load-balanced over multiple servers, all webservers should
use the same value for the same domain. When not set, a fixed
default value will be used.
HostName hostname
The hostname of the server. This is required for a Virtual
section. For the System and Users sections it defaults to the
name of the machine.
HostAlias hostname [hostname ...] <>
One or more aliases for the previously mentioned hostname.
PathInfoScripts filename [filename ...]
</cgi-bin/imagemap /cgi-bin/xschpass>
One or more filenames (URIs) of scripts that should be executed
using the username path specified in the PATH_INFO argument.
HtmlDir directory <htdocs>
The main directory containing all the HTML files. This defaults
to /usr/local/www/xshttpd/htdocs for the main server and .html
for users (path relative to user's homedir). It is a mandatory
option in Virtual sections (path may be relative to
/usr/local/www/xshttpd).
For the Users section the special substring `%u' may be used in
this setting, which will be replaced with the user's login. There
is no need to use this for the home directory (as the path given
is relative to the homedir), but one might want to do something
like /data/www/%u/.
ExecDir directory <cgi-bin>
The directory containing the CGI scripts. This is the directory
as it is specified in the URL, which is not necessary the same as
the directory on disk.
PhExecDir directory <cgi-bin>
Physical CGI directory: this is the subdirectory where scripts
are stored on disk. However if you do not use the same value as
ExecDir, it is easy to get confused.
IconDir directory <icons>
Location where the icons used by xsindex(1) are to be found. When
encountered in an URL path prefix, files will be retrieved from
the PhIconDir directory rather than the normal path. Beware that
changing this setting only affects the behaviour of the webserver
and not the xsindex(1) program.
PhIconDir directory <icons>
Location where the icons used by xsindex(1) are to be stored on
disk.
LogAccess filename <>
Logfile to use for normal HTTP requests (answered with a 2xx
response). Instead of a filename, it is possible to log to an
external process using a pipe-symbol and full pathname. For
example to enable logging through cronolog:
LogAccess |/usr/local/sbin/cronolog /wwwsys/logs/access_%Y%m%d
LogError filename <>
Logfile or program to use for HTTP requests that trigger errors
(like file not found, 4xx responses).
LogScript filename <>
Logfile used to collect errors generated by CGI scripts. This
includes all data written to stderr by a user script and errors
from scripts that cannot be executed or produce invalid HTTP
response headers.
LogReferer filename <>
Logfile or program to use for HTTP referrer information. Note
that this is only used when LogStyle `traditional' is selected -
otherwise referrer information will be included in the standard
LogAccess file.
LogRefererIgnoreDomain domain <>
References coming from this domain will not be logged in the
LogReferer file. This is usually your local network domain. Note
that it is wise to start the domain with a dot (.) to match all
hosts in the domain as well. You may also give a machine name
instead of a domain name. Note: This only affects `traditional'
logging where a separate referrer logfile is used. It will be
ignored when using more modern log styles.
LogStyle {traditional|combined|virtual} <combined>
Defines the logfile format. Traditionally access and referrer
logs will be split over two different files (`common logfile
format'), but using a combined accesslog is more common nowadays
(`extended logfile format').The virtual format is basically a
combined log with an extra first field indicating the virtual
hostname that was accessed on the webserver.
RedirFile filename
Redirect all requests for this host according to the rules listed
in filename. This file uses the regular expression matching
rules detailed in xsredir(5). If this command is present,
HtmlDir must not be set. All requests are redirected; if none of
the rules match, a `404 not found' error will be returned.
IndexFiles filename [filename ...] <index.html index.htm index.xhtml
index.xml index.php>
Defines the filename(s) that should be used when the user asks
for a directory. The webserver will never auto-generate a
directory index: you can use xsindex(1) for that. You can specify
multiple filenames separated by commas or whitespace. The default
value of `index.html index.htm index.php' means that index.htm
will only be tried if index.html is not present, etc.
If this option is omitted for the Virtual or Users section, it
will default to the definition in the System block, or the
previously mentioned default if this is also unspecified.
UseUsers boolean <false>
This flag controls if personal user directories (as defined in
the Users section) will be made available through this virtual
host. If access to personal web directories is enabled, then
these will always be made available through the default System
host. However, by default personal directories cannot be
accessed through any virtual webhost definitions, unless this
option is explicitly set. This setting is only relevant in a
Virtual section and will be ignored if it is used in any other
section.
SocketName key <>
A socket name is optional and should usually not be specified. If
such a key is present, then this virtual section will only be
applied to listening sockets that match the same key. There may
be multiple sockets or Virtual sections with the same SocketName.
SSLCertificate filename <>
Set an SSLCertificate for this virtual host. This option is only
available when the SSL-library supports `server name indication'
(SNI).
SSLPrivateKey filename <>
Set an SSLPrivateKey for this virtual host. This option is only
available when the SSL-library supports `server name indication'
(SNI).
UseSTS boolean <false>
Enable HTTP Strict Transport Security for this virtual host. STS
sites should only be visited via SSL/TLS (https). Setting this
option will generate an HTTP redirect for visitors using the
insecure HTTP port and adds an extra `Strict-Transport-Security'
header for HTTPS pages. This instructs browsers to use HTTPS for
all further requests to this site. Note that the STSMaxAge
option must be set as well; without it STS will be explicitly
disabled.
SSLOCSPfile filename <>
The location of the up-to-date OCSP file to be used for
validation of the server certificate via OCSP Stapling. See the
description of this directive in the Section Options overview.
SSLinfofile filename <>
The location of the up-to-date server certificate information
file to be used for additional server certificate information.
See the description of this directive in the Section Options
overview.
STSMaxAge seconds <0>
Set the expiry time, in seconds remaining, indicating how long
HTTP Strict Transport Security will remain active for this site.
When the life-time expires, a user agent must check the headers
again before making assumptions about STS. Setting this value to
`0' explicitly disables STS (the default). This option must be
used in combination with UseSTS.
STSSubDomains boolean <false>
When this option is set, the HTTP Strict Transport Security
policy will be used for all sub domains as well. This is merely
an indication for the user agent: This does not change the
configuration of other virtual hosts. You must still add UseSTS
to the configuration block for DNS sub domains, if they are
defined separately in the webserver configuration.
FcgiSocket path <>
Set the path for communication with a FastCGI daemon. This path
can either be the filename of a UNIX domain socket or a
[hostname]:port specification. This setting is required in order
to use FastCGI. FastCGI is not available for the Users section.
FcgiPath path <>
The full pathname of the program that launches the FastCGI
daemon. This is only required if you want to launch the daemon
from within the webserver. It will use the standard uid of the
virtual host block in which it is defined. The path specification
may contain a %s argument which will automatically be replaced
with the FcgiSocket name specified in the same block.
PhpFcgiChildren number <16>
Specifically for the PHP FastCGI daemon, if launched by the
webserver. This sets the number of parallel FastCGI processes to
run.
PhpFcgiResults number <2000>
Specifically for the PHP FastCGI daemon, if launched by the
webserver. This sets the number of requests that each process
should handle. The child processes will automatically be
restarted by the FastCGI daemon after handling the specified
amount of requests.
EXAMPLES
Refer to the httpd.conf.sample file that comes with the source
distribution.
SEE ALSO
httpd(1), xsscripts(5), xsconf(5), mime.types(5)
The project homepage: http://www.xs-httpd.org/
xs-httpd/3.5 June 12, 2002 xs-httpd/3.5