Configure > 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 understand that there are four configuration levels: global, host, path, extension.
Global-level configurations affect the entire server. Host-level configurations affect the configuration for the specific hostname (i.e. corresponds 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 mapping), 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=864001 header would be sent.
The second host accepts connections on port 80 (via the plain-text HTTP protocol), and redirects 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://example.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 exist, 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.
Therefore, it is possible to use an alias to reduce the redundancy of the configuration file.
For example, the following configuration reuses the first paths element (that is given an anchor named default_paths) in the following 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 YAML™ Version 1.1.
Users can use the feature to merge an existing mapping against another.
The following example reuses the TLS configuration of example.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 extracts the TLS configuration into default_ssl.conf and include it multiple times in h2o.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
hosts:
"example.com":
listen:
port: 443
ssl: !file default_ssl.conf
paths:
...
"example.org":
listen:
port: 443
ssl:
<<: !file default_ssl.conf
certificate-file: /path/to/example.org.crt
key-file: /path/to/example.org.crt
paths:
...
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.
hosts:
"example.com":
listen:
port: !env H2O_PORT
paths:
...
Notes:
- 1 day is equivalent to 86400 seconds