Syntax and Structure - Configure - H2O - the optimized HTTP server

# H2O

the optimized HTTP/1.x, HTTP/2, HTTP/3 server

×
Powered by Oktavia

## 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=86400`1 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`.

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:
            <<: !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.

Example. h2o.conf

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

### Notes:

1. 1 day is equivalent to 86400 seconds