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 --- .../h2o/libh2o/srcdoc/configure/access_control.mt | 273 ++++++++ .../srcdoc/configure/access_log_directives.mt | 134 ++++ .../h2o/libh2o/srcdoc/configure/base_directives.mt | 690 +++++++++++++++++++++ .../h2o/libh2o/srcdoc/configure/basic_auth.mt | 31 + web/server/h2o/libh2o/srcdoc/configure/cgi.mt | 40 ++ .../h2o/libh2o/srcdoc/configure/command_options.mt | 36 ++ .../libh2o/srcdoc/configure/compress_directives.mt | 82 +++ .../h2o/libh2o/srcdoc/configure/dos_detection.mt | 101 +++ .../libh2o/srcdoc/configure/errordoc_directives.mt | 52 ++ .../libh2o/srcdoc/configure/expires_directives.mt | 32 + .../libh2o/srcdoc/configure/fastcgi_directives.mt | 114 ++++ .../h2o/libh2o/srcdoc/configure/file_directives.mt | 244 ++++++++ .../libh2o/srcdoc/configure/headers_directives.mt | 84 +++ .../libh2o/srcdoc/configure/http1_directives.mt | 24 + .../libh2o/srcdoc/configure/http2_directives.mt | 356 +++++++++++ web/server/h2o/libh2o/srcdoc/configure/mruby.mt | 199 ++++++ .../libh2o/srcdoc/configure/mruby_directives.mt | 58 ++ .../libh2o/srcdoc/configure/proxy_directives.mt | 236 +++++++ .../h2o/libh2o/srcdoc/configure/quick_start.mt | 66 ++ .../libh2o/srcdoc/configure/redirect_directives.mt | 47 ++ .../libh2o/srcdoc/configure/reproxy_directives.mt | 29 + .../libh2o/srcdoc/configure/status_directives.mt | 63 ++ .../srcdoc/configure/syntax_and_structure.mt | 216 +++++++ .../configure/throttle_response_directives.mt | 44 ++ 24 files changed, 3251 insertions(+) create mode 100644 web/server/h2o/libh2o/srcdoc/configure/access_control.mt create mode 100644 web/server/h2o/libh2o/srcdoc/configure/access_log_directives.mt create mode 100644 web/server/h2o/libh2o/srcdoc/configure/base_directives.mt create mode 100644 web/server/h2o/libh2o/srcdoc/configure/basic_auth.mt create mode 100644 web/server/h2o/libh2o/srcdoc/configure/cgi.mt create mode 100644 web/server/h2o/libh2o/srcdoc/configure/command_options.mt create mode 100644 web/server/h2o/libh2o/srcdoc/configure/compress_directives.mt create mode 100644 web/server/h2o/libh2o/srcdoc/configure/dos_detection.mt create mode 100644 web/server/h2o/libh2o/srcdoc/configure/errordoc_directives.mt create mode 100644 web/server/h2o/libh2o/srcdoc/configure/expires_directives.mt create mode 100644 web/server/h2o/libh2o/srcdoc/configure/fastcgi_directives.mt create mode 100644 web/server/h2o/libh2o/srcdoc/configure/file_directives.mt create mode 100644 web/server/h2o/libh2o/srcdoc/configure/headers_directives.mt create mode 100644 web/server/h2o/libh2o/srcdoc/configure/http1_directives.mt create mode 100644 web/server/h2o/libh2o/srcdoc/configure/http2_directives.mt create mode 100644 web/server/h2o/libh2o/srcdoc/configure/mruby.mt create mode 100644 web/server/h2o/libh2o/srcdoc/configure/mruby_directives.mt create mode 100644 web/server/h2o/libh2o/srcdoc/configure/proxy_directives.mt create mode 100644 web/server/h2o/libh2o/srcdoc/configure/quick_start.mt create mode 100644 web/server/h2o/libh2o/srcdoc/configure/redirect_directives.mt create mode 100644 web/server/h2o/libh2o/srcdoc/configure/reproxy_directives.mt create mode 100644 web/server/h2o/libh2o/srcdoc/configure/status_directives.mt create mode 100644 web/server/h2o/libh2o/srcdoc/configure/syntax_and_structure.mt create mode 100644 web/server/h2o/libh2o/srcdoc/configure/throttle_response_directives.mt (limited to 'web/server/h2o/libh2o/srcdoc/configure') diff --git a/web/server/h2o/libh2o/srcdoc/configure/access_control.mt b/web/server/h2o/libh2o/srcdoc/configure/access_control.mt new file mode 100644 index 00000000..4a613ac6 --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/configure/access_control.mt @@ -0,0 +1,273 @@ +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Configure", "Access Control")->(sub { + +

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

+ +{example}->('Access Control', <<'EOT'); +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 +EOT +?> + +

+In the example, the handler you get by calling acl method will do the following: +

+ +

ACL Methods

+ +

+An ACL handler is built by calling ACL methods, which can be used like directives. +ACL methods can only be used in acl block. +

+ +

+Each ACL method adds a filter to the handler, which checks whether the request matches the provided condition or not. +Every ACL method can be accompanied by a condition block, which should return boolean value. +

+ +

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

+ +{mruby_method}->( + name => "allow", + desc => q{ Adds a filter which delegates the request to the next handler if the request matches the provided condition. }, +)->(sub { +?> +
allow { ..condition.. }
+? }) + +{mruby_method}->( + name => "deny", + desc => q{ Adds a filter which returns 403 Forbidden if the request matches the provided condition. }, +)->(sub { +?> +
deny { ..condition.. }
+? }) + +{mruby_method}->( + name => "redirect", + params => [ + { label => 'location', desc => 'Location to which the client will be redirected. Required.' }, + { label => 'status', desc => 'Status code of the response. Default value: 302' }, + ], + desc => q{ Adds a filter which redirects the client if the request matches the provided condition. }, +)->(sub { +?> +
redirect(location, status) { ..condition.. }
+? }) + +{mruby_method}->( + name => "respond", + params => [ + { label => 'status', desc => 'Status code of the response. Required.' }, + { label => 'header', desc => 'Header key-value pairs of the response. Default value: {}' }, + { label => 'body', desc => 'Body array of the response. Default value: []' }, + ], + desc => q{ Adds a filter which returns arbitrary response if the request matches the provided condition. }, +)->(sub { +?> +
respond(status, header, body) { ..condition.. }
+? }) + +{mruby_method}->( + name => "use", + params => [ + { label => 'proc', desc => 'Callable object that should be applied' }, + ], + desc => q{ Adds a filter which applies the provided handler (callable object) if the request matches the provided condition. }, +)->(sub { +?> +
use(proc) { ..condition.. }
+? }) + +

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

