h2o.conf(5) - FreeBSD Ports 15.1.quarterly Manual Pages

home | help

H2O.CONF(5) File Formats Manual H2O.CONF(5)

NAME
h2o.conf - The configuration file for H2O, the optimized HTTP/1.x, HTTP/2
server

SYNOPSIS
/etc/h2o/h2o.conf

DESCRIPTION
h2o.conf h2o.conf is a YAML configuration file.

QUICK START
In order to run the H2O standalone HTTP server, you need to write a config-
uration file. The minimal configuration file looks like as follows.

hosts:
"myhost.example.com":
listen:
port: 80
listen:
port: 443
ssl: {}
listen:
aport: 443
ssl: {}
type: quic
paths:
/:
file.dir: /path/to/the/public-files

user: nobody
access-log: /path/to/the/access-log
error-log: /path/to/the/error-log
pid-file: /path/to/the/pid-file

acme:
email: admin@myhost.example.com
accept-tos: YES

The configuration instructs the server to:

serve contents under the hostname: myhost.example.com for HTTP, listen on
TCP port 80 for HTTPS, listen on TCP port 443 and UDP port 443 serve files
under /path/to/the/public-files run under the privileges of nobody emit ac-
cess logs to file: /path/to/the/access-log emit error logs to
/path/to/the/error-log store the process id of the server in
/path/to/the/pid-file use ACME to fetch the TLS certificates automatically
(note: lego must be installed for this to work).

Enter the command below to start the server.

% sudo h2o -m daemon -c /path/to/the/configuration-file

The command instructs the server to read the configuration file, and start
in daemon mode, which dispatches a pair of master and worker processes that
serves the HTTP requests.

To stop the server, send SIGTERM to the server.

% sudo kill -TERM `cat /path/to/the/pid-file`

Next Step

Now that you know how to start and stop the server, the next step is to
learn the configuration directives and their structure, or see the configu-
ration examples.

SYNTAX AND STRUCTURE
Syntax

H2O uses YAML 1.1 as the syntax of its configuration file.

Levels of Configuration

When using the configuration directives of H2O, it is important to under-
stand that there are four configuration levels: global, host, path, exten-
sion.

Global-level configurations affect the entire server. Host-level configu-
rations affect the configuration for the specific hostname (i.e. corre-
sponds to the <VirtualHost> directive of the Apache HTTP Server). Path-
level configurations only affect the behavior of resources specific to the
path.

Extension-level configuration affect how files with certain extensions are
being served. For example, it is possible to map files with .php extension
to the FastCGI handler running the php-cgi command.

Consider the following example.

hosts:
"example.com":
listen:
port: 443
ssl:
certificate-file: etc/site1.crt
key-file: etc/site1.key
paths:
"/":
file.dir: htdocs/site1
"/icons":
file.dir: icons
expires: 1 day
"example.com:80":
listen:
port: 80
paths:
"/":
redirect: "https://example.com/"

In the example, two host-level configurations exist (under the hosts map-
ping), each of them listening to different ports. The first host listens
to port 443 using TLS (i.e. HTTPS) using the specified server certificate
and key. It has two path-level configurations, one for / and the other for
/icons, each of them pointing to different local directories containing the
files to be served. The latter also has the expires directive set, so that
Cache-Control: max-age=86400 [1] header would be sent. The second host ac-
cepts connections on port 80 (via the plain-text HTTP protocol), and redi-
rects all the requests to the first host using HTTPS.

Certain configuration directives can be used in more than one levels. For
example, the listen can be used either at the global level or at the host
level. Expires can be used at all levels. On the other hand file.dir can
only be used at the path level.

Path-level configuration

Values of the path-level configuration define the action(s) to be taken
when the server processes a request that prefix-matches to the configured
paths. Each entry of the mapping associated to the paths is evaluated in
the order they appear.

Consider the following example. When receiving a request for https://exam-
ple.com/foo, the file handler is first executed trying to serve a file
named /path/to/doc-root/foo as the response. In case the file does not ex-
ist, then the FastCGI handler is invoked.

hosts:
"example.com":
listen:
port: 443
ssl:
certificate-file: etc/site1.crt
key-file: etc/site1.key
paths:
"/":
file.dir: /path/to/doc-root
fastcgi.connect:
port: /path/to/fcgi.sock
type: unix

Starting from version 2.1, it is also possible to define the path-level
configuration as a sequence of mappings instead of a single mapping. The
following example is identical to the previous one. Notice the dashes
placed before the handler directives.

hosts:
"example.com":
listen:
port: 443
ssl:
certificate-file: etc/site1.crt
key-file: etc/site1.key
paths:
"/":
- file.dir: /path/to/doc-root
- fastcgi.connect:
port: /path/to/fcgi.sock
type: unix

Using YAML Alias

H2O resolves YAML aliases before processing the configuration file. There-
fore, it is possible to use an alias to reduce the redundancy of the con-
figuration file. For example, the following configuration reuses the first
paths element (that is given an anchor named default_paths) in the follow-
ing definitions.

hosts:
"example.com":
listen:
port: 443
ssl:
certificate-file: /path/to/example.com.crt
key-file: /path/to/example.com.crt
paths: &default_paths
"/":
file.dir: /path/to/doc-root
"example.org":
listen:
port: 443
ssl:
certificate-file: /path/to/example.org.crt
key-file: /path/to/example.org.crt
paths: *default_paths

Using YAML Merge

Since version 2.0, H2O recognizes Merge Key Language-Independent Type for
YAMLac Version 1.1. Users can use the feature to merge an existing mapping
against another. The following example reuses the TLS configuration of ex-
ample.com in example.org.

hosts:
"example.com":
listen:
port: 443
ssl: &default_ssl
minimum-version: TLSv1.2
cipher-suite: ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256
certificate-file: /path/to/example.com.crt
key-file: /path/to/example.com.crt
paths:
...
"example.org":
listen:
port: 443
ssl:
<<: *default_ssl
certificate-file: /path/to/example.org.crt
key-file: /path/to/example.org.crt
paths:
...

Including Files

Starting from version 2.1, it is possible to include a YAML file from the
configuration file using !file custom YAML tag. The following example ex-
tracts the TLS configuration into default_ssl.conf and include it multiple
times in h2o.conf.

Example: default_ssl.conf

minimum-version: TLSv1.2
cipher-suite: ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256
certificate-file: /path/to/example.com.crt
key-file: /path/to/example.com.crt

Example: h2o.conf

hosts:
"example.com":
listen:
port: 443
ssl: !file default_ssl.conf
paths:
...
"example.org":
listen:
port: 443
ssl:
<
Starting from version 2.3, it is possible to refer to an environment variable (intepreted as a scalar) from the configuration file by using !env custom YAML tag.

Example:
h2o.conf

hosts:
"example.com":
listen:
port: !env H2O_PORT
paths:
...

Notes:
[1]1 day is equivalent to 86400 seconds

BASE DIRECTIVES
This document describes the configuration directives common to all the pro-
tocols and handlers.

hosts
Maps host:port to the mappings of per-host configs.

The directive specifies the mapping between the authorities (the host or
host:port section of an URL) and their configurations. The directive is
mandatory, and must at least contain one entry.

When port is omitted, the entry will match the requests targetting the de-
fault ports (i.e. port 80 for HTTP, port 443 for HTTPS) with given host-
name. Otherwise, the entry will match the requests targetting the speci-
fied port.

Since version 1.7, a wildcard character * can be used as the first compo-
nent of the hostname. If used, they are matched using the rule defined in
RFC 2818 Section 3.1. For example, *.example.com will match HTTP requests
for both foo.example.com and bar.example.com.

For each HTTP request to be processed, the matching host entry is deter-
mined by the steps below:

Among the host elements that do not use wildcards, find the first element
that matches the host and port being specified by the URI. If none is
found in the previous step, find a matching element among the entries that
use wildcards. If none is found in the previous steps, use the first host
element without a strict-match flag.

When the hostname of the HTTP request is unknown (i.e., processing an
HTTP/1.0 request without a host header field), only the last step is being
used.

Example: A host redirecting all HTTP requests to HTTPS

hosts:
"www.example.com:80":
listen:
port: 80
paths:
"/":
redirect: https://www.example.com/
"www.example.com:443":
listen:
port: 443
ssl:
key-file: /path/to/ssl-key-file
certificate-file: /path/to/ssl-certificate-file
paths:
"/":
file.dir: /path/to/doc-root

paths
Mapping of paths and their configurations.

