From be1c7e50e1e8809ea56f2c9d472eccd8ffd73a97 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Fri, 19 Apr 2024 04:57:58 +0200 Subject: Adding upstream version 1.44.3. Signed-off-by: Daniel Baumann --- .../srcdoc/configure/syntax_and_structure.mt | 216 +++++++++++++++++++++ 1 file changed, 216 insertions(+) create mode 100644 web/server/h2o/libh2o/srcdoc/configure/syntax_and_structure.mt (limited to 'web/server/h2o/libh2o/srcdoc/configure/syntax_and_structure.mt') diff --git a/web/server/h2o/libh2o/srcdoc/configure/syntax_and_structure.mt b/web/server/h2o/libh2o/srcdoc/configure/syntax_and_structure.mt new file mode 100644 index 00000000..f8f8cd4f --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/configure/syntax_and_structure.mt @@ -0,0 +1,216 @@ +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Configure", "Syntax and Structure")->(sub { + +

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. +

+ +{code}->(<< 'EOT') +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/" +EOT +?> + +

+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{note}->("1 day is equivalent to 86400 seconds") ?> 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. +

+ +{code}->(<< 'EOT') +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 +EOT +?> + +

+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. +

+ +{code}->(<< 'EOT') +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 +EOT +?> + +

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. + +{code}->(<< 'EOT') +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 +EOT +?> + +

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. +

+ +{code}->(<< 'EOT') +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: + ... +EOT +?> + +

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', << 'EOT') +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 +EOT +?> + +{example}->('h2o.conf', << 'EOT') +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: + ... +EOT +?> + +? }) -- cgit v1.2.3