+ +{mruby_method}->( + name => "addr", + params => [ + { label => 'forwarded', desc => 'If true, returns the value of X-Forwarded-For header if it exists. Default value: true' }, + ], + desc => q{ Returns the remote IP address of the request. }, +)->(sub { +?> +
addr(forwarded)
+? }) + +{mruby_method}->( + name => "path", + desc => q{ Returns the requested path string of the request. }, +)->(sub { +?> +
path()
+? }) + +{mruby_method}->( + name => "method", + desc => q{ Returns the HTTP method of the request. }, +)->(sub { +?> +
method()
+? }) + +{mruby_method}->( + name => "header", + params => [ + { label => 'name', desc => 'Case-insensitive header name. Required.' }, + ], + desc => q{ Returns the header value of the request associated with the provided name. }, +)->(sub { +?> +
header(name)
+? }) + +{mruby_method}->( + name => "user_agent", + desc => q{ Shortcut for header("user-agent"). }, +)->(sub { +?> +
user_agent()
+? }) + +

Caution

+ +

+Several restrictions are introduced to avoid misconfiguration when using 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', <<'EOT'); +paths: + "/": + mruby.handler: | + acl { # this block will be ignored! + allow { addr == "127.0.0.1" } + } + acl { + deny + } + file.dir: /path/to/doc_root +EOT +?> + +{example}->('Misconfiguration Example 2', <<'EOT'); +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 +EOT +?> + +

+You can correct these like the following: +

+ +{example}->('Valid Configuration Example', <<'EOT'); +paths: + "/": + mruby.handler: | + acl { + allow { addr == "127.0.0.1" } + deny + } + file.dir: /path/to/doc_root +EOT +?> + +

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', <<'EOT'); +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 +EOT +?> + +

+This library currently supports only IPv4 addresses. TrieAddr#match? returns false when it receives an invalid IPv4 address (including an IPv6 address) as an argument.. +

+ +? }) diff --git a/web/server/h2o/libh2o/srcdoc/configure/access_log_directives.mt b/web/server/h2o/libh2o/srcdoc/configure/access_log_directives.mt new file mode 100644 index 00000000..52a585ba --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/configure/access_log_directives.mt @@ -0,0 +1,134 @@ +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Configure", "Access Log Directives")->(sub { + +

+This document describes the configuration directives of the access_log handler. +

+ +{directive}->( + name => "access-log", + levels => [ qw(global host path extension) ], + see_also => render_mt(<<'EOT'), +error-log +error-log.emit-request-errors +EOT + desc => q{The directive sets the path and optionally the format of the access log.}, +)->(sub { +?> +

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

+{example}->('Emit access log to file', <<'EOT') +access-log: /path/to/access-log-file +EOT +?> +{example}->('Emit access log through pipe', <<'EOT') +access-log: "| rotatelogs /path/to/access-log-file.%Y%m%d 86400" +EOT +?> + +

+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 \xNN, where N is a hexadecimal number in lower case. +If json is specified, unsafe octets are emitted in the form of \u00NN. +apache is the default escape method. +

+ +{example}->('Emit access log to file using Common Log Format', <<'EOT') +access-log: + path: /path/to/access-log-file + format: "%h %l %u %t \"%r\" %s %b" + escape: apache +EOT +?> + +

+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) +
%<sstatus 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) +
%<{HEADERNAME}ovalue of the response header received from upstream (or initially generated) +
%{NAME}xvarious extensions. NAME must be one listed in the following 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 connection (i.e. since connection gets accept(2)-ed until first octet of the request is received) +
request-header-timetime spent receiving request headers +
request-body-timetime spent receiving request body +
request-total-timesum of request-header-time and request-body-time +
process-timetime spent after receiving request, before starting to send response +
response-timetime spent sending response +
durationsum of request-total-time, process-time, response-time +
+ + +
Connection (since v2.0)
NameDescription +
connection-id64-bit internal ID assigned 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{note}->(q{A single SSL connection may transfer more than one HTTP request.}) ?> +
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 +
+ + +
HTTP/2 (since v2.0)
NameDescription +
http2.stream-idstream ID +
http2.priority.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.received.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). +

+? }) + +? }) diff --git a/web/server/h2o/libh2o/srcdoc/configure/base_directives.mt b/web/server/h2o/libh2o/srcdoc/configure/base_directives.mt new file mode 100644 index 00000000..1f6ffe3e --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/configure/base_directives.mt @@ -0,0 +1,690 @@ +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Configure", "Base Directives")->(sub { + +

+This document describes the configuration directives common to all the protocols and handlers. +

