H2O

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

Powered by Oktavia

Configure > FastCGI Directives

This document describes the configuration directives of the FastCGI handler.

The configuration directives of the FastCGI handler can be categorized into two groups. Fastcgi.connect and fastcgi.spawn define the address (or the process) to which the requests should be sent. Other directives customize how the connections to the FastCGI processes should be maintained.

Description:

The directive specifies the address at where the FastCGI daemon is running.

If the argument is a mapping, following properties are recognized.

host
name (or IP address) of the server running the FastCGI daemon (ignored if type is unix)
port
TCP port number or path to the unix socket
type
either tcp (default) or unix

If the argument is a scalar, the value is considered as a TCP port number and the host is assumed to be 127.0.0.1.

Example. Map /app to FastCGI daemon listening to /tmp/fcgi.sock
hosts:
    "example.com:80":
        paths:
            "/app":
                fastcgi.connect:
                    port: /tmp/fcgi.sock
                    type: unix
Level:
path, extension
Description:

Sets the DOCUMENT_ROOT variable to be passed to the FastCGI application.

Level:
global, host, path, extension
Default:
none
Description:

The directive specifies the command to start the FastCGI process manager.

In contrast to fastcgi.connect that connects to a FastCGI server running externally, this directive launches a FastCGI process manager under the control of H2O, and terminates it when H2O quits. The argument is a /bin/sh -c expression to be executed when H2O boots up. The HTTP server records the process id of the expression, and sends SIGTERM to the id when it exits.

Example. Map .php files to 10 worker processes of /usr/local/bin/php-cgi
file.custom-handler:
    extension:     .php
    fastcgi.spawn: "PHP_FCGI_CHILDREN=10 exec /usr/local/bin/php-cgi"
Example. Map any executable file in path /var/www/data/cgi-bin to fastcgi-cgi wrapper
"/cgi-bin":
    file.dir: /var/www/data/cgi-bin
    file.custom-handler:
        extension: default # means "no extension" in this case
        fastcgi.spawn:
            command: "exec /usr/local/share/h2o/fastcgi-cgi"

As of version 1.4.0, the spawned process is run under the privileges of user specified by the user directive (in version 1.3.x, the FastCGI process was spawned under the privileges that spawned the H2O standalone server). It is possible to specify a different user for running the FastCGI process, by providing a mapping that contains an attribute named user together with an attribute named command.

Example. Running FastCGI processes under user fastcgi
file.custom-handler:
    extension:     .php
    fastcgi.spawn:
        command: "PHP_FCGI_CHILDREN=10 exec /usr/local/bin/php-cgi"
        user:    fastcgi
Level:
path, extension
Description:

Sets the I/O timeout of connections to the FastCGI process in milliseconds.

Level:
global, host, path, extension
Default:
fastcgi.timeout.io: 30000
Description:

Sets the keepl-alive timeout for idle connections in milliseconds.

FastCGI connections will not be persistent if the value is set to zero (default).

Level:
global, host, path, extension
Default:
fastcgi.timeout.keepalive: 0
Description:

Send the modified HTTP_HOST and REQUEST_URI being rewritten in case of internal redirect.

In H2O, it is possible to perform internal redirects (a.k.a. delegations or URL rewrites) using the redirect directive or by returning X-Reproxy-URL headers from web applications. The directive specifies whether to send the original values to the FastCGI process (default), or if the rewritten values should be sent.

Level:
global, host, path, extension
Default:
fastcgi.send-delegated-uri: OFF