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_SOFTWARE
logdir
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 drop
block
[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_HOST
location match
option.connection
optionmax request
body
numbermax
requests
numberrequest timeout
secondstimeout
secondsdefault
type
type/subtypedirectory
optionno
] auto index
index
stringno
index
no
] 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_ROOT
root
option for the server or location that
matches the request.GATEWAY_INTERFACE
HTTP_*
HTTPS
REQUEST_URI
DOCUMENT_URI
PATH_INFO
appended to
SCRIPT_NAME
.SCRIPT_NAME
PATH_INFO
SCRIPT_FILENAME
QUERY_STRING
REMOTE_ADDR
REMOTE_PORT
REMOTE_USER
REQUEST_METHOD
SERVER_ADDR
SERVER_NAME
SERVER_PORT
SERVER_PROTOCOL
SERVER_SOFTWARE
TLS_PEER_VERIFY
gzip-static
If 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
secondspreload
subdomains
listen
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
] syslog
pass
block
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
] nodelay
no
] sack
socket 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 |