+ +{directive}->( + name => "hosts", + levels => [ qw(global) ], + desc => q{Maps host:port to the mappings of per-host configs.}, +)->(sub { +?> +

+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 default ports (i.e. port 80 for HTTP, port 443 for HTTPS) with given hostname. +Otherwise, the entry will match the requests targetting the specified port. +

+

+Since version 1.7, a wildcard character * can be used as the first component 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. +Note that an exact match is preferred over host definitions using wildcard characters. +

+ + +{example}->('A host redirecting all HTTP requests to HTTPS', <<'EOT'); +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 +EOT +?> +? }) + +{directive}->( + name => "paths", + levels => [ qw(host) ], + desc => q{Mapping of paths and their configurations.}, +)->(sub { +?> +

+

+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', <<'EOT') +hosts: + "www.example.com": + listen: + port: 80 + paths: + "/": + file.dir: /path/to/doc-root + "/assets": + file.dir: /path/to/assets +EOT +?> +

+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 continues to perform the redirection; in case of the example above, access to /assets is redirected to /assets/. +

+? }) + +{directive}->( + name => "listen", + levels => [ qw(global host) ], + desc => q{Specifies the port at which the server should listen to.}, +)->(sub { +?> +

+

+In addition to specifying the port number, it is also possible to designate the bind address or the SSL configuration. +

+{example}->('Various ways of using the Listen Directive', <<'EOT') +# 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 +EOT +?> +

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 context. +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', <<'EOT') +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 +EOT +?> +

SSL Attribute

+

+The ssl attribute must be defined as a mapping, and recognizes the following attributes. +

+
+
certificate-file:
+
path of the SSL certificate file (mandatory)
+
key-file:
+
path of the SSL private key file (mandatory)
+
minimum-version:
+
+minimum protocol version, should be one of: SSLv2, SSLv3, TLSv1, TLSv1.1, TLSv1.2. +Default is TLSv1 +
+
min-verison:
+
+synonym of minimum-version (introduced in version 2.2) +
+
maximum-version:
+
+maximum protocol version. +Introduced in version 2.2. +Default is the maximum protocol version supported by the server. +
+
max-version:
+
+synonym of maximum-version. +
+
cipher-suite:
+
list of cipher suites to be passed to OpenSSL via SSL_CTX_set_cipher_list (optional)
+
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 agreement. +(optional) +
+
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). +
+
ocsp-max-failures:
+
+number of consecutive OCSP query failures before stopping to send OCSP stapling data to the client. +Default is 3. +
+
neverbleed:
+
+unless set to OFF, H2O isolates RSA private key operations to an isolated process by using Neverbleed. +Default is ON. +
+

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

+

The Proxy-Protocol Attribute

+

+The proxy-protocol attribute (i.e. the value of the attribute must be either 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 address 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 attribute has been used. +

+

+Default is OFF. +

+

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. +
+
permission
+
+an octal number specifying the permission of the socket file. +Many operating 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', <<'EOT') +listen: + type: unix + port: /tmp/h2o.sock + owner: www-data + permission: 600 +EOT +?> +? }) + +{directive}->( + name => "error-log", + levels => [ qw(global) ], + see_also => render_mt(<<'EOT'), +error-log.emit-request-errors +EOT + desc => q{Path of the file to which error logs should be appended.}, +)->(sub { +?> +

+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', <<'EOT') +error-log: /path/to/error-log-file +EOT +?> +{example}->('Log errors through pipe', <<'EOT') +error-log: "| rotatelogs /path/to/error-log-file.%Y%m%d 86400" +EOT +?> +? }) + +{directive}->( + name => "error-log.emit-request-errors", + levels => [ qw(global host path extension) ], + since => "2.1", + see_also => render_mt(<<'EOT'), +access-log +error-log +EOT + default => "error-log.emit-request-errors: ON", + desc => q{Sets whether if request-level errors should be emitted to the error log.}, +)->(sub { +?> +By setting the value to OFF and by using the %{error}x specifier of the access-log directive, it is possible to log request-level errors only to the access log. +? }) + +{directive}->( + name => "handshake-timeout", + levels => [ qw(global) ], + default => "handshake-timeout: 10", + desc => q{Maximum time (in seconds) that can be spent by a connection before it becomes ready to accept an HTTP request.}, +)->(sub { +?> +Times spent for receiving the PROXY protocol and TLS handshake are counted. +? }) + +{directive}->( + name => "limit-request-body", + levels => [ qw(global) ], + desc => q{Maximum size of request body in bytes (e.g. content of POST).}, +)->(sub { +?> +

+Default is 1073741824 (1GB). +

+? }) + +{directive}->( + name => "max-connections", + levels => [ qw(global) ], + default => 'max-connections: 1024', + desc => q{Number of connections to handle at once at maximum.}, +)->(sub {}); + +$ctx->{directive}->( + name => "max-delegations", + levels => [ qw(global) ], + default => 'max-delegations: 5', + desc => q{Limits the number of delegations (i.e. internal redirects using the X-Reproxy-URL header).}, +)->(sub {}); + +$ctx->{directive}->( + name => "num-name-resolution-threads", + levels => [ qw(global) ], + default => 'num-name-resolution-threads: 32', + desc => q{Maximum number of threads to run for name resolution.}, +)->(sub {}); +?> + +{directive}->( + name => "num-ocsp-updaters", + levels => [ qw(global) ], + since => "2.0", + default => 'num-ocsp-updaters: 10', + desc => q{Maximum number of OCSP updaters.}, +)->(sub { +?> +

+OSCP Stapling is an optimization that speeds up the time spent for establishing a TLS connection. +In order to staple OCSP information, a HTTP server is required to periodically contact the certificate authority. +This directive caps the number of the processes spawn for collecting the information. +

+

+The use and the update interval of OCSP can be configured using the SSL attributes of the listen configuration directive. +

+? }); + +{directive}->( + name => "num-threads", + levels => [ qw(global) ], + desc => q{Number of worker threads.}, +)->(sub { +?> +

+Default is the number of the processors connected to the system as obtained by getconf NPROCESSORS_ONLN. +

+? }) + +{directive}->( + name => "pid-file", + levels => [ qw(global) ], + desc => q{Name of the file to which the process id of the server should be written.}, +)->(sub { +?> +

+Default is none. +

+? }) + +{directive}->( + name => "tcp-fastopen", + levels => [ qw(global) ], + desc => q{Size of the queue used for TCP Fast Open.}, +)->(sub { +?> +

+TCP Fast Open is an extension to the TCP/IP protocol that reduces the time spent for establishing a connection. +On Linux that support the feature, the default value is 4,096. +On other platforms the default value is 0 (disabled). +

+? }) + +{directive}->( + name => "send-server-name", + levels => [ qw(global) ], + since => '2.0', + desc => q{A boolean flag (ON or OFF) indicating whether if the server response header should be sent.}, + default => q{send-server-name: ON}, + see_also => render_mt(<<'EOT'), +server-name +EOT +)->(sub { +?> +? }) + +{directive}->( + name => "server-name", + levels => [ qw(global) ], + since => '2.0', + desc => q{Lets the user override the value of the server response header.}, + see_also => render_mt(<<'EOT'), +send-server-name +EOT +)->(sub { +?> +The default value is h2o/VERSION-NUMBER. +? }) + +{directive}->( + name => "setenv", + levels => [ qw(global host path extension) ], + since => '2.0', + desc => 'Sets one or more environment variables.', + see_also => render_mt(<<'EOT'), +unsetenv +EOT +)->(sub { +?> +

+Environment variables are a set of key-value pairs containing arbitrary strings, that can be read from applications invoked by the standalone server (e.g. fastcgi handler, mruby handler) and the access logger. +

+

+The directive is applied from outer-level to inner-level. +At each level, the directive is applied after the unsetenv directive at the corresponding level is applied. +

+

+Environment variables are retained through internal redirections. +

+{example}->('Setting an environment variable named FOO', <<'EOT') +setenv: + FOO: "value_of_FOO" +EOT +?> +? }) + +{directive}->( + name => "unsetenv", + levels => [ qw(global host path extension) ], + since => '2.0', + desc => 'Unsets one or more environment variables.', + see_also => render_mt(<<'EOT'), +setenv +EOT +)->(sub { +?> +

+The directive can be used to have an exception for the paths that have an environment variable set, or can be used to reset variables after an internal redirection. +

+{example}->('Setting environment variable for example.com excluding /specific-path', <<'EOT') +hosts: + example.com: + setenv: + FOO: "value_of_FOO" + paths: + /specific-path: + unsetenv: + - FOO + ... +EOT +?> +? }) + +{directive}->( + name => "ssl-session-resumption", + levels => [ qw(global) ], + desc => q{Configures cache-based and ticket-based session resumption.}, +)->(sub { +?> +

+To reduce the latency introduced by the TLS (SSL) handshake, two methods to resume a previous encrypted session are defined by the Internet Engineering Task Force. +H2O supports both of the methods: cache-based session resumption (defined in RFC 5246) and ticket-based session resumption (defined in RFC 5077). +

+{example}->('Various session-resumption configurations', <<'EOT'); +# use both methods (storing data on internal memory) +ssl-session-resumption: + mode: all + +# use both methods (storing data on memcached running at 192.168.0.4:11211) +ssl-session-resumption: + mode: all + cache-store: memcached + ticket-store: memcached + cache-memcached-num-threads: 8 + memcached: + host: 192.168.0.4 + port: 11211 + +# use ticket-based resumption only (with secrets used for encrypting the tickets stored in a file) +ssl-session-resumption: + mode: ticket + ticket-store: file + ticket-file: /path/to/ticket-secrets.yaml +EOT +?> +

Defining the Methods Used

+

+The mode attribute defines which methods should be used for resuming the TLS sessions. +The value can be either of: off, cache, ticket, all. +Default is all. +

+

+If set to off, session resumption will be disabled, and all TLS connections will be established via full handshakes. +If set to all, both session-based and ticket-based resumptions will be used, with the preference given to the ticket-based resumption for clients supporting both the methods. +

+

+For each method, additional attributes can be used to customize their behaviors. +Attributes that modify the behavior of the disabled method are ignored. +

+

Attributes for Cache-based Resumption

+

+Following attributes are recognized if the cache-based session resumption is enabled. +Note that memcached attribute must be defined as well in case the memcached cache-store is used. +

+
+
cache-store:
+
+

+defines where the cache should be stored, must be one of: internal, memcached. +Default is internal. +

+

+Please note that if you compiled h2o with OpenSSL 1.1.0 ~ 1.1.0f, session resumption with external cache store would fail due to bug of OpenSSL. +

+
+
cache-memcached-num-threads:
+
defines the maximum number of threads used for communicating with the memcached server. +Default is 1. +
+
cache-memcached-prefix:
+
+for the memcached store specifies the key prefix used to store the secrets on memcached. +Default is h2o:ssl-session-cache:. +
+
+

Attributes for Ticket-based Resumption

+

+Ticket-based session resumption uses master secret(s) to encrypt the keys used for encrypting the data transmitted over TLS connections. +To achieve forward-secrecy (i.e. protect past communications from being decrypted in case a master secret gets obtained by a third party), it is essential to periodically change the secret and remove the old ones. +

+

+Among the three types of stores supported for ticket-based session resumption, the internal store and memcached store implement automatic roll-over of the secrets. +A new master secret is created every 1/4 of the session lifetime (defined by the lifetime attribute), and they expire (and gets removed) after 5/4 of the session lifetime elapse. +

+

+For the file store, it is the responsibility of the web-site administrator to periodically update the secrets. H2O monitors the file and reloads the secrets when the file is altered. +

+

+Following attributes are recognized if the ticket-based resumption is enabled. +

+
+
ticket-store:
+
defines where the secrets for ticket-based resumption should be / is stored, must be one of: internal, file, memcached. +Default is internal. +
ticket-cipher:
+
+for stores that implement automatic roll-over, specifies the cipher used for encrypting the tickets. +The value must be one recognizable by EVP_get_cipherbyname. +Default is aes-256-cbc. +
ticket-hash:
+
+for stores that implement automatic roll-over, specifies the cipher used for digitally-signing the tickets. +The value must be one recognizable by EVP_get_digestbyname. +Default is sha-256. +
+
ticket-file:
+
for the file store specifies the file in which the secrets are stored
+
ticket-memcached-key:
+
+for the memcached store specifies the key used to store the secrets on memcached. +Default is h2o:ssl-session-ticket. +
+
+

Other Attributes

+

+Following attributes are common to cache-based and ticket-based session resumption. +

+
+
lifetime:
+
+defines the lifetime of a TLS session; when it expires the session cache entry is purged, and establishing a new connection will require a full TLS handshake. +Default value is 3600 (in seconds). +
+
memcached:
+
+specifies the location of memcached used by the memcached stores. +The value must be a mapping with host attribute specifying the address of the memcached server, and optionally a port attribute specifying the port number (default is 11211). +By default, the memcached client uses the BINARY protocol. +Users can opt-in to using the legacy ASCII protocol by adding a protocol attribute set to ASCII. +
+? }) + +{directive}->( + name => "temp-buffer-path", + levels => [ qw(global) ], + desc => q{Directory in which temporary buffer files are created.}, + default => q{temp-buffer-path: "/tmp"}, + since => "2.0", + see_also => render_mt(<<'EOT'), +user +EOT +)->(sub { +?> +

+H2O uses an internal structure called h2o_buffer_t for buffering various kinds of data (e.g. POST content, response from upstream HTTP or FastCGI server). +When amount of the data allocated in the buffer exceeds 32MB, it starts allocating storage from the directory pointed to by the directive. +

+

+By using the directive, users can set the directory to one within a memory-backed file system (e.g. tmpfs) for speed, or specify a disk-based file system to avoid memory pressure. +

+

+Note that the directory must be writable by the running user of the server. +

+? }) + +{directive}->( + name => "user", + levels => [ qw(global) ], + desc => q{Username under which the server should handle incoming requests.}, +)->(sub { +?> +

+If the directive is omitted and if the server is started under root privileges, the server will attempt to setuid to nobody. +

+? }) + +{directive}->( + name => "crash-handler", + levels => [ qw(global) ], + desc => q{Script to invoke if h2o receives a fatal signal.}, + default => q{crash-handler: "${H2O_ROOT}/share/h2o/annotate-backtrace-symbols"}, + since => "2.1", +)->(sub { +?> +

Note: this feature is only available when linking to the GNU libc.

+ +

The script is invoked if one of the SIGABRT, +SIGBUS, SIGFPE, SIGILL or +SIGSEGV signals is received by h2o.

+ +

h2o writes the backtrace as provided by +backtrace() and backtrace_symbols_fd to the +standard input of the program.

+ +

If the path is not absolute, it is prefixed with ${H2O_ROOT}/.

+? }) + +{directive}->( + name => "crash-handler.wait-pipe-close", + levels => [ qw(global) ], + desc => q{Whether h2o should wait for the crash handler pipe to close before exiting.}, + default => q{crash-handler.wait-pipe-close: OFF}, + since => "2.1", +)->(sub { +?> +

When this setting is ON, h2o will wait +for the pipe to the crash handler to be closed before exiting. +This can be useful if you use a custom handler that inspects the dying +process.

+? }) + +? }) diff --git a/web/server/h2o/libh2o/srcdoc/configure/basic_auth.mt b/web/server/h2o/libh2o/srcdoc/configure/basic_auth.mt new file mode 100644 index 00000000..918b4053 --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/configure/basic_auth.mt @@ -0,0 +1,31 @@ +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Configure", "Using Basic Authentication")->(sub { + +

