http.fastcgi

fastcgi proxies requests to a FastCGI server. Even though the most common use for this directive is to serve PHP sites, it is by default a generic FastCGI proxy. This directive may be used multiple times with different request paths.

Syntax

fastcgi *path endpoint* [*preset*] { root *directory* ext *extension* split *splitval* index *indexfile* env *key value* except *ignored_paths...* upstream *endpoint* connect_timeout *duration* read_timeout *duration* send_timeout *duration* }

• path is the base path to match before the request will be forwarded.
• endpoint is the address or Unix socket of the FastCGI server.
• preset is an optional preset name (see below). You do not need to repeat a preset’s individual settings when using a preset.
• root specifies the root directory used by the FastCGI server if different from the root directory of the virtual host. Useful if the FastCGI server is on a different server, chroot-jailed, and/or containerized.
• ext specifies the extension which, if the request URL has it, would proxy the request to FastCGI.
• split specifies how to split the URL; the split value becomes the end of the first part and anything in the URL after it becomes part of the PATH_INFO CGI variable.
• index specifies the default file to try if a file is not specified by the URL.
• env sets an environment variable named key with the given value; the env property can be used multiple times and values may use request placeholders.
• except is a list of space-separated request paths to be excepted from fastcgi processing, even if it matches the base path.
• upstream specifies an additional backend to use. Basic load balancing will be performed. This can be specified multiple times.
• connect_timeout is the time allowed for connecting to the backend. Must be a duration value (e.g. “10s”). Default 60s.
• read_timeout is the time allowed to read a response from the backend. Must be a duration value. Default 60s.
• send_timeout is the time allowed to send a request to the backend. Must be a duration value. Default 60s.

For HTTPS connections, the following environment variables are set, in a manner compliant with httpd’s mod_ssl: HTTPS, SSL_PROTOCOL, and SSL_CIPHER.

Presets

A preset is shorthand for a certain FastCGI configuration. These presets are available:

• php is shorthand for: ext .php split .php index index.php

You do not need to specify the individual configuration settings for a preset. However, you can overwrite its individual settings if needed by declaring them manually.

Examples

Proxy all requests to a FastCGI responder listening at 127.0.0.1:9000:

fastcgi / 127.0.0.1:9000

Forward all requests in /blog to a PHP site (like WordPress) being served with php-fpm:

fastcgi /blog/ 127.0.0.1:9000 php

With custom FastCGI configuration:

fastcgi / 127.0.0.1:9001 { split .html }

With PHP preset, but overriding the ext property:

fastcgi / 127.0.0.1:9001 php { ext .html }

With PHP preset, but the FastCGI server is running in a container based on an official Docker image (with container port 9000 published to 127.0.0.1:9001):

fastcgi / 127.0.0.1:9001 php { root /var/www/html }

Need help with this feature?

Join us in the Caddy forum, where the open source community gathers to share their knowledge.

Does your company use Caddy?

Purchase a commercial license to use Caddy with your business and for basic email support, along with other benefits!