File Directives - Configure - H2O - the optimized HTTP/2 server

- -

-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. -

- -

`"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 -

See also:

file.dir -

`"file.etag"`

- -

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 -

- -

`"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 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 -

- -

`"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, 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. -

- - -

Attribute	Possible Values	Description -
`is_compressible`	`ON`, `OFF`	if content is compressible -
`priority`	`highest, normal`	send 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

- -

`"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

- -

since v2.0

`"file.send-compressed"`

- -

Description:

-A flag indicating how a pre-compressed file should be served. - -

- -

-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. -

-If set to OFF, the handler always serves the file specified by the client. -

-Starting from version 2.2, gunzip is also supported. -If set, the handler acts identical to when the value was set to ON. -In addition, the handler will send an uncompressed response by dynamically decompressing the .gz 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. -

- -

Level:

global, host, path

Default:

file.send-compressed: OFF -

See also:

compress -

- -

`"file.send-gzip"`

- -

Description:: -
-Obsoleted in 2.0. -Synonym of file.send-compressed. - -
- -
Level:: global, host, path

- - - - - -

-H2O -

-Configure > -File Directives -