+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 authentication fails, the mruby handler returns a 401 Unauthorized response. +If authentication succeeds, the handler returns a 399 response, and the request is delegated internally to the next handler (i.e. file.dir). +

+ +{example}->('Configuring HTTP authentication using htpasswd.rb', <<'EOT'); +paths: + "/": + mruby.handler: | + require "htpasswd.rb" + Htpasswd.new("/path/to/.htpasswd", "realm-name") + file.dir: /path/to/doc_root +EOT +?> + +

+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 directories that start with .ht. + +? }) diff --git a/web/server/h2o/libh2o/srcdoc/configure/cgi.mt b/web/server/h2o/libh2o/srcdoc/configure/cgi.mt new file mode 100644 index 00000000..09da7e93 --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/configure/cgi.mt @@ -0,0 +1,40 @@ +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Configure", "Using CGI")->(sub { + +

+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 installation 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', <<'EOT'); +file.custom-handler: + extension: .cgi + fastcgi.spawn: + command: "exec $H2O_ROOT/share/h2o/fastcgi-cgi" +EOT +?> + +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 option. + +{example}->('Output of share/h2o/fastcgi-cgi --help', <<'EOT'); +$ 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 +EOT +?> + +? }) diff --git a/web/server/h2o/libh2o/srcdoc/configure/command_options.mt b/web/server/h2o/libh2o/srcdoc/configure/command_options.mt new file mode 100644 index 00000000..b9ea030e --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/configure/command_options.mt @@ -0,0 +1,36 @@ +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Configure", "Command Options")->(sub { + +

