Skip to main content
Mapagam

Configuring FastCGI (PHP)

1. Setting FastCGI Pass

Directive Values Description
fastcgi_pass unix:/var/run/php-fpm.sock or http://127.0.0.1:9000 Specifies the FastCGI server address to which requests should be passed.

Example: Basic FastCGI Pass Configuration

location ~ \.php$ {
    fastcgi_pass unix:/var/run/php-fpm.sock;
    fastcgi_index index.php;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}
Note: Ensure that the PHP-FPM service is running and accessible at the specified socket or port.

2. Configuring FastCGI Params

Directive Values Description
fastcgi_param key value Sets a FastCGI parameter to be passed to the FastCGI server
fastcgi_pass address Specifies the FastCGI server address
fastcgi_index index.php Specifies the default index file for FastCGI requests
fastcgi_read_timeout 60s Defines the timeout for reading a response from the FastCGI server

Example: Setting FastCGI Parameters

location ~ \.php$ {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_index index.php;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_param QUERY_STRING $query_string;
    fastcgi_param REQUEST_METHOD $request_method;
    fastcgi_param CONTENT_TYPE $content_type;
    fastcgi_param CONTENT_LENGTH $content_length;
    fastcgi_read_timeout 60s;
}

3. Including FastCGI Config

Directive Values Description
fastcgi_config fastcgi.conf Path to the default FastCGI configuration file
fastcgi_params fastcgi_params Path to the default FastCGI parameters file

Example: Including FastCGI Config

location ~ \.php$ {
    fastcgi_pass   127.0.0.1:9000;
    fastcgi_index  index.php;
    fastcgi_param  SCRIPT_FILENAME $document_root$fastcgi_script_name;
    include        fastcgi_params;
}
Note: The fastcgi_params file is typically located in /etc/nginx/ or /usr/local/nginx/conf/. It contains default FastCGI parameters that are commonly used.

4. Setting Script Filename

Directive Values Description
fastcgi_param SCRIPT_FILENAME Specifies the path to the PHP script file to be executed.

Example: Setting SCRIPT_FILENAME

location ~ \.php$ {
    fastcgi_pass   127.0.0.1:9000;
    fastcgi_index  index.php;
    fastcgi_param  SCRIPT_FILENAME $document_root$fastcgi_script_name;
    include        fastcgi_params;
}
Note: The SCRIPT_FILENAME parameter is crucial for PHP-FPM to locate and execute the correct script file.

5. Configuring PHP-FPM

Directive Description Default Notes
fastcgi_pass Specifies the PHP-FPM server address — Required for FastCGI processing
fastcgi_index Specifies the default index file for FastCGI index.php Used when no script is specified
fastcgi_param Sets FastCGI parameters — Can be used to pass environment variables
fastcgi_connect_timeout Timeout for connecting to PHP-FPM 60s Controls how long to wait for a connection
fastcgi_send_timeout Timeout for sending a request to PHP-FPM 60s Controls how long to wait for a response
fastcgi_read_timeout Timeout for reading a response from PHP-FPM 60s Controls how long to wait for data from PHP-FPM

Example: Basic PHP-FPM Configuration

location ~ \.php$ {
    fastcgi_pass unix:/var/run/php-fpm/php-fpm.sock;
    fastcgi_index index.php;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    include fastcgi_params;
}

Example: PHP-FPM with TCP Socket

location ~ \.php$ {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_index index.php;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    include fastcgi_params;
}
Note: Ensure that the PHP-FPM service is running and accessible at the specified socket or port.

6. Setting FastCGI Index

Directive Values Description
fastcgi_index index.php Specifies the default file to be processed by the FastCGI server when a directory is requested.

Example: Setting FastCGI Index

location / {
    fastcgi_pass   127.0.0.1:9000;
    fastcgi_index  index.php;
    fastcgi_param  SCRIPT_FILENAME  /scripts$fastcgi_script_name;
}

7. Configuring FastCGI Buffering

Directive Values Description
fastcgi_buffering on | off Enables or disables buffering of the response from the FastCGI server. Default is on.
fastcgi_buffer_size size Defines the size of the buffer used for reading the first part of the response from the FastCGI server. Default is 4k or 8k.
fastcgi_buffers number size Defines the number and size of buffers used for reading the response from the FastCGI server. Default is 8 4k or 8 8k.
fastcgi_busy_buffers_size size Defines the maximum size of buffers that can be filled with data and are still being processed by the client. Default is 2 * fastcgi_buffer_size.
fastcgi_cache_min_uses number Defines the number of requests that must be made to a FastCGI server before it is eligible for caching. Default is 1.
fastcgi_cache_valid time Defines the time for which a response should be cached. Default is 1h.

Example: Enabling FastCGI Buffering