The mapping is searched using prefix-match. The entry with the longest
path is chosen when more than one matching paths were found. An 404 Not
Found error is returned if no matching paths were found.

Example: Configuration with two paths

hosts:
"www.example.com":
listen:
port: 80
paths:
"/":
file.dir: /path/to/doc-root
"/assets":
file.dir: /path/to/assets

In releases prior to version 2.0, all the path entries are considered as
directories. When H2O receives a request that exactly matches to an entry
in paths that does not end with a slash, the server always returns a 301
redirect that appends a slash.

Since 2.0, it depends on the handler of the path whether if a 301 redirect
that appends a slash is returned. Server administrators can take advantage
of this change to define per-path configurations (see the examples in
file.file and the FastCGI handler). file.dir is an exception that contin-
ues to perform the redirection; in case of the example above, access to
/assets is redirected to /assets/.

listen
Specifies the port at which the server should listen to.

In addition to specifying the port number, it is also possible to designate
the bind address or the SSL and HTTP/3 (QUIC) configuration.

Example: Various ways of using the Listen Directive

# accept HTTP on port 80 on default address (both IPv4 and IPv6)
listen: 80

# accept HTTP on 127.0.0.1:8080
listen:
host: 127.0.0.1
port: 8080

# accept HTTPS on port 443
listen:
port: 443
ssl:
key-file: /path/to/key-file
certificate-file: /path/to/certificate-file

# accept HTTPS on port 443 (using PROXY protocol)
listen:
port: 443
ssl:
key-file: /path/to/key-file
certificate-file: /path/to/certificate-file
proxy-protocol: ON

To configure HTTP/3 (QUIC), see HTTP/3.

Configuration Levels

The directive can be used either at global-level or at host-level. At
least one listen directive must exist at the global level, or every host-
level configuration must have at least one listen directive.

Incoming connections accepted by global-level listeners will be dispatched
to one of the host-level contexts with the corresponding host:port, or to
the first host-level context if none of the contexts were given host:port
corresponding to the request.

Host-level listeners specify bind addresses specific to the host-level con-
text. However it is permitted to specify the same bind address for more
than one host-level contexts, in which case hostname-based lookup will be
performed between the host contexts that share the address. The feature is
useful for setting up a HTTPS virtual host using Server-Name Indication
(RFC 6066).

Example: Using host-level listeners for HTTPS virtual-hosting

hosts:
"www.example.com:443":
listen:
port: 443
ssl:
key-file: /path/to/www_example_com.key
certificate-file: /path/to/www_example_com.crt
paths:
"/":
file.dir: /path/to/doc-root_of_www_example_com
"www.example.jp:443":
listen:
port: 443
ssl:
key-file: /path/to/www_example_jp.key
certificate-file: /path/to/www_example_jp.crt
paths:
"/":
file.dir: /path/to/doc-root_of_www_example_jp

SSL Attribute

The ssl attribute must be defined as a mapping.

The identity of the TLS listener is specified in one of the following ways:

by specifying the certificate-file and key-file attributes directly under
ssl, by specifying a sequence of certificate- and key-file pairs inside
identity, or if neither of the above is used, the identity is obtained us-
ing ACME; see acme.

The certificate-file attribute specifies the path of a PEM file containing
either an X.509 certificate chain or a raw public key. When the latter
form is being used, RFC 7250 handshake will be used.

The key-file attribute specifies the path of a PEM file that contains the
corresponding private key.

The identity attribute can be used in place of certificate-file and key-
file to specify more than one pair of certificates and keys. When a TLS
handshake is performed, h2o uses the first pair that contains a compatible
certificate / key. The last pair acts as the fallback.

Example: Using both RSA and ECDSA certificates

ssl:
identity:
- certificate-file: /path/to/ecdsa.crt # prefer ECDSA if client supports both
key-file: /path/to/ecdsa.key
- certificate-file: /path/to/rsa.crt. # use RSA if ECDSA is not supported
key-file: /path/to/rsa.key

In addition, the ssl mapping recognizes the following attributes.

client-ca-file:

path to a file of Certificate Authority (CA) certificates used to verify
client certificates. If set, H2O will request a client certificate from
connecting clients and validate it against these CAs. Connections lacking
a valid client certificate (either not provided or not signed by one of the
given CAs) will be rejected. This enables mutual TLS (mTLS) authentica-
tion.

cipher-suite: list of cipher suites to be passed to OpenSSL via
SSL_CTX_set_cipher_list cipher-suite-tls1.3: list of TLS 1.3 cipher suites
to use; the list must be a YAML sequence where each element specifies the
cipher suite using the name as registered to the IANA TLS Cipher Suite Reg-
istry; e.g., TLS_AES_128_GCM_SHA256, TLS_CHACHA20_POLY1305_SHA256. cipher-
preference:

side of the list that should be used for selecting the cipher-suite; should
be either of: client, server. Default is client.

dh-file:

path of a PEM file containing the Diffie-Hellman parameters to be used.
Use of the file is recommended for servers using Diffie-Hellman key agree-
ment. (optional)

key-exchange-tls1.3: list of TLS 1.3 key exchange algorithms to use; the
list must be a YAML sequence of algorithms. x25519 and secp256r1 are sup-
ported and enabled by default. In addition, secp384r1, secp521r1, and
x25519mlkem768 might be available if they are supported by libcrypto. max-
tickets:

maximum number of TLS/1.3 session tickets to send, when the client requests
for them using the ticket_request extension. Default is 4.

minimum-version:

minimum protocol version, should be one of: SSLv2, SSLv3, TLSv1, TLSv1.1,
TLSv1.2, TLSv1.3. Default is TLSv1.

min-version:

synonym of minimum-version (introduced in version 2.2)

maximum-version:

maximum protocol version. Introduced in version 2.2. Default is the maxi-
mum protocol version supported by the server.

max-version:

synonym of maximum-version.

ocsp-max-failures:

number of consecutive OCSP query failures before stopping to send OCSP sta-
pling data to the client. Default is 3.

ocsp-update-interval:

interval for updating the OCSP stapling data (in seconds), or set to zero
to disable OCSP stapling. Default is 14400 (4 hours).

neverbleed:

unless set to OFF, H2O isolates SSL private key operations to a different
process by using Neverbleed. Default is ON.

ssl-session-resumption directive is provided for tuning parameters related
to session resumption and session tickets.

ech:

This experimental attribute controls the use of TLS Encrypted Client Hello
extension (draft-15). The attribute takes a sequence of mappings, each of
them defining one ECH configuration.

Example: Encrypted Clint hello

ssl:
key-file: /path/to/rsa.key
certificate-file: /path/to/rsa.crt
ech:
- key-file: /path/to/ech.key
config-id: 11
public-name: public-name.example.net
cipher-suite: [ HKDF-SHA256/AES-128-GCM ]

The example above defines one ECH configuration that uses /path/to/ech.key
as the semi-static ECDH key with a config-id of 11, with the public-name
being public-name.example.net, and the HPKE SymmetricCipherSuite being
HKDF-SHA256/AES-128-GCM.

In addition to these four attributes, following attributes may be speci-
fied.

max-name-length specifies the maximum-name-length field of an ECH confgura-
tion (default: 64).

advertise takes either YES (default) or NO as the argument. This argument
indicates if given ECH configuration should be advertised as part of
retry_configs (draft-ietf-tls-esni-15; section 5).

When removing a stale ECH configuration, its advertise attribute should be
set at first to NO so that the stale configuration would not be advertised.
Then, after waiting for the expiry of caches containing the stale configu-
ration, the stale ECH configuration can be removed. This may take long de-
pending on the TTL of the HTTPS / SVC DNS resource record advertising the
configuration.

The ech attribute must be set only in the first ssl attribute that binds to
a particular address.

The CC Attribute

The CC attribute specifies the congestion controller to be used for incom-
ing HTTP connections.

For TCP connections, the congestion controller is set using the TCP_CONGES-
TION socket option on platforms that have support for that socket option.
To find out the default and the list of supported congestion controllers,
please refer to man 7 tcp. If the platform does not have support for that
socket option, the attribute has no effect.

For QUIC connections, the congestion controller is one of Reno, Cubic,
Pico. The default is Reno.

The Initcwnd Attribute

The initcwnd attribute specifies the initial congestion window of each in-
coming HTTP connection in the unit of packets. At the moment, this option
only applies to QUIC. It has no effect for TCP connections.

The Proxy-Protocol Attribute

The proxy-protocol attribute (i.e. the value of the attribute must be ei-
ther ON or OFF) specifies if the server should recognize the information
passed via "the PROXY protocol in the incoming connections. The protocol
is used by L4 gateways such as AWS Elastic Load Balancing to send peer ad-
dress to the servers behind the gateways.