+Full list of command options can be viewed by running h2o --help. +Following is the output of --help as of version 1.2.0. +

+ +{code}->(<< 'EOT') +Options: + -c, --conf FILE configuration file (default: h2o.conf) + -m, --mode specifies one of the following mode + - worker: invoked process handles incoming connections + (default) + - daemon: spawns a master process and exits. `error-log` + must be configured when using this mode, as all + the errors are logged to the file instead of + being emitted to STDERR + - master: invoked process becomes a master process (using + the `share/h2o/start_server` command) and spawns + a worker process for handling incoming + connections. Users may send SIGHUP to the master + process to reconfigure or upgrade the server. + - test: tests the configuration and exits + -t, --test synonym of `--mode=test` + -v, --version prints the version number + -h, --help print this help +EOT +?> + +

+The default path of the configuration file may differ depending on the distribution. +Please run h2o --help to find out the location. +

+ +? }) diff --git a/web/server/h2o/libh2o/srcdoc/configure/compress_directives.mt b/web/server/h2o/libh2o/srcdoc/configure/compress_directives.mt new file mode 100644 index 00000000..57f7a43e --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/configure/compress_directives.mt @@ -0,0 +1,82 @@ +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Configure", "Compress Directives")->(sub { + +

+The compress handler performs on-the-fly compression - it compresses the contents of an HTTP response as it is being sent, if the client indicates itself to be capable of decompressing the response transparently with the use of Accept-Encoding header, and if the response is deemed compressible according to the following rules. +

+

+If x-compress-hint response header does not exist or the value is auto, then whether if the response is considered compressible depends on the is_compressible attribute assigned to the content type (see file.mime.addtypes). +If x-compress-hint response header exists and the value is on, the response is always considered to be compressible. +If the value of the response header is set to off, then the response never gets compressed. +

+ +

+The following are the configuration directives recognized by the handler. +

