File Directives - Configure - H2O - the optimized HTTP server

# H2O

the optimized HTTP/1.x, HTTP/2, HTTP/3 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.

- `file.custom-handler`
- `file.dir`
- `file.dirlisting`
- `file.etag`
- `file.file`
- `file.index`
- `file.mime.addtypes`
- `file.mime.removetypes`
- `file.mime.setdefaulttype`
- `file.mime.settypes`
- `file.send-compressed`
- `file.send-gzip`

### `"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. If all the files (including those without extensions) shall be mapped, this property must be set to `default`. 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
See also:
  `file.dirlisting`, `file.file`, `file.index`

### `"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
See also:
  `compress`, `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

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`, `.zstd`, or `.gz` appended and sends the file, if the client is capable of transparently decoding a brotli, zstd, 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. 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.

  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