When set to ON, H2O standalone server tries to parse the first octets of
the incoming connections as defined in version 1 of the specification, and
if successful, passes the addresses obtained from the protocol to the web
applications and the logging handlers. If the first octets do not accord
with the specification, it is considered as the start of the SSL handshake
or as the beginning of an HTTP request depending on whether if the ssl at-
tribute has been used.

Default is OFF.

The Sndbuf and Rcvbuf Attributes

The sndbuf and rcvbuf attributes specify the send and receive buffer size
for each TCP or UNIX socket used for accepting incoming HTTP connections.
If set, the values of these attributes are applied to the sockets using
SO_SNDBUF and SO_RCVBUF socket options.

These attributes have no effect for QUIC connections.

Listening to a Unix Socket

If the type attribute is set to unix, then the port attribute is assumed to
specify the path of the unix socket to which the standalone server should
bound. Also following attributes are recognized.

owner

username of the owner of the socket file. If omitted, the socket file will
be owned by the launching user.

group

name of the group of the socket file. If omitted, group ID associated to
the socket file will be the group ID of the owner.

permission

an octal number specifying the permission of the socket file. Many operat-
ing systems require write permission for connecting to the socket file. If
omitted, the permission of the socket file will reflect the umask of the
calling process.

Example: Listening to a Unix Socket accessible only by www-data

listen:
type: unix
port: /tmp/h2o.sock
owner: www-data
permission: 600

acme
Set the parameters for automatic certificate management using ACME (e.g.,
Letsencrypt).

Unless a custom loader program is specified, h2o obtains certificates from
Let's Encrypt using the popular ACME client: Lego. On most distributions,
Lego should be available as pre-build packages.

This directive takes two mandatory and one optional parameters.

email (mandatory) The email address to be registered to the ACME service
provider. accept-tos (mandatory) Must be set to YES to accept the terms of
service of the ACME service provider. loader (optional) The program to be
launched for issuing and renewing the certificates. If omitted,
H2O_ROOT/share/h2o/acme/lego-loader is used.

The below example shows a configuration that relies on ACME for serving
https://example.org.

Example: Simple h2o.conf using ACME

acme:
email: admin@example.org # email address to be used when contacting Let's Encrypt
accept-tos: YES # consent to the Terms of Service of Let's Encrypt
hosts:
example.org:
listen:
port: 80
listen:
port: 443
ssl: {} # omission on an identity indicates the use of ACME
paths:
...

The certificates and keys being issued or generated are stored under the
$prefix/var/h2o/acme directory. Output of the lego command (including er-
rors) are emitted to the error log of h2o.

capabilities
Set capabilities to be added to the process before dropping root privi-
leges.

This directive can be used only on Linux. The argument is a YAML sequence
of capabilites, where each capability is a name that is accepted by
cap_from_name. See man 7 capabilities for details.

error-log
Path of the file to which error logs should be appended.

Default is stderr.

If the path starts with |, the rest of the path is considered as a command
to which the logs should be piped.

Example: Log errors to file

error-log: /path/to/error-log-file

Example: Log errors through pipe

error-log: "| rotatelogs /path/to/error-log-file.%Y%m%d 86400"

See also:

Reorganizing Website Architecture for HTTP/2 and Beyond pp.14-21

The following describes the configuration directives for controlling the
HTTP/2 protocol handler.

http2-casper
Configures CASPer (cache-aware server-push).

When enabled, H2O maintains a fingerprint of the web browser cache, and
cancels server-push suggested by the handlers if the client is known to be
in possession of the content. The fingerprint is stored in a cookie named
h2o_casper using Golomb-compressed sets (a compressed encoding of Bloom
filter).

If the value is OFF, the feature is disabled. Push requests (made by the
handlers through the use of Link: rel=preload header) are processed regard-
less of whether if client already has the responses in its cache. If the
value is ON, the feature is enabled with the defaults value specified be-
low. If the value is mapping, the feature is enabled, recognizing the fol-
lowing attributes.

capacity-bits: number of bits used for the fingerprinting. Roughly speak-
ing, the number of bits should be log2(1/P * number-of-assets-to-track)
where P being the probability of false positives. Default is 13, enough
for tracking about 100 asset files with 1/100 chance of false positives
(i.e. log2(100 * 100) =~ 13). tracking-types: specifies the types of the
content tracked by casper. If omitted or set to blocking-assets, maintains
fingerprint (and cancels server push) for resources with mime-type of high-
est priority. If set to all, tracks all responses.

It should be noted that the size of the cookie will be log2(P) * number-of-
assets-being-tracked bits multiplied by the overhead of Base 64 encoding
(4/3). Therefore with current cookie-based implementation, it is necessary
in many cases to restrict the resources being tracked to those have signif-
icant effect to user-perceived response time.

Example: Enabling CASPer

http2-casper: ON

# `ON` is equivalent to:
# http2-casper:
# capacity-bits: 13
# tracking-types: blocking-assets

See also: file.mime.addtypes, issue #421

http2-debug-state
A directive to turn on the HTTP/2 Implementation Debug State.

This experimental feature serves a JSON document at the fixed path /.well-
known/h2/state, which describes an internal HTTP/2 state of the H2O server.
To know the details about the response fields, please see the spec. This
feature is only for developing and debugging use, so it's highly recom-
mended that you disable this setting in the production environment.

The value of this directive specifies the property set contained in the re-
sponse. Available values are minimum or hpack. If hpack is specified, the
response will contain the internal hpack state of the same connection. If
minimum is specified, the response doesn't contain the internal hpack
state.

In some circumstances, there may be a risk of information leakage on pro-
viding an internal hpack state. For example, the case that some proxies ex-
ist between the client and the server, and they share the connections among
the clients. Therefore, you should specify hpack only when the server runs
in the environments you can completely control.

This feature is considered experimental yet. For now, the implementation
conforms to the version draft-01 of the specification.

See also: HTTP/2 Implementation Debug State (draft-01)

http2-idle-timeout
Timeout for idle connections in seconds.

http2-input-window-size
(since v2.3) Default window size for HTTP request body.

The value is the maximum amount of request body (in bytes) that can be sent
by the client in 1 RTT (round-trip time).

http2-max-streams
Maximum number of streams to advertise via HTTP2 SETTINGS_MAX_CONCUR-
RENT_STREAMS.

Limits the number of active requests that the proxy will accept on a
client connection. Also see "http2-max-concurrent-requests-per-connection"
which controls the number of requests that the proxy will process concur-
rently.

http2-max-concurrent-requests-per-connection
Maximum number of requests to be handled concurrently within a single
HTTP/2 connection.

The value cannot exceed 256.

http2-max-concurrent-streaming-requests-per-connection
Maximum number of streaming requests to be handled concurrently within a
single HTTP/2 connection.

The value cannot exceed 256.

http2-latency-optimization-min-rtt
(since v2.1) Minimum RTT (in milliseconds) to enable latency optimization.

Latency optimization is disabled for TCP connections with smaller RTT
(round-trip time) than the specified value. Otherwise, whether if the op-
timization is used depends on other parameters.

Setting this value to 4294967295 (i.e. UINT_MAX) effectively disables the
optimization.

http2-latency-optimization-max-additional-delay
(since v2.1) Maximum additional delay (as the ratio to RTT) permitted to
get latency optimization activated.

Latency optimization is disabled if the additional delay imposed by the in-
teraction between the OS and the TCP/IP stack is estimated to be greater
than the given threshold. Otherwise, whether if the optimization is used
depends on other parameters.

http2-latency-optimization-max-cwnd
(since v2.1) Maximum size (in octets) of CWND to get latency optimization
activated.

CWND is a per-TCP-connection variable that represents the number of bytes
that can be sent within 1 RTT.

The server will not use or stop using latency optimization mode if CWND be-
comes greater than the configured value. In such case, average size of
HTTP/2 frames buffered unsent will be slightly above the tcp_notsent_lowat
sysctl value.

http2-push-preload
(since v2.1) A boolean flag (ON or OFF) indicating whether if the server
should push resources when observing a link: rel=preload header.

http2-reprioritize-blocking-assets
A boolean flag (ON or OFF) indicating if the server should send contents
with highest priority before anything else.

To maximize the user-perceived responsiveness of a web page, it is essen-
tial for the web server to send blocking assets (i.e. CSS and JavaScript
files in ) before any other files such as images. HTTP/2 provides a way
for web browsers to specify such priorities to the web server. However, as
of Sep. 2015, no major web browsers except Mozilla Firefox take advantage
of the feature.