+ +{directive}->( + name => "compress", + levels => [ qw(global host path extension) ], + default => "compress: OFF", + see_also => render_mt(<<'EOT'), +file.send-compressed, file.mime.addtypes +EOT + since => '2.0', + desc => <<'EOT', +Enables on-the-fly compression of HTTP response. +EOT +)->(sub { +?> +

+If the argument is ON, both brotli and gzip compression are enabled. +If the argument is OFF, on-the-fly compression is disabled. +If the argument is a sequence, the elements are the list of compression algorithms to be enabled. +If the argument is a mapping, each key specifies the compression algorithm to be enabled, and the values specify the quality of the algorithms. +

+

+When both brotli and gzip are enabled and if the client supports both, H2O is hard-coded to prefer brotli. +

+{example}->('Enabling on-the-fly compression', <<'EOT') +# enable all algorithms +compress: ON + +# enable by name +compress: [ gzip, br ] + +# enable gzip only +compress: [ gzip ] +EOT +?> +? }) + +{directive}->( + name => "compress-minimum-size", + levels => [ qw(global host path extension) ], + default => "compress-minimum-size: 100", + since => '2.0', + desc => <<'EOT', +Defines the minimum size a files needs to have in order for H2O to compress the request. +EOT +)->(sub {}); +?> + +{directive}->( + name => "gzip", + levels => [ qw(global host path extension) ], + default => "gzip: OFF", + see_also => render_mt(<<'EOT'), +compress +EOT + since => '1.5', + desc => <<'EOT', +Enables on-the-fly compression of HTTP response using gzip. +EOT +)->(sub { +?> +Equivalent to compress: [ gzip ]. +? }) + +? }) diff --git a/web/server/h2o/libh2o/srcdoc/configure/dos_detection.mt b/web/server/h2o/libh2o/srcdoc/configure/dos_detection.mt new file mode 100644 index 00000000..9cba1bf7 --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/configure/dos_detection.mt @@ -0,0 +1,101 @@ +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Configure", "Using DoS Detection")->(sub { + +

+Starting from version 2.1, H2O comes with a mruby script named dos_detector.rb that implements DoS Detection feature. +The script provides a Rack handler that detects HTTP flooding attacks based on the client's IP address. +

+ +

Basic Usage

+ +

+Below example uses the mruby script to detect DoS attacks. +The default detecting 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', <<'EOT'); +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 +EOT +?> + +

+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 Forbidden 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 restricted. 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', <<'EOT'); +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 +EOT +?> +

+ +

Points to Notice

+
    +
  • + For now, counting requests is "per-thread" and not shared between multiple threads. +
    • +
+ +? }) diff --git a/web/server/h2o/libh2o/srcdoc/configure/errordoc_directives.mt b/web/server/h2o/libh2o/srcdoc/configure/errordoc_directives.mt new file mode 100644 index 00000000..94137ae6 --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/configure/errordoc_directives.mt @@ -0,0 +1,52 @@ +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Configure", "Errordoc Directives")->(sub { + +

+This document describes the configuration directives of the errordoc handler. +

+ +{directive}->( + name => "error-doc", + levels => [ qw(global host path extension) ], + desc => <<'EOT', +Specifies the content to be sent when returning an error response (i.e. a response with 4xx or 5xx status code). +EOT +)->(sub { +?> +

+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-language, set-cookie headers obtained from the specified URL are served to the client. +

+

+{example}->('Set error document for 404 status', <<'EOT') +error-doc: + status: 404 + url: /404.html +EOT +?> +{example}->('Set error document for 500 and 503 status', <<'EOT') +error-doc: + - status: 500 + url: /internal-error.html + - status: 503 + url: /service-unavailable.html +EOT +?> +{example}->('Set error document for 50x statuses (From version 2.3)', <<'EOT') +error-doc: + status: [500, 502, 503, 504] + url: /50x.html +EOT +?> +

+? }) + +? }) diff --git a/web/server/h2o/libh2o/srcdoc/configure/expires_directives.mt b/web/server/h2o/libh2o/srcdoc/configure/expires_directives.mt new file mode 100644 index 00000000..a3b22f85 --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/configure/expires_directives.mt @@ -0,0 +1,32 @@ +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Configure", "Expires Directives")->(sub { + +

+This document describes the configuration directives of the expires handler. +

+ +{directive}->( + name => "expires", + levels => [ qw(global host path extension) ], + desc => <<'EOT', +An optional directive for setting the Cache-Control: max-age= header. +EOT +)->(sub { +?> +
    +
  • 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', <<'EOT') +expires: 1 day +EOT +?> +

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

+? }) + +? }) diff --git a/web/server/h2o/libh2o/srcdoc/configure/fastcgi_directives.mt b/web/server/h2o/libh2o/srcdoc/configure/fastcgi_directives.mt new file mode 100644 index 00000000..2e287088 --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/configure/fastcgi_directives.mt @@ -0,0 +1,114 @@ +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Configure", "FastCGI Directives")->(sub { + +

+This document describes the configuration directives of the FastCGI handler. +

+

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

+ +{directive}->( + name => "fastcgi.connect", + levels => [ qw(path extension) ], + desc => q{The directive specifies the address at where the FastCGI daemon is running.}, +)->(sub { +?> +

+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 +
either 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', <<'EOT'); +hosts: + "example.com:80": + paths: + "/app": + fastcgi.connect: + port: /tmp/fcgi.sock + type: unix +EOT +?> +? }) + +{directive}->( + name => "fastcgi.spawn", + levels => [ qw(path extension) ], + desc => q{The directive specifies the command to start the FastCGI process manager.}, +)->(sub { +?> +

+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', <<'EOT'); +file.custom-handler: + extension: .php + fastcgi.spawn: "PHP_FCGI_CHILDREN=10 exec /usr/local/bin/php-cgi" +EOT +?> +

+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', <<'EOT'); +file.custom-handler: + extension: .php + fastcgi.spawn: + command: "PHP_FCGI_CHILDREN=10 exec /usr/local/bin/php-cgi" + user: fastcgi +EOT +?> +? }) + +{directive}->( + name => "fastcgi.timeout.io", + levels => [ qw(global host path extension) ], + default => q{fastcgi.timeout.io: 30000}, + desc => q{Sets the I/O timeout of connections to the FastCGI process in milliseconds.}, +)->(sub {}); +?> + +{directive}->( + name => "fastcgi.timeout.keepalive", + levels => [ qw(global host path extension) ], + default => q{fastcgi.timeout.keepalive: 0}, + desc => 'Sets the keepl-alive timeout for idle connections in milliseconds.', +)->(sub { +?> +

+FastCGI connections will not be persistent if the value is set to zero (default). +

+? }) + +{directive}->( + name => "fastcgi.send-delegated-uri", + levels => [ qw(global host path extension) ], + default => q{fastcgi.send-delegated-uri: OFF}, + desc => 'Send the modified HTTP_HOST and REQUEST_URI being rewritten in case of internal redirect.', +)->(sub { +?> +

+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 values should be sent. +

+? }) + +? }) diff --git a/web/server/h2o/libh2o/srcdoc/configure/file_directives.mt b/web/server/h2o/libh2o/srcdoc/configure/file_directives.mt new file mode 100644 index 00000000..b56de065 --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/configure/file_directives.mt @@ -0,0 +1,244 @@ +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Configure", "File Directives")->(sub { + +

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

