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.

"file.custom-handler"

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

"file.dir"

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

"file.dirlisting"

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

"file.etag"

Description:

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

Level:
global, host, path
Default:
file.etag: ON

"file.index"

Description:

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

The sequence of filenames afer search 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' ]

"file.mime.addtypes"

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, seting 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:
gzip, http2-casper, http2-reprioritize-blocking-assets

"file.mime.removetypes"

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

"file.mime.setdefaulttype"

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"

"file.mime.settypes"

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

"file.send-gzip"

Description:

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

If set to ON, the handler looks for a file with .gz appended and sends the file (i.e. sends the contents of index.html.gz in place of index.html) if the client is capable of transparently decoding a gzipped response.

Level:
global, host, path
Default:
file.send-gzip: OFF
See also:
gzip