| HTTPD.CONF(5) | 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 the following
main sections:
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, httpd(8) will listen on all IPv4 and IPv6 addresses. 0.0.0.0 means to listen on all IPv4 addresses and :: 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 quoted.
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:
ext_ip="10.0.0.1"
server "default" {
listen on $ext_ip port 80
}
Here are the settings that can be set globally:
chroot
directorydefault
type type/subtypeerrdocs
directorydirectory is relative to the
chroot.
Custom error documents are standalone “.html” files provided in one of the following ways:
In case the latter does not exist and there is no dedicated file available for a certain response code, the built-in error document will be used as fallback.
A custom error document may contain the following macros that will be expanded at runtime:
$HTTP_ERROR$RESPONSE_CODE$SERVER_SOFTWARElogdir
directoryprefork
numberThe configured web servers.
Each server section starts with a
declaration of the server name:
server
name {...}server match name {...}Followed by a block of options enclosed in curly braces:
alias
namealias match namealias option, but
match the name using pattern
matching instead of shell globbing rules, see
patterns(7).no] authenticate
[realm] with
htpasswdchroot and must be readable by the www user. Use
the no authenticate directive to disable
authentication in a location.block dropblock
[return code
[uri]]It is possible to rewrite the request to redirect it to a different external location. The uri may contain predefined macros that will be expanded at runtime:
$DOCUMENT_URI$QUERY_STRING$QUERY_STRING_ENC$REMOTE_ADDR$REMOTE_PORT$REMOTE_USER$REQUEST_SCHEME$REQUEST_URI$SERVER_ADDR$SERVER_PORT$SERVER_NAME$HTTP_HOSTlocation match
option.connection
optionmax request
body numbermax
requests numberrequest timeout
secondstimeout
secondsdefault
type type/subtypedirectory
optionno] auto indexindex
stringno
indexno] errdocs
directoryno keyword is given, disables
globally defined custom error documents for the current
server.no] fastcgi
[option]socket
[tcp] socket
[port]httpd passes HTTP requests to a FastCGI
handler listening on the socket socket. The
socket can either be a UNIX domain socket or a
TCP socket. If the FastCGI handler is listening on a UNIX domain
socket, socket is a local path name within the
chroot(2) root directory of
httpd(8) and defaults to
/run/slowcgi.sock. Alternatively if the
FastCGI handler is listening on a TCP socket,
socket is a hostname or an IP address. If the
port is not specified, it defaults to port
9000.strip
numberparam
variable valueThe FastCGI handler will be given the following variables by default:
DOCUMENT_ROOTroot option for the server or location that
matches the request.GATEWAY_INTERFACEHTTP_*HTTPSREQUEST_URIDOCUMENT_URIPATH_INFO appended to
SCRIPT_NAME.SCRIPT_NAMEPATH_INFOSCRIPT_FILENAMEQUERY_STRINGREMOTE_ADDRREMOTE_PORTREMOTE_USERREQUEST_METHODSERVER_ADDRSERVER_NAMESERVER_PORTSERVER_PROTOCOLSERVER_SOFTWARETLS_PEER_VERIFYgzip-staticIf gzip encoding is accepted and if the requested file exists with an additional .gz suffix, use the compressed file instead and deliver it with content encoding gzip.
hsts
[option]max-age
secondspreloadsubdomainslisten
on address [tls]
port numberlocation
[[not] found]
path {...}found (i.e. accessible) or
not found request paths only. In case of multiple
location statements in the same context, the first matching location
statement will be put into effect, while all later ones will be ignored.
Therefore it is advisable to match for more specific paths first and for
generic ones later on. A location section may include most of the server
configuration rules except alias,
connection, errdocs,
hsts, listen on,
location, tcp and
tls.location
[[not] found]
match path {...}location option, but
match the path using pattern
matching instead of shell globbing rules, see
patterns(7). The pattern may contain
captures that can be used in an enclosed block
return or request rewrite option.no] log
[option]access and error
log files, but can be changed per server or location. Use the
no log directive to disable logging of any
requests. Multiple options may be specified within curly braces. Valid
options are:
access
nameerror
namestyle
stylecommon, combined,
forwarded 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
forwarded extends the style
combined by appending two fields containing
the values of the headers X-Forwarded-For and
X-Forwarded-Port. The style
connection writes a summarized log entry after
each connection, that can have multiple requests, similar to the
format that is used by relayd(8).
If not specified, the default is common.no] syslogpassblock in a location.request
optionno] rewrite
pathblock return, this will change the
request path internally before httpd makes a
final decision about the matching location. The
path argument may contain predefined macros that
will be expanded at runtime. See the block
return option for the list of supported macros.strip
numberroot
directoryhttpd. If not specified, it defaults to
/htdocs.tcp
optionbacklog
numberip
minttl numberip
ttl numberno] nodelayno] sacksocket buffer
numbertls
optioncertificate
fileciphers
stringclient
ca cafile [crl
crlfile] [optional]optional is specified, request
but do not require) TLS client certificates whose authenticity can be
verified against the CA certificate(s) in cafile
in order to proceed beyond the TLS handshake. With
crl specified, additionally require that no
certificate in the client chain be listed as revoked in the CRL(s) in
crlfile. CA certificates and CRLs should be PEM
encoded.dhe
paramsecdhe
curveskey
filehttpd. The default is
/etc/ssl/private/server.key.ocsp
fileprotocols
stringticket
lifetime secondsConfigure 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, image/svg+xml, and
application/javascript.
The types section must include one or more
lines of the following syntax, enclosed in curly braces:
include
fileExample configuration files for httpd.conf
and acme-client(1) are provided in
/etc/examples/httpd.conf and
/etc/examples/acme-client.conf.
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 html htm
text/plain txt
image/gif gif
image/jpeg jpeg jpg
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 203.0.113.1 port 80
root "/htdocs/www.a.example.com"
}
server "www.b.example.com" {
listen on 203.0.113.1 port 80
root "/htdocs/www.b.example.com"
}
server "intranet.example.com" {
listen on 10.0.0.1 port 80
root "/htdocs/intranet.example.com"
}
Simple redirections can be configured with the
block directive:
server "example.com" {
listen on 10.0.0.1 port 80
listen on 10.0.0.1 tls port 443
block return 301 "$REQUEST_SCHEME://www.example.com$REQUEST_URI"
}
server "www.example.com" {
listen on 10.0.0.1 port 80
listen on 10.0.0.1 tls port 443
}
The request can also be rewritten with the
request rewrite directive:
server "example.com" {
listen on * port 80
location match "/old/(.*)" {
request rewrite "/new/%1"
}
}
htpasswd(1), patterns(7), httpd(8), ocspcheck(8), slowcgi(8)
The httpd(8) program was written by Reyk Floeter <reyk@openbsd.org>.
| March 9, 2022 | OpenBSD-current |