mirror of
https://github.com/h2o/h2o.git
synced 2025-05-15 02:02:57 +08:00
504 lines
16 KiB
HTML
504 lines
16 KiB
HTML
<!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 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, HTTP/3 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"><a href="configure.html">Configure</a></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>
|
|
|
|
<ul>
|
|
<li><a href="configure/file_directives.html#file.custom-handler">
|
|
<code>file.custom-handler</code>
|
|
</a></li>
|
|
<li><a href="configure/file_directives.html#file.dir">
|
|
<code>file.dir</code>
|
|
</a></li>
|
|
<li><a href="configure/file_directives.html#file.dirlisting">
|
|
<code>file.dirlisting</code>
|
|
</a></li>
|
|
<li><a href="configure/file_directives.html#file.etag">
|
|
<code>file.etag</code>
|
|
</a></li>
|
|
<li><a href="configure/file_directives.html#file.file">
|
|
<code>file.file</code>
|
|
</a></li>
|
|
<li><a href="configure/file_directives.html#file.index">
|
|
<code>file.index</code>
|
|
</a></li>
|
|
<li><a href="configure/file_directives.html#file.io_uring">
|
|
<code>file.io_uring</code>
|
|
</a></li>
|
|
<li><a href="configure/file_directives.html#file.mime.addtypes">
|
|
<code>file.mime.addtypes</code>
|
|
</a></li>
|
|
<li><a href="configure/file_directives.html#file.mime.removetypes">
|
|
<code>file.mime.removetypes</code>
|
|
</a></li>
|
|
<li><a href="configure/file_directives.html#file.mime.setdefaulttype">
|
|
<code>file.mime.setdefaulttype</code>
|
|
</a></li>
|
|
<li><a href="configure/file_directives.html#file.mime.settypes">
|
|
<code>file.mime.settypes</code>
|
|
</a></li>
|
|
<li><a href="configure/file_directives.html#file.send-compressed">
|
|
<code>file.send-compressed</code>
|
|
</a></li>
|
|
<li><a href="configure/file_directives.html#file.send-gzip">
|
|
<code>file.send-gzip</code>
|
|
</a></li>
|
|
</ul>
|
|
|
|
|
|
<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.
|
|
If all the files (including those without extensions) shall be mapped, this property must be set to <code>default</code>.
|
|
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.io_uring" class="directive-head">
|
|
<div class="directive-since">experimental</div>
|
|
<h3><a href="configure/file_directives.html#file.io_uring"><code>"file.io_uring"</code></a></h3>
|
|
</div>
|
|
|
|
<dl class="directive-desc">
|
|
<dt>Description:</dt>
|
|
<dd>
|
|
<p>
|
|
If io_uring should be used for serving files.
|
|
</p>
|
|
|
|
<p>
|
|
By default, H2O uses system calls such as pread (2) or sendfile (2), which block if the file being read is not in the page cache.
|
|
This can prevent H2O's worker threads from making progress on any connection handled by the affected thread.
|
|
When this flag is enabled, H2O is no longer blocked by the I/O calls, as the data is asynchronously copied from disk to the page cache before h2o attempts to access it.
|
|
</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.io_uring: OFF</pre></code>
|
|
<dt>See also:</dt>
|
|
<dd><a href="configure/base_directives.html#io_uring-batch-size"><code>io_uring-batch-size</code></a>,
|
|
<a href="configure/base_directives.html#max-spare-pipes"><code>max-spare-pipes</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>, <code>.zstd</code>, or <code>.gz</code> appended and sends the file, if the client is capable of transparently decoding a <a href="https://www.rfc-editor.org/rfc/rfc7932.html" target=_blank>brotli</a>, <a href="https://www.rfc-editor.org/rfc/rfc8878.html" target=_blank>zstd</a>, or <a href="https://tools.ietf.org/html/rfc1952" target=_blank>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.
|
|
When both the client and the server support multiple content encodings, the encoding chosen is the first one listed in the following order: brotli, zstd, gzip.
|
|
</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-2023 <a href="http://dena.com/intl/">DeNA Co., Ltd.</a> et al.
|
|
</p>
|
|
</div>
|
|
</body>
|
|
</html>
|