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), which is
equipped with the additional functionality provided by the
httpd-plus
add-on package.
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 "example.com" { 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. If a request does not
match any server name, it is handled by the first defined
server
section that matches the listening port.
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.script
pathstrip
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 [[not
]
from
network ...] {...}found
(i.e. accessible) or
not found
request paths. Specifying
from
or not from
enables
client address filtering accepting or refusing connections from the
specified (whitespace separated) list of up to 16
network strings (formatted as outlined
here
with the exception that only decimal numbers are accepted) each being
matched either against the client's IP address or, in case a
network string is preceded by a ‘>’
character, against the content of the
X-Forwarded-For HTTP request header. If there was no
such header transmitted or the data transmitted could not be read as a
valid IP address, the unspecified address
0:0:0:0:0:0:0:0, resp. 0.0.0.0
will be silently used for matching instead. 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
[[not
] from
network ...] {...}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
no
] notify-on-block
option | {...}block
directive. If specified on server
level,
notify-on-block
will be inherited by all enclosed
locations unless no notify-on-block
is specified.
In case making the connection or sending the message fails (either because
of transmission error or timeout), a corresponding warning will be written
into the system log.
Options may be specified either one at a time or enclosed in curly braces. Valid options are:
message
string ... |
drop
cr
(‘\r
’) or
lf
(‘\n
’). The parts will be
concatenated in the given order.
Additionally, a string may contain the following macros which will be expanded at runtime:
$HTTP_HOST
Host
’ header.$HTTP_REFERRER
Referer
’ header.$HTTP_USER_AGENT
User-Agent
’ header.$REMOTE_ADDR
$REMOTE_PORT
$REMOTE_USER
$REQUEST_METHOD
$REQUEST_SCHEME
http
’
or
‘https
’).$REQUEST_URI
$RESPONSE_CODE
000
’ if the connection was
dropped.$RESPONSE_URI
Location
’ header.The following example defines a two line message, line 1
containing the client IP address, line 2 the requested URI, using
‘\n
’ as the newline
character:
notify-on-block { socket "/run/example.sock" message "$REMOTE_ADDR" lf \ "$REQUEST_URI" }
Here, the two string parts of the
message
internally concatenate and transform
to
message
"$REMOTE_ADDR\n$REQUEST_URI"
If drop
is specified instead of an
actual message, a previously (perhaps in a parent
server
) defined message will be deleted.
socket
pathno
] timeout
millistimeout
by specifying the
no
keyword. Defaults to 2000
milliseconds.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:
cache
string}] name ...cache
control header string may be specified. Each entry may end with an
optional semicolon. Later entries overwrite earlier entries.include
fileText enclosed by curly braces inside the
alias
name,
include
path, and
location
path parameters will
be handled as follows:
Comma-separated lists in the form
<list> ::= <text> |
<text> ',' <list>
expand according to the given list items, e.g.
alias
"server-{AAA,BBB,CCC,DDD}"
expands to
alias "server-AAA" alias "server-BBB" alias "server-CCC" alias "server-DDD"
Number sequences formatted as
<sequence> ::= <first>
'..' <last>
with <first>
and
<last>
as decimal numbers denoting the
respective elements expand as such, e.g.
include
"/etc/httpd-{19..47}.conf"
expands to
include "/etc/httpd-19.conf" include "/etc/httpd-20.conf" ... include "/etc/httpd-47.conf"
In case one of the special characters (‘{’, ‘}’ or ‘,’) is needed inside a brace extended parameter, a preceding back-slash (‘\’) serving as escape character is required. This also applies to the back-slash character itself, i.e. in case for some reason a back-slash character is needed inside the parameter, it must be passed as ‘\\’. Escaping a regular character will be silently ignored. Escape characters inside number sequence braces are not allowed and will make the number sequence silently being handled as if it was a list.
In case there are multiple brace sections inside a parameter, the following rules of thumb apply:
Another example is available below.
Example 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 "example.com" { listen on * port 80 } types { text/css css text/html html htm text/plain txt image/gif gif image/jpeg { cache "max-age=2592000, public" } 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 "example.com" { 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" } }
The location not found
option (here in
combination with the fastcgi script
override
directive) may be used to enable
WordPress
Pretty Permalinks just like on an Apache web server with
mod_rewrite installed.
server "www.example.com" { listen on * port www directory index "index.php" location not found "/*" { fastcgi { socket "/run/php-fpm.sock" script "/index.php" } } location "/*.php" { fastcgi socket "/run/php-fpm.sock" } }
WordPress, however, is unable to discover that httpd(8) is now capable to perform required URL rewrites. This will make the Permalink Settings Screen not behave as expected. Luckily, and for this case exactly, the got_url_rewrite hook exists. Adding the following line of code into the current theme's functions.php file will straighten things out.
add_filter('got_url_rewrite', '__return_true');
Brace expansion can help clarify configuration files in which
several location
sections share the same
content:
location
"/chapter/{A_0{1,2,5},F_{17..49}}-{B,C}/*" { ... }
replaces
location "/chapter/A_01-B/*" { ... } location "/chapter/A_01-C/*" { ... } location "/chapter/A_02-B/*" { ... } location "/chapter/A_02-C/*" { ... } location "/chapter/A_05-B/*" { ... } location "/chapter/A_05-C/*" { ... } location "/chapter/F_17-B/*" { ... } location "/chapter/F_17-C/*" { ... } ... location "/chapter/F_49-B/*" { ... } location "/chapter/F_49-C/*" { ... }
htpasswd(1), glob(7), patterns(7), httpd(8), ocspcheck(8), slowcgi(8)
The httpd(8) program was written by Reyk Floeter <reyk@openbsd.org>.
November 3, 2023 | OpenBSD |