DragonFly On-Line Manual Pages

Search: Section:  


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

Search: Section: