Manual Reference Pages  - HTTPD.CONF (5)


httpd.conf - XS-httpd configuration file


     Global Options
     Global module options
     Socket Options
     Section Options
See Also


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/>
  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 CGI’s 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. Therefor 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.
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/lib/httpd>
  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.
  Location of the script that is used for internal handling of Perl CGI’s.
  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.
  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.
  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.
  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.
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 x509 certificate to be used for SSL connections. This may be an absolute path or relative to the configuration directory ( /usr/local/lib/httpd/conf). 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 x509 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.
SSLAuthentication Xo
.Bro Cm none Ns No | Ns Cm optional Ns No | Ns Cm strict Brc Aq 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 x509 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/lib/httpd/conf).
SSLCApath directory<>
  The location of the list of files containing x509 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/lib/httpd/conf). 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/lib/httpd/conf).
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/lib/httpd/conf). Both SSLCRLfile and SSLCRLpath may be set, in which case both locations will be checked for certificate revocation lists.
  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 with overmultiple 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/lib/httpd/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/lib/httpd).

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 retreived 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 Xo
.Bro Cm traditional Ns | Ns Cm combined Ns | Ns Cm virtual Brc Aq combined
  Defines the logfile format. Traditionally access and referrer logs will be split over two different files (‘commonlogfile format’), but using a combined accesslog is more common nowadays (‘extendedlogfile 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.htmlindex.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 controles if personal user directories (as defined in the Users section) will be made available through this virtual host. If access to personal webdirectories 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 browers 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.
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 seperately 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.


Refer to the httpd.conf.sample file that comes with the source distribution.


httpd(1), xsscripts(5), xsconf(5), mime.types(5)

The project homepage:

June 12, 2002 HTTPD.CONF (5) xs-httpd/3.5