H2O

the optimized HTTP/1.x, HTTP/2 server
Powered by Oktavia

Configure > Syntax and Structure

Syntax

H2O uses YAML 1.1 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 directive 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.

Notes:

  1. 1 day is equivalent to 86400 seconds