H2O

the optimized HTTP/1.x, HTTP/2 server

Powered by Oktavia

Configure > File Directives

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.

Description:

The directive maps extensions to a custom handler (e.g. FastCGI).

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
file.custom-handler:
  extension: .php
  fastcgi.connect:
    port: /tmp/fcgi.sock
    type: unix
Level:
global, host, path
Description:

The directive specifies the directory under which should be served for the corresponding path.

Example. Serving files under different paths
paths:
    "/":
        file.dir: /path/to/doc-root
    "/icons":
        file.dir: /path/to/icons-dir
Level:
path
See also:
file.dirlisting, file.file, file.index
Description:

A boolean flag (OFF, or ON) specifying whether or not to send the directory listing in case none of the index files exist.

Level:
global, host, path
Default:
file.dirlisting: OFF
See also:
file.dir
Description:

A boolean flag (OFF, or ON) specifying whether or not to send etags.

Level:
global, host, path
Default:
file.etag: ON
since v2.0

"file.file"

Description:

The directive maps a path to a specific file.

Example. Mapping a path to a specific file
paths:
  /robots.txt:
    file.file: /path/to/robots.txt
Level:
path
See also:
file.dir
Description:

Specifies the names of the files that should be served when the client sends a request against the directory.

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

Level:
global, host, path
Default:
file.index: [ 'index.html', 'index.htm', 'index.txt' ]
See also:
file.dir
Description:

The directive modifies the MIME mappings by adding the specified MIME type mappings.

Example. Adding MIME mappings
file.mime.addtypes:
    "application/javascript": ".js"
    "image/jpeg": [ ".jpg", ".jpeg" ]

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
file.mime.settypes:
    "text/css":
         extensions: [".css"]
         is_compressible: yes
         priority: highest

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.

Level:
global, host, path
See also:
compress, http2-casper, http2-reprioritize-blocking-assets
Description:

Removes the MIME mappings for specified extensions supplied as a sequence of extensions.

Example. Removing MIME mappings
file.mime.removetypes: [ ".jpg", ".jpeg" ]
Level:
global, host, path
Description:

Sets the default MIME-type that is used when an extension does not exist in the MIME mappings

Level:
global, host, path
Default:
file.mime.setdefaulttype: "application/octet-stream"
Description:

Resets the MIME mappings to given mapping.

Example. Resetting the MIME mappings to minimum
file.mime.settypes:
    "text/html":  [ ".html", ".htm" ]
    "text/plain": ".txt"
Level:
global, host, path
Description:

A boolean flag (ON or OFF) indicating whether or not so send .br or .gz variants if possible.

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.

Level:
global, host, path
Default:
file.send-compressed: OFF
See also:
compress
Description:

Obsoleted in 2.0. Synonym of file.send-compressed.

Level:
global, host, path