This option, when enabled, works as a workaround for such web browsers,
thereby improving experience of users using the web browsers.

Technically speaking, it does the following:

if the client uses dependency-based prioritization, do not reprioritize if
the client does not use dependency-based prioritization, send the contents
of which their types are given highest priority before any other responses

See also: file.mime.addtypes, HTTP/2 (and H2O) improves user experience
over HTTP/1.1 or SPDY

http2-graceful-shutdown-timeout
A timeout in seconds. How long to wait before closing the connection on
graceful shutdown. Setting the timeout to 0 deactivates the feature: H2O
will wait for the peer to close the connections.

http2-allow-cross-origin-push
(since v2.3) A boolean flag (ON or OFF) indicating whether if the server
should push resources belonging to a different authority.

http2-dos-delay
HTTP request processing delay to be applied when the client behavior is
suspicious, in the unit of milliseconds.

When the client behavior is suspicious and there is a concern of Denial-of-
Service attack, h2o stops processing requests arriving on the suspicious
connection for specified amount of time.

HTTP/3
HTTP/3 uses QUIC as the transport protocol. A listen directive with a type
attribute set to quic instructs the standalone server to bind to a UDP port
on which QUIC packets will be sent and received. The binding must have an
ssl attribute, as QUIC uses TLS/1.3 as the handshake protocol.

The example below setups a server that listens to both TCP port 443 and UDP
port 443 using the same certificate and private key.

First listen directive binds the server to TCP port 443 with specified cre-
dentials, marking that directive as an YAML alias called &listen_ssl.
Then, it reuses (YAML merge) the first listen directive, adding type: quic
to create a UDP port 443 binding for accepting QUIC connections.

Example: Serving HTTP/1,2 and 3 on port 443

listen: &listen_ssl
port: 443
ssl:
certificate-file: /path/to-ssl-certificate-file
key-file: /path/to/ssl-key-file
listen:
<Fine-tuning QUIC Behavior

To fine tune the behavior of QUIC, the quic attribute should be used in place of the type attribute specifying quic.
The quic attribute accepts following parameters.

amp-limit
Amount of data that can be sent to the client before the client address is validated; see section 8.1 of RFC 9000. Default is 3.
ecn
A boolean flag (either ON or OFF) indicating whether the server should use ECN signals to detect congestion. The default setting is ON. This flag affects the server's sending behavior. Regardless of this configuration, the server sends back ECN signals it receives using ACK_ECN frames.
handshake-timeout-rtt-multiplier
Handshake timeout in the unit of round-trip time. Default is 400.
jumpstart-default
Jumpstart enhances the slow start phase of congestion control by pacing a large number of packets for an entire round-trip time (RTT), allowing the server to assess the network's capacity sooner. This parameter specifies the number of packets sent during the jumpstart phase. The default value is zero, indicating that jumpstart is disabled for new connections.
jumpstart-max
Upon resuming QUIC connections, clients present tokens issued by the server that contain the bandwidth of the previous connection. This information enables the server to instantly match the previous send rate by adjusting the jumpstart window accordingly. This parameter sets a cap on the maximum size of the jumpstart window. If set to zero (the default), the server disregards the bandwidth values in the tokens. Nonetheless, the server may still initiate a jumpstart without using previous information, based on the jumpstart-default parameter.
max-initial-handshake-packets
Maximum number of Initial packets to be sent before the handshake is deemed to have failed. Default is 1,000.
max-streams-bidi
Maximum number of client-initated bi-directional streams. This parameter controls the HTTP request concurrency of a HTTP/3 connection. Default is 100.
max-udp-payload-size
See Section 18.2 of RFC 9000. Default is 1,472.
pacing
A boolean flag (either OFF or ON) indicating whether sent packets should be paced. The default setting is OFF.
qpack-encoder-table-capacity
Size of the QPACK encoder table. Default is 4,096.
respect-app-limited
This boolean flag (either OFF or ON) indicates whether the server should respect the notion of rate limited traffic when adjusting the size of the congestion window, as detailed in RFC 7661. The default setting is ON.
retry
A boolean flag (OFF or ON) indicating if a Retry packet should be used for validating the client address. Use of Retry packets mitigate denial-of-service attacks at the cost of incurring one additional round-trip for processing the handshake.
sndbuf, rcvbuf
Size of send and receive buffers, in the unit of bytes. Unlike the TCP counterparts that are per-connection, these buffers are associated to the listening port and applies to all the connections bound to that port.

The example below reuses a previous binding but sets the retry parameter to ON.

Example:
HTTP/3 endpoint using Retry packets

listen:
<
Also, properties such as congestion controller and initial congestion window can be tuned using the top-level attribute of listen.

HTTP/3 Directives

Aside from QUIC-level properties, configuration directives listed below are provided for tuning HTTP/3 behavior.

http3-graceful-shutdown-timeout
Maximum duration to retain HTTP/3 connections in half-closed state, in sec-
onds.

When a graceful shutdown of h2o is initiated, h2o at first sends a GOAWAY
frame indicating the clients that it is initiating shutdown, then after one
second, starts rejecting new HTTP requests (a.k.a. half-closed state).

This directive controls how long h2o should wait for the peer to close the
QUIC connection in this half-closed state, before exitting.

If set to zero, this timeout is disabled. h2o will not shut down until all
QUIC connections are closed by the clients or times out.

http3-gso
If Generic Segmentation Offload should be used when sending QUIC packets.

http3-idle-timeout
Idle timeout in the unit of seconds.

Unlike idle timeout of HTTP/1 and HTTP/2, this value should be small be-
cause it is faster to re-establish a new connection using 0-RTT than mi-
grating to a different port due to NAT rebinding.

http3-input-window-size
Default window size for HTTP request body.

See http2-input-window-size.

http3-max-concurrent-streaming-requests-per-connection
Maximum number of streaming requests to be handled concurrently within a
single HTTP/3 connection.

ACCESS LOG DIRECTIVES
This document describes the configuration directives of the access_log han-
dler.

access-log
The directive sets the path and optionally the format of the access log.

If the supplied argument is a scalar, it is treated as the path of the log
file, or if the value starts with a |, it is treated as a command to which
the log should be emitted.

The latter approach (i.e. |) needs to be used for rotating the logs. This
is because the log file is opened (or the command that emits the log is
spawned) before dropping privileges so that it can be owned by root or any
other user; therefore it cannot be reopened by the server process itself
once it starts running.

Example: Emit access log to file

access-log: /path/to/access-log-file

Example: Emit access log through pipe

access-log: "| rotatelogs /path/to/access-log-file.%Y%m%d 86400"

If the supplied argument is a mapping, its path property is considered as
the path of the log file or the pipe command, and the format property is
treated as the format of the log file. Starting from version 2.2, escape
property can be used to specify the escape sequence that should be used to
emit unsafe octets.

Two forms of escape sequences are supported. If apache is specified as the
value of the escape property, unsafe octets are emitted in the form of ,
where N is a hexadecimal number in lower case. If json is specified, un-
safe octets are emitted in the form of 00NN. apache is the default escape
method.

Example: Emit access log to file using Common Log Format

access-log:
path: /path/to/access-log-file
format: "%h %l %u %t
escape: apache

The list of format strings recognized by H2O is as follows.

Format StringDescription %%the percent sign %Alocal address (e.g. 4.5.6.7)
%bsize of the response body in bytes %Hrequest protocol as sent by the
client (e.g. HTTP/1.1) %hremote address (e.g. 1.2.3.4) %lremote logname
(always -) %mrequest method (e.g. GET, POST) %plocal port (%{local}p is a
synonym that is supported since version 2.2) %{remote}premote port (since
version 2.2) %qquery string (? is prepended if exists, otherwise an empty
string) %rrequest line (e.g. GET / HTTP/1.1) %sstatus code sent to client
(e.g. 200) %status code received from upstream (or initially generated)
%ttime when the request was received in format: [02/Jan/2006:15:04:05
-0700] %{FORMAT}ttime when the request was received using the specified
format. FORMAT should be an argument to strftime, or one of:

secnumber of seconds since Epoch msecnumber of milliseconds since Epoch
usecnumber of microseconds since Epoch msec_fracmillisecond fraction
usec_fracmicrosecond fraction

