diff options
Diffstat (limited to '')
| -rw-r--r-- | web/server/h2o/libh2o/srcdoc/configure/file_directives.mt | 244 |
1 files changed, 244 insertions, 0 deletions
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 { + +<p> +This document describes the configuration directives of the file handler - a handler that for serving static files. +</p> +<p> +Two directives: <a href="configure/file_directives.html#file.dir"><code>file.dir</code></a> and <a href="configure/file_directives.html#file.file"><code>file.file</code></a> are used to define the mapping. +Other directives modify the behavior of the mappings defined by the two. +</p> + +<? +$ctx->{directive}->( + name => "file.custom-handler", + levels => [ qw(global host path) ], + desc => q{The directive maps extensions to a custom handler (e.g. FastCGI).}, +)->(sub { +?> +<p> +The directive accepts a mapping containing configuration directives that can be used at the <code>extension</code> level, together with a property named <code>extension</code> specifying a extension (starting with <code>.</code>) or a sequence of extensions to which the directives should be applied. +Only one handler must exist within the directives. +</p> +<?= $ctx->{example}->('Mapping PHP files to FastCGI', <<'EOT') +file.custom-handler: + extension: .php + fastcgi.connect: + port: /tmp/fcgi.sock + type: unix + +EOT +?> +? }) + +<? +$ctx->{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(<<EOT), +<a href="configure/file_directives.html#file.dirlisting"><code>file.dirlisting</code></a>, +<a href="configure/file_directives.html#file.file"><code>file.file</code></a>, +<a href="configure/file_directives.html#file.index"><code>file.index</code></a> +EOT +)->(sub { +?> +<?= $ctx->{example}->('Serving files under different paths', <<'EOT') +paths: + "/": + file.dir: /path/to/doc-root + "/icons": + file.dir: /path/to/icons-dir +EOT +?> +? }) + +<? +$ctx->{directive}->( + name => "file.dirlisting", + levels => [ qw(global host path) ], + default => 'file.dirlisting: OFF', + desc => <<'EOT', +A boolean flag (<code>OFF</code>, or <code>ON</code>) specifying whether or not to send the directory listing in case none of the index files exist. +EOT + see_also => render_mt(<<EOT), +<a href="configure/file_directives.html#file.dir"><code>file.dir</code></a> +EOT +)->(sub {}); + +$ctx->{directive}->( + name => "file.etag", + levels => [ qw(global host path) ], + default => 'file.etag: ON', + desc => <<'EOT', +A boolean flag (<code>OFF</code>, or <code>ON</code>) specifying whether or not to send etags. +EOT +)->(sub {}); +?> + +<? +$ctx->{directive}->( + name => "file.file", + levels => [ qw(path) ], + desc => q{The directive maps a path to a specific file.}, + see_also => render_mt(<<EOT), +<a href="configure/file_directives.html#file.dir"><code>file.dir</code></a> +EOT + since => '2.0', +)->(sub { +?> +<?= $ctx->{example}->('Mapping a path to a specific file', <<'EOT') +paths: + /robots.txt: + file.file: /path/to/robots.txt +EOT +?> +? }) + +<? +$ctx->{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(<<EOT), +<a href="configure/file_directives.html#file.dir"><code>file.dir</code></a> +EOT +)->(sub { +?> +<p> +The sequence of filenames are searched from left to right, and the first file that existed is sent to the client. +</p> +? }) + +<? +$ctx->{directive}->( + name => "file.mime.addtypes", + levels => [ qw(global host path) ], + see_also => render_mt(<<'EOT'), +<a href="configure/compress_directives.html#compress"><code>compress</code></a>, +<a href="configure/http2_directives.html#http2-casper"><code>http2-casper</code></a>, +<a href="configure/http2_directives.html#http2-reprioritize-blocking-assets"><code>http2-reprioritize-blocking-assets</code></a> +EOT + desc => q{The directive modifies the MIME mappings by adding the specified MIME type mappings.}, +)->(sub { +?> +<?= $ctx->{example}->('Adding MIME mappings', <<'EOT') +file.mime.addtypes: + "application/javascript": ".js" + "image/jpeg": [ ".jpg", ".jpeg" ] +EOT +?> +<p> +The default mappings is hard-coded in <a href="https://github.com/h2o/h2o/blob/master/lib/handler/mimemap/defaults.c.h">lib/handler/mimemap/defaults.c.h</a>. +</p> +<p> +It is also possible to set certain attributes for a MIME type. +The example below maps <code>.css</code> files to <code>text/css</code> type, setting <code>is_compressible</code> flag to <code>ON</code> and <code>priority</code> to highest. +</p> + +<?= $ctx->{example}->('Setting MIME attributes', <<'EOT') +file.mime.settypes: + "text/css": + extensions: [".css"] + is_compressible: yes + priority: highest +EOT +?> + +<p> +Following attributes are recognized. +</p> + +<table> +<tr><th>Attribute<th>Possible Values<th>Description +<tr><td><code>is_compressible</code><td><code>ON</code>, <code>OFF</code><td>if content is compressible +<tr><td><code>priority</code><td><code>highest<code>, <code>normal</code><td>send priority of the content +</table> + +<p> +The <code>priority</code> attribute affects how the HTTP/2 protocol implementation handles the request. +For detail, please refer to the HTTP/2 directives listed in the <i>see also</i> section below. +By default, mime-types for CSS and JavaScript files are the only ones that are given <code>highest</code> priority. +</p> + +? }) + +<? +$ctx->{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 { +?> +<?= $ctx->{example}->('Removing MIME mappings', <<'EOT') +file.mime.removetypes: [ ".jpg", ".jpeg" ] +EOT +?> +? }) + +<? +$ctx->{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 {}) +?> + +<? +$ctx->{directive}->( + name => "file.mime.settypes", + levels => [ qw(global host path) ], + desc => q{Resets the MIME mappings to given mapping.}, +)->(sub { +?> +<?= $ctx->{example}->('Resetting the MIME mappings to minimum', <<'EOT') +file.mime.settypes: + "text/html": [ ".html", ".htm" ] + "text/plain": ".txt" +EOT +?> +? }) + +<? +$ctx->{directive}->( + name => "file.send-compressed", + levels => [ qw(global host path) ], + default => q{file.send-compressed: OFF}, + see_also => render_mt(<<'EOT'), +<a href="configure/compress_directives.html#compress"><code>compress</code></a> +EOT + since => '2.0', + desc => <<'EOT', +A flag indicating how a pre-compressed file should be served. +EOT +)->(sub { +?> +<p> +If set to <code>ON</code>, the handler looks for a file with <code>.br</code> or <code>.gz</code> appended and sends the file, if the client is capable of transparently decoding a <a href="https://datatracker.ietf.org/doc/draft-alakuijala-brotli/">brotli</a> or <a href="https://tools.ietf.org/html/rfc1952">gzip</a>-encoded response. +For example, if a client requests a file named <code>index.html</code> with <code>Accept-Encoding: gzip</code> header and if <code>index.html.gz</code> exists, the <code>.gz</code> file is sent as a response together with a <code>Content-Encoding: gzip</code> response header. +</p> +<p> +If set to <code>OFF</code>, the handler always serves the file specified by the client. +</p> +<p> +Starting from version 2.2, <code>gunzip</code> is also supported. +If set, the handler acts identical to when the value was set to <code>ON</code>. +In addition, the handler will send an uncompressed response by dynamically decompressing the <code>.gz</code> 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. +</p> +? }) + +<? +$ctx->{directive}->( + name => "file.send-gzip", + levels => [ qw(global host path) ], + desc => <<'EOT', +Obsoleted in 2.0. +Synonym of <a href="configure/file_directives.html#file.send-compressed"><code>file.send-compressed</code></a>. +EOT +)->(sub {}) +?> + +? }) |