diff options
Diffstat (limited to '')
| -rw-r--r-- | web/server/h2o/libh2o/doc/configure/file_directives.html | 427 |
1 files changed, 427 insertions, 0 deletions
diff --git a/web/server/h2o/libh2o/doc/configure/file_directives.html b/web/server/h2o/libh2o/doc/configure/file_directives.html new file mode 100644 index 00000000..a5ec2c68 --- /dev/null +++ b/web/server/h2o/libh2o/doc/configure/file_directives.html @@ -0,0 +1,427 @@ +<!DOCTYPE html> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> +<meta name="viewport" content="width=device-width,initial-scale=1,user-scalable=no" /> +<base href="../" /> + +<!-- oktavia --> +<link rel="stylesheet" href="assets/searchstyle.css" type="text/css" /> +<script src="search/jquery-1.9.1.min.js"></script> +<script src="search/oktavia-jquery-ui.js"></script> +<script src="search/oktavia-english-search.js"></script> +<!-- /oktavia --> + +<link rel="stylesheet" href="assets/style.css" type="text/css" /> + +<title>File Directives - Configure - H2O - the optimized HTTP/2 server</title> +</head> +<body> +<div id="body"> +<div id="top"> + +<h1> +<a href="index.html">H2O</a> +</h1> +<p class="description">the optimized HTTP/1.x, HTTP/2 server</p> + +<!-- oktavia --> +<form id="searchform"> +<input class="search" type="search" name="search" id="search" results="5" value="" placeholder="Search" /> +<div id="searchresult_box"> +<div id="close_search_box">×</div> +<div id="searchresult_summary"></div> +<div id="searchresult"></div> +<div id="searchresult_nav"></div> +<span class="pr">Powered by <a href="https://github.com/shibukawa/oktavia">Oktavia</a></span> +</div> +</form> +<!-- /oktavia --> + +</div> + +<table id="menu"> +<tr> +<td><a href="index.html">Top</a></td> +<td><a href="install.html">Install</a></td> +<td class="selected">Configure</td> +<td><a href="faq.html">FAQ</a></td> +<td><a href="http://blog.kazuhooku.com/search/label/H2O" target="_blank">Blog</a></td> +<td><a href="http://github.com/h2o/h2o/" target="_blank">Source</a></td> +</tr> +</table> + +<div id="main"> + +<h2> +<a href="configure.html">Configure</a> > +File Directives +</h2> + + +<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> + +<div id="file.custom-handler" class="directive-head"> +<h3><a href="configure/file_directives.html#file.custom-handler"><code>"file.custom-handler"</code></a></h3> +</div> + +<dl class="directive-desc"> +<dt>Description:</dt> +<dd> +<p> +The directive maps extensions to a custom handler (e.g. FastCGI). +</p> + +<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> +<div class="example"> +<div class="caption">Example. Mapping PHP files to FastCGI</div> +<pre><code>file.custom-handler: + extension: .php + fastcgi.connect: + port: /tmp/fcgi.sock + type: unix + +</code></pre> +</div> + + +</dd> +<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt> +<dd>global, host, path</dd> +</dl> + +<div id="file.dir" class="directive-head"> +<h3><a href="configure/file_directives.html#file.dir"><code>"file.dir"</code></a></h3> +</div> + +<dl class="directive-desc"> +<dt>Description:</dt> +<dd> +<p> +The directive specifies the directory under which should be served for the corresponding path. +</p> + +<div class="example"> +<div class="caption">Example. Serving files under different paths</div> +<pre><code>paths: + "/": + file.dir: /path/to/doc-root + "/icons": + file.dir: /path/to/icons-dir +</code></pre> +</div> + + +</dd> +<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt> +<dd>path</dd> +<dt>See also:</dt> +<dd><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> +</dd> +</dl> + +<div id="file.dirlisting" class="directive-head"> +<h3><a href="configure/file_directives.html#file.dirlisting"><code>"file.dirlisting"</code></a></h3> +</div> + +<dl class="directive-desc"> +<dt>Description:</dt> +<dd> +<p> +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. + +</p> + +</dd> +<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt> +<dd>global, host, path</dd> +<dt>Default:</dt> +<dd><code><pre>file.dirlisting: OFF</pre></code> +<dt>See also:</dt> +<dd><a href="configure/file_directives.html#file.dir"><code>file.dir</code></a> +</dd> +</dl> +<div id="file.etag" class="directive-head"> +<h3><a href="configure/file_directives.html#file.etag"><code>"file.etag"</code></a></h3> +</div> + +<dl class="directive-desc"> +<dt>Description:</dt> +<dd> +<p> +A boolean flag (<code>OFF</code>, or <code>ON</code>) specifying whether or not to send etags. + +</p> + +</dd> +<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt> +<dd>global, host, path</dd> +<dt>Default:</dt> +<dd><code><pre>file.etag: ON</pre></code> +</dl> + + +<div id="file.file" class="directive-head"> +<div class="directive-since">since v2.0</div> +<h3><a href="configure/file_directives.html#file.file"><code>"file.file"</code></a></h3> +</div> + +<dl class="directive-desc"> +<dt>Description:</dt> +<dd> +<p> +The directive maps a path to a specific file. +</p> + +<div class="example"> +<div class="caption">Example. Mapping a path to a specific file</div> +<pre><code>paths: + /robots.txt: + file.file: /path/to/robots.txt +</code></pre> +</div> + + +</dd> +<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt> +<dd>path</dd> +<dt>See also:</dt> +<dd><a href="configure/file_directives.html#file.dir"><code>file.dir</code></a> +</dd> +</dl> + +<div id="file.index" class="directive-head"> +<h3><a href="configure/file_directives.html#file.index"><code>"file.index"</code></a></h3> +</div> + +<dl class="directive-desc"> +<dt>Description:</dt> +<dd> +<p> +Specifies the names of the files that should be served when the client sends a request against the directory. +</p> + +<p> +The sequence of filenames are searched from left to right, and the first file that existed is sent to the client. +</p> + +</dd> +<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt> +<dd>global, host, path</dd> +<dt>Default:</dt> +<dd><code><pre>file.index: [ 'index.html', 'index.htm', 'index.txt' ]</pre></code> +<dt>See also:</dt> +<dd><a href="configure/file_directives.html#file.dir"><code>file.dir</code></a> +</dd> +</dl> + +<div id="file.mime.addtypes" class="directive-head"> +<h3><a href="configure/file_directives.html#file.mime.addtypes"><code>"file.mime.addtypes"</code></a></h3> +</div> + +<dl class="directive-desc"> +<dt>Description:</dt> +<dd> +<p> +The directive modifies the MIME mappings by adding the specified MIME type mappings. +</p> + +<div class="example"> +<div class="caption">Example. Adding MIME mappings</div> +<pre><code>file.mime.addtypes: + "application/javascript": ".js" + "image/jpeg": [ ".jpg", ".jpeg" ] +</code></pre> +</div> + +<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> + +<div class="example"> +<div class="caption">Example. Setting MIME attributes</div> +<pre><code>file.mime.settypes: + "text/css": + extensions: [".css"] + is_compressible: yes + priority: highest +</code></pre> +</div> + + +<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> + + +</dd> +<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt> +<dd>global, host, path</dd> +<dt>See also:</dt> +<dd><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> +</dd> +</dl> + +<div id="file.mime.removetypes" class="directive-head"> +<h3><a href="configure/file_directives.html#file.mime.removetypes"><code>"file.mime.removetypes"</code></a></h3> +</div> + +<dl class="directive-desc"> +<dt>Description:</dt> +<dd> +<p> +Removes the MIME mappings for specified extensions supplied as a sequence of extensions. +</p> + +<div class="example"> +<div class="caption">Example. Removing MIME mappings</div> +<pre><code>file.mime.removetypes: [ ".jpg", ".jpeg" ] +</code></pre> +</div> + + +</dd> +<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt> +<dd>global, host, path</dd> +</dl> + +<div id="file.mime.setdefaulttype" class="directive-head"> +<h3><a href="configure/file_directives.html#file.mime.setdefaulttype"><code>"file.mime.setdefaulttype"</code></a></h3> +</div> + +<dl class="directive-desc"> +<dt>Description:</dt> +<dd> +<p> +Sets the default MIME-type that is used when an extension does not exist in the MIME mappings +</p> + +</dd> +<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt> +<dd>global, host, path</dd> +<dt>Default:</dt> +<dd><code><pre>file.mime.setdefaulttype: "application/octet-stream"</pre></code> +</dl> + + +<div id="file.mime.settypes" class="directive-head"> +<h3><a href="configure/file_directives.html#file.mime.settypes"><code>"file.mime.settypes"</code></a></h3> +</div> + +<dl class="directive-desc"> +<dt>Description:</dt> +<dd> +<p> +Resets the MIME mappings to given mapping. +</p> + +<div class="example"> +<div class="caption">Example. Resetting the MIME mappings to minimum</div> +<pre><code>file.mime.settypes: + "text/html": [ ".html", ".htm" ] + "text/plain": ".txt" +</code></pre> +</div> + + +</dd> +<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt> +<dd>global, host, path</dd> +</dl> + +<div id="file.send-compressed" class="directive-head"> +<div class="directive-since">since v2.0</div> +<h3><a href="configure/file_directives.html#file.send-compressed"><code>"file.send-compressed"</code></a></h3> +</div> + +<dl class="directive-desc"> +<dt>Description:</dt> +<dd> +<p> +A flag indicating how a pre-compressed file should be served. + +</p> + +<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> + +</dd> +<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt> +<dd>global, host, path</dd> +<dt>Default:</dt> +<dd><code><pre>file.send-compressed: OFF</pre></code> +<dt>See also:</dt> +<dd><a href="configure/compress_directives.html#compress"><code>compress</code></a> +</dd> +</dl> + +<div id="file.send-gzip" class="directive-head"> +<h3><a href="configure/file_directives.html#file.send-gzip"><code>"file.send-gzip"</code></a></h3> +</div> + +<dl class="directive-desc"> +<dt>Description:</dt> +<dd> +<p> +Obsoleted in 2.0. +Synonym of <a href="configure/file_directives.html#file.send-compressed"><code>file.send-compressed</code></a>. + +</p> + +</dd> +<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt> +<dd>global, host, path</dd> +</dl> + + + + + +</div> +<div id="footer"> +<p> +Copyright © 2015 <a href="http://dena.com/intl/">DeNA Co., Ltd.</a> et al. +</p> +</div> +</body> +</html> |