As an example, it is possible to log timestamps in millisecond resolution
using %{%Y/%m/%d:%H:%M:%S}t.%{msec_frac}t, which results in a timestamp
like 2006-01-02:15:04:05.000. %Urequested URL path, not including the
query string %uremote user if the request was authenticated (always -)
%Vrequested server name (or the default server name if not specified by the
client) %vcanonical server name %{VARNAME}erequest environment variable
(since version 2.3; see Logging Arbitrary Variable) %{HEADERNAME}ivalue of
the given request header (e.g. %{user-agent}i) %{HEADERNAME}ovalue of the
given response header sent to client (e.g. %{set-cookie}o) %<{HEADER-
NAME}ovalue of the response header received from upstream (or initially
generated) %{NAME}xvarious extensions. NAME must be one listed in the fol-
lowing tables. A dash (-) is emitted if the directive is not applicable to
the request being logged.

Access Timings NameDescription connect-timetime spent to establish the con-
nection (i.e. since connection gets accept(2)-ed until first octet of the
request is received) request-header-timetime spent receiving request head-
ers request-body-timetime spent receiving request body request-total-time-
sum of request-header-time and request-body-time process-timetime spent af-
ter receiving request, before starting to send response response-timetime
spent sending response durationsum of request-total-time, process-time, re-
sponse-time total-timesame as duration (since v2.3)

HTTP Message Sizes NameDescription request-header-bytesnumber of bytes used
to receive request headers in the protocol-specific encoded form response-
header-bytesnumber of bytes used to send response headers in the protocol-
specific encoded form request-header-text-bytessum of request header name
and value lengths after decoding response-header-text-bytessum of response
header name and value lengths before encoding request-header-countnumber of
request header fields response-header-countnumber of response header fields
request-body-bytesnumber of request body bytes received

Proxy Timings (since v2.3) NameDescription proxy.idle-timetime spent after
receiving request, before starting to connect to the upstream proxy.con-
nect-timetime spent to establish the connection (including SSL handshake)
proxy.request-timetime spent sending request (header and body)
proxy.process-timetime spent after sending request, before starting to re-
ceive response proxy.response-timetime spent receiving response proxy.to-
tal-timesum of proxy-request-time, proxy-process-time, proxy-response-time

Proxy (since v2.3) NameDescription proxy.request-bytesnumber of bytes used
by the proxy handler for sending the request (above TLS layer) proxy.re-
quest-bytes-headernumber of bytes used by the proxy handler for sending the
request header (above TLS layer) proxy.request-bytes-bodynumber of bytes
used by the proxy handler for sending the request body (above TLS layer)
proxy.response-bytesnumber of bytes used by the proxy handler for receiving
the response (above TLS layer) proxy.response-bytes-headernumber of bytes
used by the proxy handler for receiving the response header (above TLS
layer) proxy.response-bytes-bodynumber of bytes used by the proxy handler
for receiving the response body (above TLS layer)

Connection (since v2.0) NameDescription connection-id64-bit internal ID as-
signed to every client connection ssl.protocol-versionSSL protocol version
obtained from SSL_get_version ssl.session-reused1 if the SSL session was
reused, or 0 if not [1] ssl.session-idbase64-encoded value of the session
id used for resuming the session (since v2.2) ssl.ciphername of the cipher
suite being used, obtained from SSL_CIPHER_get_name ssl.cipher-bitsstrength
of the cipher suite in bits ssl.server-namehostname provided in Server Name
Indication (SNI) extension, if any

Upstream Proxy Connection (since v2.3) NameDescription proxy.ssl.protocol-
versionSSL protocol version obtained from SSL_get_version proxy.ssl.ses-
sion-reused1 if the SSL session was reused, or 0 if not proxy.ssl.cipher-
name of the cipher suite being used, obtained from SSL_CIPHER_get_name
proxy.ssl.cipher-bitsstrength of the cipher suite in bits

HTTP/2 (since v2.0) NameDescription http2.stream-idstream ID http2.prior-
ity.receivedcolon-concatenated values of exclusive, parent, weight
http2.priority.received.exclusiveexclusive bit of the most recent priority
specified by the client http2.priority.received.parentparent stream ID of
the most recent priority specified by the client http2.priority.re-
ceived.weightweight of the most recent priority specified by the client

Miscellaneous NameDescription errorrequest-level errors. Unless specified
otherwise by using the error-log.emit-request-errors directive, the same
messages are emitted to the error-log. (since v2.1)

The default format is %h %l %u %t "%r" %s %b "%{Referer}i" "%{User-
agent}i", a.k.a. the NCSA extended/combined log format.

Note that you may need to quote (and escape) the format string as required
by YAML (see Yaml Cookbook).

See also: error-log error-log.emit-request-errors

Notes:
[1]A single SSL connection may transfer more than one HTTP request.

ERRORDOC DIRECTIVES
This document describes the configuration directives of the errordoc han-
dler.

error-doc
Specifies the content to be sent when returning an error response (i.e. a
response with 4xx or 5xx status code).

The argument must be a mapping containing following attributes, or if it is
a sequence, every element must be a mapping with the following attributes.

status - three-digit number indicating the status code (or sequence of that
from version 2.3) url - URL of the document to be served

URL can either be absolute or relative. Only content-type, content-lan-
guage, set-cookie headers obtained from the specified URL are served to the
client.

Example: Set error document for 404 status

error-doc:
status: 404
url: /404.html

Example: Set error document for 500 and 503 status

error-doc:
- status: 500
url: /internal-error.html
- status: 503
url: /service-unavailable.html

Example: Set error document for 50x statuses (From version 2.3)

error-doc:
status: [500, 502, 503, 504]
url: /50x.html

EXPIRES DIRECTIVES
This document describes the configuration directives of the expires han-
dler.

expires
An optional directive for setting the Cache-Control: max-age= header.

if the argument is OFF the feature is not used if the value is NUMBER UNIT
then the header is set the units recognized are: second, minute, hour, day,
month, year
the units can also be in plural forms

Example: Set Cache-Control: max-age=86400

expires: 1 day

You can also find an example that conditionally sets the header depending
on the aspects of a request in Modifying the Response section of the Mruby
directives documentation.

FASTCGI DIRECTIVES
This document describes the configuration directives of the FastCGI han-
dler.

The configuration directives of the FastCGI handler can be categorized into
two groups. Fastcgi.connect and fastcgi.spawn define the address (or the
process) to which the requests should be sent. Other directives customize
how the connections to the FastCGI processes should be maintained.

fastcgi.connect
The directive specifies the address at where the FastCGI daemon is running.

If the argument is a mapping, following properties are recognized.

host name (or IP address) of the server running the FastCGI daemon (ignored
if type is unix) port TCP port number or path to the unix socket type ei-
ther tcp (default) or unix

If the argument is a scalar, the value is considered as a TCP port number
and the host is assumed to be 127.0.0.1.

Example: Map /app to FastCGI daemon listening to /tmp/fcgi.sock

hosts:
"example.com:80":
paths:
"/app":
fastcgi.connect:
port: /tmp/fcgi.sock
type: unix

fastcgi.document_root
Sets the DOCUMENT_ROOT variable to be passed to the FastCGI application.

fastcgi.spawn
The directive specifies the command to start the FastCGI process manager.

In contrast to fastcgi.connect that connects to a FastCGI server running
externally, this directive launches a FastCGI process manager under the
control of H2O, and terminates it when H2O quits. The argument is a
/bin/sh -c expression to be executed when H2O boots up. The HTTP server
records the process id of the expression, and sends SIGTERM to the id when
it exits.

Example: Map .php files to 10 worker processes of /usr/local/bin/php-cgi

file.custom-handler:
extension: .php
fastcgi.spawn: "PHP_FCGI_CHILDREN=10 exec /usr/local/bin/php-cgi"

Example: Map any executable file in path /var/www/data/cgi-bin to fastcgi-
cgi wrapper

"/cgi-bin":
file.dir: /var/www/data/cgi-bin
file.custom-handler:
extension: default # means "no extension" in this case
fastcgi.spawn:
command: "exec /usr/local/share/h2o/fastcgi-cgi"

As of version 1.4.0, the spawned process is run under the privileges of
user specified by the user directive (in version 1.3.x, the FastCGI process
was spawned under the privileges that spawned the H2O standalone server).
It is possible to specify a different user for running the FastCGI process,
by providing a mapping that contains an attribute named user together with
an attribute named command.

Example: Running FastCGI processes under user fastcgi

file.custom-handler:
extension: .php
fastcgi.spawn:
command: "PHP_FCGI_CHILDREN=10 exec /usr/local/bin/php-cgi"
user: fastcgi

fastcgi.timeout.io
Sets the I/O timeout of connections to the FastCGI process in milliseconds.

