Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OpenBSD-5.7)
Apropos / Subsearch:
optional field

HTTPD.CONF(5)               BSD File Formats Manual              HTTPD.CONF(5)

     httpd.conf -- HTTP daemon configuration file

     httpd.conf is the configuration file for the HTTP daemon, httpd(8).

     httpd.conf is divided into four main sections:

           User-defined variables may be defined and used later, simplifying
           the configuration file.

     Global Configuration
           Global settings for httpd(8).

           Listening HTTP web servers.

           Media types and extensions.

     Within the sections, a host address can be specified by IPv4 address,
     IPv6 address, interface name, interface group, or DNS hostname.  If the
     address is an interface name, httpd(8) will look up the first IPv4
     address and any other IPv4 and IPv6 addresses of the specified network
     interface.  If '*' is given as an address, it will be used as an alias
     for to listen on all IPv4 addresses.  Likewise, '::' can be used
     to listen on all IPv6 addresses.  A port can be specified by number or
     name.  The port name to number mappings are found in the file
     /etc/services; see services(5) for details.

     The current line can be extended over multiple lines using a backslash
     ('\').  Comments can be put anywhere in the file using a hash mark ('#'),
     and extend to the end of the current line.  Care should be taken when
     commenting out multi-line text: the comment is effective until the end of
     the entire block.

     Argument names not beginning with a letter, digit, or underscore must be

     Additional configuration files can be included with the include keyword,
     for example:

           include "/etc/httpd.conf.local"

     Macros can be defined that will later be expanded in context.  Macro
     names must start with a letter, digit, or underscore, and may contain any
     of those characters.  Macro names may not be reserved words (for example,
     directory, log, or root).  Macros are not expanded inside quotes.

     For example:

           server "default" {
                   listen on $ext_ip port 80

     Here are the settings that can be set globally:

     chroot directory
             Set the chroot(2) directory.  If not specified, it defaults to
             /var/www, the home directory of the www user.

     logdir directory
             Specifies the full path of the directory in which log files will
             be written.  If not specified, it defaults to /logs within the
             chroot(2) directory.

     prefork number
             Run the specified number of server processes.  This increases the
             performance and prevents delays when connecting to a server.
             httpd(8) runs 3 server processes by default.

     The configured web servers.

     Each server must have a name and include one or more lines of the follow-
     ing syntax:

     alias name
             Specify an additional alias name for this server.

     [no] authenticate [realm] with htpasswd
             Authenticate a remote user for realm by checking the credentials
             against the user authentication file htpasswd.  The file name is
             relative to the chroot and must be readable by the www user.  Use
             the no authenticate directive to disable authentication in a

     block drop
             Drop the connection without sending an error page.

     block [return code [uri]]
             Close the connection and send an error page.  If the optional
             return code is not specified, httpd(8) denies access with a '403
             Forbidden' response.  The optional uri argument can be used with
             return codes in the 3xx range to send a 'Location:' header for
             redirection to a specified URI.

             The url may contain predefined macros that will be expanded at

                   $DOCUMENT_URI  The request path.
                   $QUERY_STRING  The optional query string of the request.
                   $REMOTE_ADDR   The IP address of the connected client.
                   $REMOTE_PORT   The TCP source port of the connected client.
                   $REMOTE_USER   The remote user for HTTP authentication.
                   $REQUEST_URI   The request path and optional query string.
                   $SERVER_ADDR   The configured IP address of the server.
                   $SERVER_PORT   The configured TCP server port of the
                   $SERVER_NAME   The name of the server.

     connection option
             Set the specified options and limits for HTTP connections.  Valid
             options are:

             max request body number
                     Set the maximum body size in bytes that the client can
                     send to the server.  The default value is 1048576 bytes

             max requests number
                     Set the maximum number of requests per persistent HTTP
                     connection.  Persistent connections are negotiated using
                     the Keep-Alive header in HTTP/1.0 and enabled by default
                     in HTTP/1.1.  The default maximum number of requests per
                     connection is 100.

             timeout seconds
                     Specify the inactivity timeout in seconds for accepted
                     sessions.  The default timeout is 600 seconds (10 min-
                     utes).  The maximum is 2147483647 seconds (68 years).

     directory option
             Set the specified options when serving or accessing directories.
             Valid options are:

             [no] auto index
                     If no index file is found, automatically generate a
                     directory listing.  This is disabled by default.

             index string
                     Set the directory index file.  If not specified, it
                     defaults to index.html.

             no index
                     Disable the directory index.  httpd(8) will neither dis-
                     play nor generate a directory index.

     [no] fastcgi [socket socket]
             Enable FastCGI instead of serving files.  The socket is a local
             path name within the chroot(2) root directory of httpd(8) and
             defaults to /run/slowcgi.sock.

     listen on address [tls] port number
             Set the listen address and port.  This statement can be specified
             multiple times.

     location path {...}
             Specify server configuration rules for a specific location.  The
             path argument will be matched against the request path with shell
             globbing rules.  A location section may include most of the
             server configuration rules except connection, listen on, location
             and tcp.

     [no] log [option]
             Set the specified logging options.  Logging is enabled by default
             using the standard access and error log files, but can be changed
             per server or location.  Use the no log directive to disable log-
             ging of any requests.  Valid options are:

             access name
                     Set the name of the access log file relative to the log
                     directory.  If not specified, it defaults to access.log.

             error name
                     Set the name of the error log file relative to the log
                     directory.  If not specified, it defaults to error.log.

             style style
                     Set the logging style.  The style can be common, combined
                     or connection.  The styles common and combined write a
                     log entry after each request similar to the standard
                     Apache and nginx access log formats.  The style
                     connection writes a summarized log entry after each con-
                     nection, that can have multiple requests, similar to the
                     format that is used by relayd(8).  If not specified, the
                     default is common.

             [no] syslog
                     Enable or disable logging to syslog(3) instead of the log

     pass    Disable any previous block in a location.

     root option
             Configure the document root and options for the request path.
             Valid options are:

                     Set the document root of the server.  The directory is a
                     pathname within the chroot(2) root directory of httpd.
                     If not specified, it defaults to /htdocs.

             strip number
                     Strip number path components from the beginning of the
                     request path before looking up the stripped-down path at
                     the document root.

     tcp option
             Enable or disable the specified TCP/IP options; see tcp(4) and
             ip(4) for more information about the options.  Valid options are:

             backlog number
                     Set the maximum length the queue of pending connections
                     may grow to.  The backlog option is 10 by default and is
                     limited by the kern.somaxconn sysctl(8) variable.

             ip minttl number
                     This option for the underlying IP connection may be used
                     to discard packets with a TTL lower than the specified
                     value.  This can be used to implement the Generalized TTL
                     Security Mechanism (GTSM) according to RFC 5082.

             ip ttl number
                     Change the default time-to-live value in the IP headers.

             [no] nodelay
                     Enable the TCP NODELAY option for this connection.  This
                     is recommended to avoid delays in the data stream.

             [no] sack
                     Use selective acknowledgements for this connection.

             socket buffer number
                     Set the socket-level buffer size for input and output for
                     this connection.  This will affect the TCP window size.

     tls option
             Set the TLS configuration for the server.  These options are only
             used if TLS has been enabled via the listen directive.  Valid
             options are:

             certificate file
                     Specify the certificate to use for this server.  The file
                     should contain a PEM encoded certificate.

             ciphers string
                     Specify the TLS cipher string.  If not specified, the
                     default value "HIGH:!aNULL" will be used (strong crypto
                     cipher suites without anonymous DH).  See the CIPHERS
                     section of openssl(1) for information about SSL/TLS
                     cipher suites and preference lists.

             dhe params
                     Specify the DHE parameters to use for DHE cipher suites.
                     Valid parameter values are none, legacy and auto.  For
                     legacy a fixed key length of 1024 bits is used, whereas
                     for auto the key length is determined automatically.  The
                     default is none, which disables DHE cipher suites.

             ecdhe curve
                     Specify the ECDHE curve to use for ECDHE cipher suites.
                     Valid parameter values are none, auto and the short name
                     of any known curve.  The default is auto.

             key file
                     Specify the private key to use for this server.  The file
                     should contain a PEM encoded private key and reside out-
                     side of the chroot(2) root directory of httpd.

             protocols string
                     Specify the TLS protocols to enable for this server.  If
                     not specified, the default value "all" will be used (all
                     available protocols).  Refer to the
                     tls_config_parse_protocols(3) function for other valid
                     protocol string values.

     Configure the supported media types.  httpd(8) will set the Content-Type
     of the response header based on the file extension listed in the types
     section.  If not specified, httpd(8) will use built-in media types for
     text/css, text/html, text/plain, image/gif, image/png, image/jpeg, and

     The types section must include one or more lines of the following syntax:

     type/subtype name [name ...]
             Set the media type and subtype to the specified extension name.
             One or more names can be specified per line.  Each line may end
             with an optional semicolon.

     include file
             Include types definitions from an external file, for example

     The following example will start one server that is pre-forked two times
     and is listening on all local IP addresses.  It additionally defines some
     media types overriding the defaults.

           prefork 2

           server "default" {
                   listen on * port 80

           types {
                   text/css                        css
                   text/html                       htm html
                   text/txt                        txt
                   image/gif                       gif
                   image/jpeg                      jpg jpeg
                   image/png                       png
                   application/javascript          js
                   application/xml                 xml

     The server can also be configured to only listen on the primary IP
     address of the network interface that is a member of the "egress" group.

           server "default" {
                   listen on egress port 80

     Multiple servers can be configured to support hosting of different
     domains.  If the same address is repeated multiple times in the listen on
     statement, the server will be matched based on the requested host name.

           server "www.example.com" {
                   alias "example.com"
                   listen on * port 80
                   listen on * tls port 443
                   root "/htdocs/www.example.com"

           server "www.a.example.com" {
                   listen on port 80
                   root "/htdocs/www.a.example.com"

           server "www.b.example.com" {
                   listen on port 80
                   root "/htdocs/www.b.example.com"

           server "intranet.example.com" {
                   listen on port 80
                   root "/htdocs/intranet.example.com"

     Simple redirections can be configured with the block directive:

           server "example.com" {
                   listen on port 80
                   block return 301 "http://www.example.com/"

           server "www.example.com" {
                   listen on port 80

     The syntax of the types section is also compatible with the format used
     by nginx, so it is possible to include its mime.types file directly:

           include "/etc/nginx/mime.types"

     htpasswd(1), httpd(8)

     The httpd(8) program was written by Reyk Floeter <reyk@openbsd.org>.

BSD                             March 30, 2017                             BSD