location ~ \.php$ {
    fastcgi_pass   127.0.0.1:9000;
    fastcgi_index  index.php;
    fastcgi_file_name $document_root$fastcgi_script_name;
    fastcgi_buffering on;
    fastcgi_buffer_size 1k;
    fastcgi_buffers 8 2k;
    fastcgi_busy_buffers_size 4k;
}
Note: Buffering can improve performance by reducing the number of I/O operations, but it may increase memory usage.

8. Setting FastCGI Timeouts

Directive Values Description
fastcgi_connect_timeout 60s Timeout for connecting to FastCGI server
fastcgi_send_timeout 60s Timeout for sending request to FastCGI server
fastcgi_read_timeout 60s Timeout for reading response from FastCGI server
fastcgi_busy_buffers_size 8k|16k Size of buffer to use for buffering a response
fastcgi_buffer_size 4k|8k Size of buffer used to read the first part of the response

Example: Setting FastCGI Timeouts

location ~ \.php$ {
    fastcgi_pass   127.0.0.1:9000;
    fastcgi_index  index.php;
    fastcgi_file_name $document_root$fastcgi_script_name;
    include        fastcgi_params;

    # Set FastCGI timeouts
    fastcgi_connect_timeout 30s;
    fastcgi_send_timeout 30s;
    fastcgi_read_timeout 30s;
}

9. Using FastCGI Cache

Directive Values Description
fastcgi_cache cache_name Name of the cache zone to use for FastCGI responses
fastcgi_cache_valid time Cache duration for different response codes (e.g., 200 1h)
fastcgi_cache_key string Key used to store and retrieve cached responses
fastcgi_cache_min_uses number Minimum number of requests before caching begins
fastcgi_cache_use_stale error, timeout, invalid_header, etc. Conditions under which stale cache is served
fastcgi_cache_lock on, off Lock cache entries to prevent concurrent fetches

Example: Basic FastCGI Cache Setup

location ~ \.php$ {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_cache my_cache;
    fastcgi_cache_valid 200 1h;
    fastcgi_cache_min_uses 1;
    fastcgi_cache_use_stale error timeout updating http_500 http_502;
    fastcgi_cache_lock on;
}
Note: Ensure that fastcgi_cache_path is defined in the http block to configure cache storage.

Example: Cache Path Configuration

http {
    fastcgi_cache_path /var/cache/nginx/fastcgi_cache levels=1:2 keys_zone=my_cache:10m inactive=60m max_size=1g;
}

10. Splitting Path Info

Directive Values Description
fastcgi_split_path_info regex Defines a regular expression to split the PATH_INFO variable into script name and path info components

Example: Setting up path info splitting

location ~ ^(.+\.php)(.*)$ {
    fastcgi_split_path_info ^(.+\.php)(.*)$;
    fastcgi_pass unix:/var/run/php-fpm.sock;
    fastcgi_index index.php;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_param PATH_INFO $fastcgi_path_info;
}
Note: The regex must capture two groups: the script name and the path info. The first group is used as SCRIPT_FILENAME, and the second as PATH_INFO.

11. Setting FastCGI Buffer Sizes

Directive Values Description
fastcgi_buffering on | off Enables or disables buffering of responses from the FastCGI server. Default is on.
fastcgi_buffer_size size Sets the size of the buffer used for reading the first part of the response from the FastCGI server. Default is 4k or 8k depending on the platform.
fastcgi_buffers number size Sets the number and size of buffers used for reading a response from the FastCGI server. Default is 8 4k or 8 8k.
fastcgi_busy_buffers_size size Sets the maximum size of buffers that can be filled with data and are still being processed by the client. Default is 2 * fastcgi_buffer_size.
fastcgi_temp_file_write_size size Sets the size of the buffer used for writing temporary files when the response is too large to fit in memory. Default is 1m.

Example: Configuring FastCGI Buffer Sizes

location ~ \.php$ {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_buffering on;
    fastcgi_buffer_size 8k;
    fastcgi_buffers 8 8k;
    fastcgi_busy_buffers_size 16k;
    fastcgi_temp_file_write_size 1m;
}
Note: Adjusting buffer sizes can significantly impact performance and memory usage. Larger buffers may improve throughput but increase memory consumption.

12. Configuring FastCGI Intercept Errors

Directive Values Description
fastcgi_intercept_errors on | off Enables or disables interception of FastCGI errors. When enabled, Nginx will handle error pages returned by the FastCGI application instead of passing them through to the client.

Example: Enabling FastCGI Error Interception

location ~ \.php$ {
    fastcgi_pass   127.0.0.1:9000;
    fastcgi_index  index.php;
    fastcgi_intercept_errors on;
    fastcgi_param  SCRIPT_FILENAME $document_root$fastcgi_script_name;
}
Note: When fastcgi_intercept_errors is set to on, Nginx will use the configured error pages (e.g., error_page) to display custom error responses.

Was this article helpful?

Related Cheat Sheets