fastcgi.timeout.keepalive
Sets the keepl-alive timeout for idle connections in milliseconds.

FastCGI connections will not be persistent if the value is set to zero (de-
fault).

fastcgi.send-delegated-uri
Send the modified HTTP_HOST and REQUEST_URI being rewritten in case of in-
ternal redirect.

In H2O, it is possible to perform internal redirects (a.k.a. delegations or
URL rewrites) using the redirect directive or by returning X-Reproxy-URL
headers from web applications. The directive specifies whether to send the
original values to the FastCGI process (default), or if the rewritten val-
ues should be sent.

FILE DIRECTIVES
This document describes the configuration directives of the file handler -
a handler that for serving static files.

Two directives: file.dir and file.file are used to define the mapping.
Other directives modify the behavior of the mappings defined by the two.

file.custom-handler
The directive maps extensions to a custom handler (e.g. FastCGI).

The directive accepts a mapping containing configuration directives that
can be used at the extension level, together with a property named exten-
sion specifying a extension (starting with .) or a sequence of extensions
to which the directives should be applied. If all the files (including
those without extensions) shall be mapped, this property must be set to de-
fault. Only one handler must exist within the directives.

Example: Mapping PHP files to FastCGI

file.custom-handler:
extension: .php
fastcgi.connect:
port: /tmp/fcgi.sock
type: unix

file.dir
The directive specifies the directory under which should be served for the
corresponding path.

Example: Serving files under different paths

paths:
"/":
file.dir: /path/to/doc-root
"/icons":
file.dir: /path/to/icons-dir

See also: file.dirlisting, file.file, file.index

file.dirlisting
A boolean flag (OFF, or ON) specifying whether or not to send the directory
listing in case none of the index files exist.

See also: proxy.ssl.cafile

proxy.timeout.connect
(since v2.3) Sets the timeout before establishing the upstream in millisec-
onds.

When connecting to a TLS upstream, this timeout will run until the end of
the SSL handshake.

proxy.timeout.first_byte
(since v2.3) Sets the timeout before receiving the first byte from up-
stream.

This sets the maxium time we will wait for the first byte from upstream,
after the establishment of the connection.

proxy.timeout.io
Sets the upstream I/O timeout in milliseconds.

This value will be used for proxy.timeout.connect and proxy.time-
out.first_byte as well, unless these parameters are explicitely set.

proxy.timeout.keepalive
Sets the upstream timeout for idle connections in milliseconds.

Upstream connection becomes non-persistent if the value is set to zero.
The value should be set to something smaller than that being set at the up-
stream server.

proxy.tunnel
A boolean flag (ON or OFF) indicating whether or not to allow tunnelling to
the backend server.

When set to ON, CONNECT requests and WebSocket handshakes are forwarded to
the backend server. Then, if the backend server accepts those requests,
H2O forwards the HTTP response to the client and acts as a bi-directional
tunnel.

Timeouts are governed by properties proxy.timeout.connect and proxy.time-
out.io.

proxy.zerocopy
Sets the use of zerocopy operations for forwarding the response body.

By default, this flag is set to OFF, in which case the response bytes are
read from the upstream socket to an internal buffer as they arrive, then
shipped to the client. Maximum size of this buffer is controlled by
proxy.max-buffer-size. The drawback of this approach is that it causes
pressure on memory bandwidth.

This knob provides two alternative modes to remedy the pressure:

When set to enabled, if zerocopy operation in supported by the downstream
connection (i.e., downstream connection being cleoartext or encrypted using
kernel TLS), h2o uses a pipe as an internal buffer instead of using user-
space memory. Data is moved to the pipe using the splice system call, then
shipped to the downstream connection by another call to splice. Pressure
to memory bandwidth is eliminated, as the splice system call merely moves
the references to kernel memory between file descriptors.

When set to always, data from upstream is spliced into a pipe regardless of
downstream connection providing support for zerocopy. When the downstream
connection does not support zerocopy, data is intially moved into the pipe,
then gets read and written to the socket (as well as being encrypted, if
necessary) as late as it becomes possible to send the data. This approach
does not reduce the total amount of bytes flowing through the CPU, but re-
duces the amount of userspace memory used by h2o by delaying the reads,
thereby reducing cache spills.

See also: proxy.max-spare-pipes, ssl-offload

REDIRECT DIRECTIVES
This document describes the configuration directives of the redirect han-
dler.

redirect
Redirects the requests to given URL.

The directive rewrites the URL by replacing the host and path part of the
URL at which the directive is used with the given URL. For example, when
using the configuration below, requests to http://example.com/abc.html will
be redirected to https://example.com/abc.html.

If the argument is a scalar, the value is considered as the URL to where
the requests should be redirected.

Following properties are recognized if the argument is a mapping.

url URL to redirect to status the three-digit status code to use (e.g. 301)
internal either YES or NO (default); if set to YES, then the server per-
forms an internal redirect and return the content at the redirected URL

Example: Redirect all HTTP to HTTPS permanently (except for the files un-
der RSS)

hosts:
"example.com:80":
paths:
"/":
redirect:
status: 301
url: "https://example.com/"
"/rss":
file.dir: /path/to/rss

REPROXY DIRECTIVES
This document describes the configuration directives of the reproxy han-
dler.

reproxy
A boolean flag (ON or OFF) indicating if the server should recognize the X-
Reproxy-URL header sent from upstream servers.

If H2O recognizes the header, it fetches the contents of the resource spec-
ified by the header, and sends the contents as the response to the client.
If the status code associated with the X-Reproxy-URL header is 307 or 308,
then the method of the original request is used to obtain the specified re-
source. Otherwise, the request method is changed to GET.

For example, an upstream server may send an URL pointing to a large image
using the X-Reproxy-URL header stored on a distributed file system, and let
H2O fetch and return the content to the client, instead of fetching the im-
age by itself. Doing so would reduce the load on the application server.

STATUS DIRECTIVES
The status handler exposes the current states of the HTTP server. This
document describes the configuration directives of the handler.

status
(since v2.0) If the argument is ON, the directive registers the status han-
dler to the current path.

Access to the handler should be restricted, considering the fact that the
status includes the details of in-flight HTTP requests. The example below
uses Basic authentication.

Example: Exposing status with Basic authentication

paths:
/server-status:
mruby.handler: |
require "htpasswd.rb"
Htpasswd.new("/path/to/.htpasswd", "status")
status: ON

The information returned by the /json handler can be filtered out using the
optional show=module1,module2 parameter. There are currently three modules
defined:

requests: displays the requests currently in-flight. durations: displays
durations statistics for requests since server start time in seconds (re-
turns all zeros unless duration-stats is ON). errors: displays counters
for internally generated errors. main: displays general daemon-wide stats.

duration-stats
(since v2.1) Gather timing stats for requests.

If the argument is ON, this directive populates duration statistics in sec-
onds, to be consumed by status handlers. Enabling this feature has a no-
ticeable CPU and memory impact.

Note that the time spent while processing a request in a blocking manner
(such as opening a file or a mruby handler that does invoke a network oper-
ation) will not be reflected to the process_time element of the duration
stats due to the fact that the timer being used for measuring the time
spent is updated only once per loop.

THROTTLE RESPONSE DIRECTIVES
The throttle response handler performs per response traffic throttling,
when an X-Traffic header exists in the response headers.

The value of X-Traffic header should be an integer that represents the
speed you want in bytes per second. This header CAN be set with header.add
so that traffic for static assets can also be easily throttled.

The following are the configuration directives recognized by the handler.

throttle-response
(since v2.1) Enables traffic throttle per HTTP response.

If the argument is ON, the traffic per response is throttled as long as a
legal X-Traffic header exists. If the argument is OFF, traffic throttle
per response is disabled.

Example: Enabling traffic throttle per response with static file configu-
ration

# enable throttle
throttle-response: ON

# an example host configuration that throttle traffic to ~100KB/s
hosts:
default:
paths:
/:
file.dir: /path/to/assets
header.add: "X-Traffic: 100000"

USING BASIC AUTHENTICATION
Starting from version 1.7, H2O comes with a mruby script named htpasswd.rb
that implements Basic Authentication. The script provides a Rack handler
that implements Basic Authentication using password files generated by the
htpasswd command.

Below example uses the mruby script to restrict access to the path. If au-
thentication fails, the mruby handler returns a 401 Unauthorized response.
If authentication succeeds, the handler returns a 399 response, and the re-
quest is delegated internally to the next handler (i.e. file.dir).

Example: Configuring HTTP authentication using htpasswd.rb