+ +{directive}->( + name => "file.custom-handler", + levels => [ qw(global host path) ], + desc => q{The directive maps extensions to a custom handler (e.g. FastCGI).}, +)->(sub { +?> +

+The directive accepts a mapping containing configuration directives that can be used at the extension level, together with a property named extension specifying a extension (starting with .) or a sequence of extensions to which the directives should be applied. +Only one handler must exist within the directives. +

+{example}->('Mapping PHP files to FastCGI', <<'EOT') +file.custom-handler: + extension: .php + fastcgi.connect: + port: /tmp/fcgi.sock + type: unix + +EOT +?> +? }) + +{directive}->( + name => "file.dir", + levels => [ qw(path) ], + desc => q{The directive specifies the directory under which should be served for the corresponding path.}, + see_also => render_mt(<file.dirlisting, +file.file, +file.index +EOT +)->(sub { +?> +{example}->('Serving files under different paths', <<'EOT') +paths: + "/": + file.dir: /path/to/doc-root + "/icons": + file.dir: /path/to/icons-dir +EOT +?> +? }) + +{directive}->( + name => "file.dirlisting", + levels => [ qw(global host path) ], + default => 'file.dirlisting: OFF', + desc => <<'EOT', +A boolean flag (OFF, or ON) specifying whether or not to send the directory listing in case none of the index files exist. +EOT + see_also => render_mt(<file.dir +EOT +)->(sub {}); + +$ctx->{directive}->( + name => "file.etag", + levels => [ qw(global host path) ], + default => 'file.etag: ON', + desc => <<'EOT', +A boolean flag (OFF, or ON) specifying whether or not to send etags. +EOT +)->(sub {}); +?> + +{directive}->( + name => "file.file", + levels => [ qw(path) ], + desc => q{The directive maps a path to a specific file.}, + see_also => render_mt(<file.dir +EOT + since => '2.0', +)->(sub { +?> +{example}->('Mapping a path to a specific file', <<'EOT') +paths: + /robots.txt: + file.file: /path/to/robots.txt +EOT +?> +? }) + +{directive}->( + name => "file.index", + levels => [ qw(global host path) ], + default => "file.index: [ 'index.html', 'index.htm', 'index.txt' ]", + desc => q{Specifies the names of the files that should be served when the client sends a request against the directory.}, + see_also => render_mt(<file.dir +EOT +)->(sub { +?> +

+The sequence of filenames are searched from left to right, and the first file that existed is sent to the client. +

+? }) + +{directive}->( + name => "file.mime.addtypes", + levels => [ qw(global host path) ], + see_also => render_mt(<<'EOT'), +compress, +http2-casper, +http2-reprioritize-blocking-assets +EOT + desc => q{The directive modifies the MIME mappings by adding the specified MIME type mappings.}, +)->(sub { +?> +{example}->('Adding MIME mappings', <<'EOT') +file.mime.addtypes: + "application/javascript": ".js" + "image/jpeg": [ ".jpg", ".jpeg" ] +EOT +?> +

+The default mappings is hard-coded in lib/handler/mimemap/defaults.c.h. +

+

+It is also possible to set certain attributes for a MIME type. +The example below maps .css files to text/css type, setting is_compressible flag to ON and priority to highest. +

+ +{example}->('Setting MIME attributes', <<'EOT') +file.mime.settypes: + "text/css": + extensions: [".css"] + is_compressible: yes + priority: highest +EOT +?> + +

+Following attributes are recognized. +

+ + +
AttributePossible ValuesDescription +
is_compressibleON, OFFif content is compressible +
priorityhighest, normalsend priority of the content +
+ +

+The priority attribute affects how the HTTP/2 protocol implementation handles the request. +For detail, please refer to the HTTP/2 directives listed in the see also section below. +By default, mime-types for CSS and JavaScript files are the only ones that are given highest priority. +

+ +? }) + +{directive}->( + name => "file.mime.removetypes", + levels => [ qw(global host path) ], + desc => q{Removes the MIME mappings for specified extensions supplied as a sequence of extensions.}, +)->(sub { +?> +{example}->('Removing MIME mappings', <<'EOT') +file.mime.removetypes: [ ".jpg", ".jpeg" ] +EOT +?> +? }) + +{directive}->( + name => "file.mime.setdefaulttype", + levels => [ qw(global host path) ], + default => q{file.mime.setdefaulttype: "application/octet-stream"}, + desc => q{Sets the default MIME-type that is used when an extension does not exist in the MIME mappings}, +)->(sub {}) +?> + +{directive}->( + name => "file.mime.settypes", + levels => [ qw(global host path) ], + desc => q{Resets the MIME mappings to given mapping.}, +)->(sub { +?> +{example}->('Resetting the MIME mappings to minimum', <<'EOT') +file.mime.settypes: + "text/html": [ ".html", ".htm" ] + "text/plain": ".txt" +EOT +?> +? }) + +{directive}->( + name => "file.send-compressed", + levels => [ qw(global host path) ], + default => q{file.send-compressed: OFF}, + see_also => render_mt(<<'EOT'), +compress +EOT + since => '2.0', + desc => <<'EOT', +A flag indicating how a pre-compressed file should be served. +EOT +)->(sub { +?> +

+If set to ON, the handler looks for a file with .br or .gz appended and sends the file, if the client is capable of transparently decoding a brotli or gzip-encoded response. +For example, if a client requests a file named index.html with Accept-Encoding: gzip header and if index.html.gz exists, the .gz file is sent as a response together with a Content-Encoding: gzip response header. +

+

+If set to OFF, the handler always serves the file specified by the client. +

+

+Starting from version 2.2, gunzip is also supported. +If set, the handler acts identical to when the value was set to ON. +In addition, the handler will send an uncompressed response by dynamically decompressing the .gz file if the client and the server failed to agree on using a pre-compressed file as the response and if a non-compressed file was not found. +The option is useful when conserving disk space is important; it is possible to remove the uncompressed files in place for gzipped ones. +

+? }) + +{directive}->( + name => "file.send-gzip", + levels => [ qw(global host path) ], + desc => <<'EOT', +Obsoleted in 2.0. +Synonym of file.send-compressed. +EOT +)->(sub {}) +?> + +? }) diff --git a/web/server/h2o/libh2o/srcdoc/configure/headers_directives.mt b/web/server/h2o/libh2o/srcdoc/configure/headers_directives.mt new file mode 100644 index 00000000..6c2af078 --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/configure/headers_directives.mt @@ -0,0 +1,84 @@ +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Configure", "Headers Directives")->(sub { + +

+This document describes the configuration directives of the headers handler. +

+ +{directive}->( + name => "header.add", + levels => [ qw(global host path extension) ], + desc => q{Adds a new header line to the response headers, regardless if a header with the same name already exists.}, +)->(sub { +?> +
+
Example. Setting the Set-Cookie header
+
header.add: "Set-Cookie: test=1"
+
+? }) + +{directive}->( + name => "header.append", + levels => [ qw(global host path extension) ], + desc => <<'EOT', +Adds a new header line, or appends the value to the existing header with the same name, separated by ,. +EOT +)->(sub {}); +?> + +{directive}->( + name => "header.merge", + levels => [ qw(global host path extension) ], + desc => <<'EOT', +Adds a new header line, or merges the value to the existing header of comma-separated values. +EOT +)->(sub { +?> +

+The following example sets the must-revalidate attribute of the Cache-Control header when and only when the attribute is not yet being set. +

+{example}->('Setting the must-revalidate attribute', <<'EOT') +header.merge: "Cache-Control: must-revalidate" +EOT +?> +? }) + +{directive}->( + name => "header.set", + levels => [ qw(global host path extension) ], + desc => q{Sets a header line, removing headers with the same name if exists.}, +)->(sub { +?> +{example}->('Setting the X-Content-Type-Options: nosniff header', <<'EOT') +header.set: "X-Content-Type-Options: nosniff" +EOT +?> +? }) + +{directive}->( + name => "header.setifempty", + levels => [ qw(global host path extension) ], + desc => <<'EOT', +Sets a header line when and only when a header with the same name does not already exist. +EOT +)->(sub {}); + +{directive}->( + name => "header.unset", + levels => [ qw(global host path extension) ], + desc => q{Removes headers with given name.}, +)->(sub { +?> +{example}->('Removing the X-Powered-By header', <<'EOT') +header.unset: "X-Powered-By" +EOT +?> +? }) + +? }) diff --git a/web/server/h2o/libh2o/srcdoc/configure/http1_directives.mt b/web/server/h2o/libh2o/srcdoc/configure/http1_directives.mt new file mode 100644 index 00000000..77894acc --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/configure/http1_directives.mt @@ -0,0 +1,24 @@ +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Configure", "HTTP/1 Directives")->(sub { + +