paths:
"/":
mruby.handler: |
require "htpasswd.rb"
Htpasswd.new("/path/to/.htpasswd", "realm-name")
file.dir: /path/to/doc_root

In H2O versions prior to 2.0, you should specify
"#{$H2O_ROOT}/share/h2o/mruby/htpasswd.rb" as the argument to require,
since the directory is not registered as part of $LOAD_PATH.

For convenience, the mruby script also forbids access to files or directo-
ries that start with .ht.

USING CGI
Starting from version 1.7, H2O comes with a FastCGI-to-CGI gateway
(fastcgi-cgi), which can be found under share/h2o directory of the instal-
lation path. The gateway can be used for running CGI scripts through the
FastCGI handler.

The example below maps .cgi files to be executed by the gateway. It is
also possible to run CGI scripts under different privileges by specifying
the user attribute of the directive.

Example: Execute .cgi files using FastCGI-to-CGI gateway

file.custom-handler:
extension: .cgi
fastcgi.spawn:
command: "exec $H2O_ROOT/share/h2o/fastcgi-cgi"

The gateway also provides options to for tuning the behavior. A full list
of options can be obtained by running the gateway directly with --help op-
tion.

Example: Output of share/h2o/fastcgi-cgi --help

$ share/h2o/fastcgi-cgi --help
Usage:
share/h2o/fastcgi-cgi [options]

Options:
--listen=sockfn path to the UNIX socket. If specified, the program will
create a UNIX socket at given path replacing the existing
file (should it exist). If not, file descriptor zero (0)
will be used as the UNIX socket for accepting new
connections.
--max-workers=nnn maximum number of CGI processes (default: unlimited)
--pass-authz if set, preserves HTTP_AUTHORIZATION parameter
--verbose verbose mode

USING MRUBY
mruby is a lightweight implementation of the Ruby programming language.
With H2O, users can implement their own request handling logic using mruby,
either to generate responses or to fix-up the request / response.

Rack-based Programming Interface

The interface between the mruby program and the H2O server is based on Rack
interface specification. Below is a simple configuration that returns
hello world.

Example: Hello-world in mruby

paths:
"/":
mruby.handler: |
Proc.new do |env|
[200, {'content-type' => 'text/plain'}, ["Hello world0]]
end

It should be noted that as of H2O version 1.7.0, there are limitations when
compared to ordinary web application server with support for Rack such as
Unicorn:

no libraries provided as part of Rack is available (only the interface is
compatible)

In addition to the Rack interface specification, H2O recognizes status code
399 which can be used to delegate request to the next handler. The feature
can be used to implement access control and response header modifiers.

Access Control

By using the 399 status code, it is possible to implement access control
using mruby. The example below restricts access to requests from 192.168.
private address.

Example: Restricting access to 192.168.

paths:
"/":
mruby.handler: |
lambda do |env|
if /168./.match(env["REMOTE_ADDR"])
return [399, {}, []]
end
[403, {'content-type' => 'text/plain'}, ["access forbidden0]]
end

Support for Basic Authentication is also provided by an mruby script.

Delegating the Request

When enabled using the reproxy directive, it is possible to delegate the
request from the mruby handler to any other handler.

Example: Rewriting URL with delegation

paths:
"/":
mruby.handler: |
lambda do |env|
if /user([^]+)/.match(env["PATH_INFO"])
return [307, {"x-reproxy-url" => "/user.php?user=#{$1}"}, []]
end
return [399, {}, []]
end

Modifying the Response

When the mruby handler returns status code 399, H2O delegates the request
to the next handler while preserving the headers emitted by the handler.
The feature can be used to add extra headers to the response.

For example, the following example sets cache-control header for requests
against .css and .js files.

Example: Setting cache-control header for certain types of files

paths:
"/":
mruby.handler: |
Proc.new do |env|
headers = {}
if /.(css|js).match(env["PATH_INFO"])
headers["cache-control"] = "max-age=86400"
end
[399, headers, []]
end
file.dir: /path/to/doc-root

Or in the example below, the handler triggers HTTP/2 server push with the
use of Link: rel=preload headers, and then requests a FastCGI application
to process the request.

Example: Pushing asset files

paths:
"/":
mruby.handler: |
Proc.new do |env|
push_paths = []
# push css and js when request is to dir root or HTML
if /(|.html).match(env["PATH_INFO"])
push_paths << ["/css/style.css", "style"]
push_paths << ["/js/app.js", "script"]
end
[399, push_paths.empty? ? {} : {"link" => push_paths.map{|p| "<#{p[0]}>; rel=preload; as=#{p[1]}"}.join("0)}, []]
end
fastcgi.connect: ...

Using the HTTP Client

Starting from version 1.7, a HTTP client API is provided. HTTP requests
issued through the API will be handled asynchronously; the client does not
block the event loop of the HTTP server.

Example: Mruby handler returning the response of http://example.com

paths:
"/":
mruby.handler: |
Proc.new do |env|
req = http_request("http://example.com")
status, headers, body = req.join
[status, headers, body]
end

http_request is the method that issues a HTTP request.

The method takes two arguments. First argument is the target URI. Second
argument is an optional hash; method (defaults to GET), header, body at-
tributes are recognized.

The method returns a promise object. When #join method of the promise is
invoked, a three-argument array containing the status code, response head-
ers, and the body is returned. The response body is also a promise. Ap-
plications can choose from three ways when dealing with the body: a) call
#each method to receive the contents, b) call #join to retrieve the body as
a string, c) return the object as the response body of the mruby handler.

The header and the body object passed to http_request should conform to the
requirements laid out by the Rack specification for request header and re-
quest body. The response header and the response body object returned by
the #join method of the promise returned by http_request conforms to the
requirements of the Rack specification.

Since the API provides an asynchronous HTTP client, it is possible to ef-
fectively issue multiple HTTP requests concurrently and merge them into a
single response.

When HTTPS is used, servers are verified using the properties of
proxy.ssl.cafile and proxy.ssl.verify-peer specified at the global level.

Timeouts defined for the proxy handler (proxy.timeout.*) are applied to the
requests that are issued by the http_request method.

Logging Arbitrary Variable

In version 2.3, it is possible from mruby to set and log an arbitrary-named
variable that is associated to a HTTP request. A HTTP response header that
starts with x-fallthru-set- is handled specially by the H2O server. Instead
of sending the header downstream, the server accepts the value as a request
environment variable, taking the suffix of the header name as the name of
the variable.

This example shows how to read request data, parse json and then log data
from mruby.

Example: Logging the content of a POST request via request environment
variable

paths:
"/":
mruby.handler: |
Proc.new do |env|
input = env["rack.input"] ? env["rack.input"].read : '{"default": "true"}'
parsed_json = JSON.parse(input)
parsed_json["time"] = Time.now.to_i
logdata = parsed_json.to_s
[204, {"x-fallthru-set-POSTDATA" => logdata}, []]
end
access-log:
path: /path/to/access-log.json
escape: json
format: '{"POST": %{POSTDATA}e}'

USING DOS DETECTION
Starting from version 2.1, H2O comes with a mruby script named dos_detec-
tor.rb that implements DoS Detection feature. The script provides a Rack
handler that detects HTTP flooding attacks based on the client's IP ad-
dress.

Basic Usage

Below example uses the mruby script to detect DoS attacks. The default de-
tecting strategy is simply counting requests within configured period. If
the count exceeds configured threshold, the handler returns a 403 Forbidden
response. Otherwise, the handler returns a 399 response, and the request
is delegated internally to the next handler.

Example: Configuring DoS Detection

paths:
"/":
mruby.handler: |
require "dos_detector.rb"
DoSDetector.new({
:strategy => DoSDetector::CountingStrategy.new({
:period => 10, # default
:threshold => 100, # default
:ban_period => 300, # default
}),
})
file.dir: /path/to/doc_root

In the example above, the handler countup the requests within 10 seconds
for each IP address, and when the count exceeds 100, it returns a 403 For-
bidden response for the request and marks the client as "Banned" for 300
seconds. While marked as "Banned", the handler returns a 403 Forbidden to
all requests from the same IP address.

Configuring Details

You can pass the following parameters to DoSDetector.new .

:strategy
The algorithm to detect DoS attacks. You can write and pass your own
strategies if needed. The default strategy is DoSDetector.CountingStrategy
which takes the following parameters:

:period
Time window in seconds to count requests. The default value is 10.

:threshold
Threshold count of request. The default value is 100.

:ban_period
Duration in seconds in which "Banned" client continues to be re-
stricted. The default value is 300.

:callback
The callback which is called by the handler with detecting result. You
can define your own callback to return arbitrary response, set response
headers, etc. The default callback returns 403 Forbidden if DoS detected,
otherwise delegate the request to the next handler.

:forwarded

If set true, the handler uses X-HTTP-Forwarded-For header to get
client's IP address if the header exists. The default value is true.

:cache_size

The capacity of the LRU cache which preserves client's IP address and
associated request count. The default value is 128.

Example: Configuring Details

paths:
"/":
mruby.handler: |
require "dos_detector.rb"
DoSDetector.new({
:strategy => DoSDetector::CountingStrategy.new,
:forwarded => false,
:cache_size => 2048,
:callback => proc {|env, detected, ip|
if detected && ! ip.start_with?("192.168.")
[503, {}, ["Service Unavailable"]]
else
[399, {}, []]
end
}
})
file.dir: /path/to/doc_root

Points to Notice

For now, counting requests is "per-thread" and not shared between multi-
ple threads.

ACCESS CONTROL
Starting from version 2.1, H2O comes with a DSL-like mruby library which
makes it easy to write access control list (ACL).

Example

Below example uses this Access Control feature to write various access con-
trol.

Example: Access Control

paths:
"/":
mruby.handler: |
acl {
allow { addr == "127.0.0.1" }
deny { user_agent.match(/curl/i) && ! addr.start_with?("192.168.") }
respond(503, {}, ["Service Unavailable"]) { addr == malicious_ip }
redirect("https://example.com/", 301) { path =~ /moved/ }
use Htpasswd.new("/path/to/.htpasswd", "realm") { path.start_with?("/admin") }
}
file.dir: /path/to/doc_root

In the example, the handler you get by calling acl method will do the fol-
lowing:

if the remote IP address is exactly equal to "127.0.0.1", the request
will be delegated to the next handler (i.e. serve files under
/path/to/doc_root) and all following acl settings are ignored

otherwise, if the user agent string includes "curl" and the remote IP
address doesn't start with "192.168.", this handler immediately returns 403
Forbidden response

otherwise, if the remote IP address is exactly equal to the mali-
cious_ip variable, this handler immediately returns 503 Service Unavailable
response

otherwise, if the request path matches with the pattern /moved/i, this
handler immediately redirects the client to "https://example.com" with 301
status code

otherwise, if the request path starts with /admin, apply Basic Authen-
tication to the request (for details of Basic Authentication, see here).

otherwise, the request will be delegated to the next handler (i.e.
serve files under /path/to/doc_root)

ACL Methods

An ACL handler is built by calling ACL methods, which can be used like di-
rectives. ACL methods can only be used in acl block.

Each ACL method adds a filter to the handler, which checks whether the re-
quest matches the provided condition or not. Every ACL method can be ac-
companied by a condition block, which should return boolean value.

The filter defined by the method that first matched the accompanying condi-
tion gets applied (e.g. response 403 Forbidden, redirect to somewhere). If
a condition block is omitted, all requests matches. If none of the condi-
tions matches the request, the handler returns 399 and the request will be
delegated to the next handler.

allow
Adds a filter which delegates the request to the next handler if the re-
quest matches the provided condition.

allow { ..condition.. }

deny
Adds a filter which returns 403 Forbidden if the request matches the pro-
vided condition.

deny { ..condition.. }

redirect
Adds a filter which redirects the client if the request matches the pro-
vided condition.

redirect(location, status) { ..condition.. }

Parameters:
location: Location to which the client will be redirected. Required.
status: Status code of the response. Default value: 302

respond
Adds a filter which returns arbitrary response if the request matches the
provided condition.

respond(status, header, body) { ..condition.. }

Parameters:
status: Status code of the response. Required.
header: Header key-value pairs of the response. Default value: {}
body: Body array of the response. Default value: []

use
Adds a filter which applies the provided handler (callable object) if the
request matches the provided condition.

use(proc) { ..condition.. }

Parameters:
proc: Callable object that should be applied

Matching Methods

In a condition block, you can use helpful methods which return particular
properties of the request as string values. Matching methods can only be
used in a condition block of the ACL methods.

addr
Returns the remote IP address of the request.

addr(forwarded)

Parameters:
forwarded: If true, returns the value of X-Forwarded-For header if
it exists. Default value: true

path
Returns the requested path string of the request.

path()

method
Returns the HTTP method of the request.

method()

header
Returns the header value of the request associated with the provided name.

header(name)

Parameters:
name: Case-insensitive header name. Required.

user_agent
Shortcut for header("user-agent").

user_agent()

Caution

Several restrictions are introduced to avoid misconfiguration when using
acl method.

acl method can be called only once in each handler configuration If acl
method is used, the handler returned by the configuration directive must be
the one returned by the acl method

If a configuration violates these restrictions, the server will detect it
and refuse to launch with error message.

For example, both of the following examples violate the restrictions above,
so the server will refuse to start up.

Example: Misconfiguration Example 1

paths:
"/":
mruby.handler: |
acl { # this block will be ignored!
allow { addr == "127.0.0.1" }
}
acl {
deny
}
file.dir: /path/to/doc_root

Example: Misconfiguration Example 2

paths:
"/":
mruby.handler: |
acl { # this block will be ignored!
allow { addr == "127.0.0.1" }
deny
}
proc {|env| [399, {}, []}
file.dir: /path/to/doc_root

You can correct these like the following:

Example: Valid Configuration Example

paths:
"/":
mruby.handler: |
acl {
allow { addr == "127.0.0.1" }
deny
}
file.dir: /path/to/doc_root

How-To

Matching IP Address Blocks

You can match an IP address against predefined list of address blocks using
a script named trie_addr.rb.

Below is an example.

Example: Address Block Matching Example

paths:
"/":
mruby.handler: |
require "trie_addr.rb"
trie = TrieAddr.new.add(["192.168.0.0/16", "172.16.0.0/12"])
acl {
allow { trie.match?(addr) }
deny
}
file.dir: /path/to/doc_root

This library currently supports only IPv4 addresses. TrieAddr#match? re-
turns false when it receives an invalid IPv4 address (including an IPv6 ad-
dress) as an argument..

USING H2OLOG FOR TRACING
h2olog is an experimental BPF (kernel doc) backed tracing tool for the H2O
server. It can be used for tracing quicly and h2o USDT probes.

Since h2olog is an experimental program, its command-line interface might
change without notice.

Installing from Source

See requirements for build prerequisites. If dependencies are satisfied,
h2olog is built automatically. It is possible to manually turn on / off the
build of h2olog by using the -DWITH_H2OLOG option. This option takes either
ON> or OFF as the argument. If you have BCC installed to a non-standard
path, use pkg-config for cmake.

$ PKG_CONFIG_PATH=/path/to/bcc/lib/pkgconfig cmake [options]

Requirements

For building h2olog

C++11 compiler CMake for generating the build files pkg-config for detect-
ing dependencies Python 3 for the code generator BCC (BPF compiler collec-
tion, a.k.a. bpfcc; >= 0.11.0) installed on your system

For Ubuntu 20.04 or later, you can install dependencies with:

$ sudo apt install clang cmake python3 libbpfcc-dev linux-headers-$(uname -r)

For running h2olog

Root privilege to execute h2olog Linux kernel (>= 4.10)

Quickstart h2olog -H -p $H2O_PID shows varnishlog-like tracing.

$ sudo h2olog -H -p $(pgrep -o h2o)

11 0 RxProtocol HTTP/3.0
11 0 RxHeader :authority torumk.com
11 0 RxHeader :method GET
11 0 RxHeader :path /
11 0 RxHeader :scheme https
11 0 TxStatus 200
11 0 TxHeader content-length 123
11 0 TxHeader content-type text/html

Tracing USDT events Server-side QUIC events can be traced using the quic
subcommand. Events are rendered in JSON Lines format.

$ sudo h2olog -p $(pgrep -o h2o)

Hereas an example trace.

{"time":1584380825832,"type":"accept","conn":1,"dcid":"f8aa2066e9c3b3cf"}
{"time":1584380825835,"type":"crypto-decrypt","conn":1,"pn":0,"len":1236}
{"time":1584380825832,"type":"quictrace-recv","conn":1,"pn":0}
{"time":1584380825836,"type":"crypto-handshake","conn":1,"ret":0}

H2O.CONF(5)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=h2o.conf&sektion=5&manpath=FreeBSD+Ports+15.1.quarterly>

home | help

Header And Logo

Peripheral Links

Site Navigation

Header And Logo

Peripheral Links

Search

Site Navigation