+This document describes the configuration directives for controlling the HTTP/1 protocol handler. +

+ +{directive}->( + name => "http1-request-timeout", + levels => [ qw(global) ], + default => 'http1-request-timeout: 10', + desc => q{Timeout for incoming requests in seconds.}, +)->(sub {}); + +$ctx->{directive}->( + name => "http1-upgrade-to-http2", + levels => [ qw(global) ], + default => 'http1-upgrade-to-http2: ON', + desc => q{Boolean flag (ON or OFF) indicating whether or not to allow upgrade to HTTP/2.}, +)->(sub {}); +?> + +? }) diff --git a/web/server/h2o/libh2o/srcdoc/configure/http2_directives.mt b/web/server/h2o/libh2o/srcdoc/configure/http2_directives.mt new file mode 100644 index 00000000..7c2fc26e --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/configure/http2_directives.mt @@ -0,0 +1,356 @@ +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Configure", "HTTP/2 Directives")->(sub { + +

+H2O provides one of the world's most sophisticated HTTP/2 protocol implementation, including following features. +

+ +

Prioritization

+ +

+H2O is one of the few servers that fully implement prioritization of HTTP responses conformant to what is defined in the HTTP/2 specification. +The server implements a O(1) scheduler that determines which HTTP response should be sent to the client, per every 16KB chunk. +

+

+Unfortunately, some web browsers fail to specify response priorities that lead to best end-user experience. +H2O is capable of detecting such web browsers, and if it does, uses server-driven prioritization; i.e. send responses with certain MIME-types before others. +

+

+It is possible to tune or turn off server-driven prioritization using directives: file.mime.addtypes, http2-reprioritize-blocking-assets. +

+

+See also: +

+

+ +

Server push

+ +

+H2O recognizes link headers with preload keyword sent by a backend application server (reverse proxy or FastCGI) or an mruby handler, and pushes the designated resource to a client. +

+{example}->('A link response header triggering HTTP/2 push', <<'EOT') +link: ; rel=preload; as=script +EOT +?> + +

When the HTTP/2 driver of H2O recognizes a link response header with rel=preload attribute set, and if all of the following conditions are met, the specified resource is pushed to the client. +

+
    +
  • configuration directive http2-push-preload is not set to OFF
    • +
  • the link header does not have the nopush attribute set
    • +
  • the link header is not part of a pushed response
    • +
  • the client does not disable HTTP/2 push
    • +
  • number of the pushed responses in-flight is below the negotiated threshold
    • +
  • authority of the resource specified is equivalent to the request that tried to trigger the push
    • +
  • (for handlers that return the status code synchronously) the status code of the response to be pushed does not indicate an error (i.e. 4xx or 5xx)
    • +
+

+The server also provides a mechanism to track the clients' cache state via cookies, and to push the resources specified with the link header only when it does not exist within the clients' cache. For details, please refer to the documentation of http2-casper configuration directive. +

+

+When a resource is pushed, the priority is determined using the priority attribute of the MIME-type configuration. If the priority is set to highest then the resource will be sent to the client before anything else; otherwise the resource will be sent to client after the main content, as per defined by the HTTP/2 specification. +

+

+HTTP/1.1 allows a server to send an informational response (see RFC 7230 section 6.2) before sending the final response. +Starting from version 2.1, web applications can take advantage of the informational response to initiate HTTP/2 pushes before starting to process the request. +The following example shows how such responses would look like. +

+{example}->('100 response with link headers', <<'EOT') +HTTP/1.1 100 Continue +Link: ; rel=preload; as=style +Link: ; rel=preload; as=script + +HTTP/1.1 200 OK +Content-Type: text/html; charset=utf-8 + + + + + +