Модуль ngx_http_fastcgi_module позволяет передавать запросы FastCGI-серверу.

location / {
    fastcgi_pass  localhost:9000;
    fastcgi_index index.php;

    fastcgi_param SCRIPT_FILENAME /home/www/scripts/php$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_buffer_size 4k|8k;

Задаёт размер буфера, в который будет читаться первая часть ответа, получаемого от FastCGI-сервера. В этой части ответа находится, как правило, небольшой заголовок ответа. По умолчанию размер буфера равен размеру одного буфера в директиве fastcgi_buffers, однако его можно сделать меньше.

fastcgi_buffers 8 4k|8k;

Задаёт число и размер буферов для одного соединения, в которые будет читаться ответ, получаемый от FastCGI-сервера. По умолчанию размер одного буфера равен размеру страницы. В зависимости от платформы это или 4K, или 8K.

fastcgi_cache off;

Задаёт зону для кэширования. Одна и та же зона может использоваться в нескольких местах. Параметр off запрещает кэширование, унаследованное с предыдущего уровня конфигурации.

Задаёт условия, при которых ответ не будет браться из кэша. Если значение хотя бы одного из строковых параметров непустое и не равно “0”, то ответ не берётся из кэша:

fastcgi_cache_bypass $cookie_nocache $arg_nocache$arg_comment;
fastcgi_cache_bypass $http_pragma    $http_authorization;

Можно использовать совместно с директивой fastcgi_no_cache.

Задаёт ключ для кэширования, например,

fastcgi_cache_key localhost:9000$request_uri;

fastcgi_cache_lock off;

Если включено, одновременно только одному запросу будет позволено заполнить новый элемент кэша, идентифицируемый согласно директиве fastcgi_cache_key, передав запрос на FastCGI-сервер. Остальные запросы этого же элемента будут либо ожидать появления ответа в кэше, либо освобождения блокировки этого элемента, в течение времени, заданного директивой fastcgi_cache_lock_timeout.

fastcgi_cache_lock_timeout 5s;

Задаёт таймаут для fastcgi_cache_lock.

fastcgi_cache_min_uses 1;

Задаёт число запросов, после которого ответ будет закэширован.

Задаёт путь и другие параметры кэша. Данные кэша хранятся в файлах. Ключом и именем файла в кэше является результат функции MD5 от проксированного URL. Параметр levels задаёт уровни иерархии кэша, например, при использовании

fastcgi_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m;

имена файлов в кэше будут такого вида:

/data/nginx/cache/c/29/b7f54b2df7773722d382f4809d65029c

Кэшируемый ответ сначала записывается во временный файл, а потом этот файл переименовывается. Начиная с версии 0.8.9, временные файлы и кэш могут располагаться на разных файловых системах, но нужно учитывать, что в этом случае вместо дешёвой операции переименовывания в пределах одной файловой системы файл копируется с одной файловой системы на другую. Поэтому лучше, если кэш будет находиться на той же файловой системе, что и каталог с временными файлами, задаваемый директивой fastcgi_temp_path для данного location.

Кроме того, все активные ключи и информация о данных хранятся в разделяемой памяти — зоне, имя и размер которой задаются параметром keys_zone. Если к данным кэша не обращаются в течение времени, заданного параметром inactive, то данные удаляются, независимо от их свежести. По умолчанию inactive равен 10 минутам.

Специальный процесс “cache manager” следит за максимальным размером кэша, заданным параметром max_size, и при превышении его размеров удаляет самые невостребованные данные.

fastcgi_cache_use_stale off;

Определяет, в каких случаях можно использовать устаревший закэшированный ответ, если при работе с FastCGI-сервером возникла ошибка. Параметры директивы совпадают с параметрами директивы fastcgi_next_upstream. Кроме того, дополнительный параметр updating разрешает использовать устаревший закэшированный ответ, если на данный момент он уже обновляется.

Задаёт время кэширования для разных кодов ответа. Например, директивы

fastcgi_cache_valid 200 302 10m;
fastcgi_cache_valid 404      1m;

задают время кэширования 10 минут для ответов с кодами 200 и 302, и 1 минуту для ответов с кодом 404.

Если указано только время кэширования,

fastcgi_cache_valid 5m;

то кэшируются только ответы 200, 301 и 302.

Кроме того, можно кэшировать любые ответы с помощью параметра any:

fastcgi_cache_valid 200 302 10m;
fastcgi_cache_valid 301      1h;
fastcgi_cache_valid any      1m;

fastcgi_connect_timeout 60s;

Задаёт таймаут для установления соединения с FastCGI-сервером. Необходимо иметь в виду, что этот таймаут обычно не может превышать 75 секунд.

По умолчанию nginx не передаёт клиенту поля заголовка “Status” и “X-Accel-...” из ответа FastCGI-сервера. Директива fastcgi_hide_header задаёт дополнительные поля, которые не будут передаваться. Если же передачу полей нужно разрешить, можно воспользоваться директивой fastcgi_pass_header.

fastcgi_ignore_client_abort off;

Определяет, закрывать ли соединение с FastCGI-сервером в случае, если клиент закрыл соединение, не дождавшись ответа.

Запрещает обработку некоторых полей заголовка из ответа FastCGI-сервера. В директиве можно указать поля “X-Accel-Redirect”, “X-Accel-Expires”, “X-Accel-Limit-Rate” (1.1.6), “X-Accel-Buffering” (1.1.6), “X-Accel-Charset” (1.1.6), “Expires”, “Cache-Control” и “Set-Cookie” (0.8.44).

Задаёт имя файла, который при создании переменной $fastcgi_script_name будет добавляться после URI, если URI заканчивается слэшом. Например, при таких настройках

fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name;

и запросе “/page.php” параметр SCRIPT_FILENAME будет равен “/home/www/scripts/php/page.php”, а при запросе “/” - “/home/www/scripts/php/index.php”.

fastcgi_intercept_errors off;

Определяет, передавать ли клиенту ответы FastCGI-сервера с кодом больше либо равным 400, или же перенаправлять их на обработку nginx'у с помощью директивы error_page.

fastcgi_keep_conn off;

По умолчанию FastCGI-сервер будет закрывать соединение сразу же после отправки ответа. При установке значения on nginx указывает FastCGI-серверу оставлять соединения открытыми. Это в частности требуется для функционирования постоянных соединений с FastCGI-серверами.

fastcgi_next_upstream error timeout;

Определяет, в каких случаях запрос будет передан следующему серверу:

error

произошла ошибка соединения с сервером, передачи ему запроса или чтения заголовка ответа сервера;

timeout

произошёл таймаут во время соединения с сервером, передачи ему запроса или чтения заголовка ответа сервера;

invalid_header

сервер вернул пустой или неверный ответ;

http_500

сервер вернул ответ с кодом 500;

http_503

сервер вернул ответ с кодом 503;

http_404

сервер вернул ответ с кодом 404;

off

запрещает передачу запроса следующему серверу.

Необходимо понимать, что передача запроса следующему серверу возможна только при условии, что клиенту ещё ничего не передавалось. То есть, если ошибка или таймаут возникли в середине передачи ответа, то исправить это уже невозможно.

Задаёт условия, при которых ответ не будет сохраняться в кэш. Если значение хотя бы одного из строковых параметров непустое и не равно “0”, то ответ не будет сохранён:

fastcgi_no_cache $cookie_nocache $arg_nocache$arg_comment;
fastcgi_no_cache $http_pragma    $http_authorization;

Можно использовать совместно с директивой fastcgi_cache_bypass.

Задаёт параметр, который будет передаваться FastCGI-серверу. В качестве значения можно использовать текст, переменные и их комбинации. Директивы наследуются с предыдущего уровня при условии, что на данном уровне не описаны свои директивы fastcgi_param.

Ниже приведён пример минимально необходимых параметров для PHP:

fastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name;
fastcgi_param QUERY_STRING    $query_string;

Параметр SCRIPT_FILENAME используется в PHP для определения имени скрипта, а в параметре QUERY_STRING передаются параметры запроса.

Если скрипты обрабатывают запросы POST, то нужны ещё три параметра:

fastcgi_param REQUEST_METHOD  $request_method;
fastcgi_param CONTENT_TYPE    $content_type;
fastcgi_param CONTENT_LENGTH  $content_length;

Если PHP был собран с параметром конфигурации --enable-force-cgi-redirect, то нужно передавать параметр REDIRECT_STATUS со значением “200”:

fastcgi_param REDIRECT_STATUS 200;

Если директива указана с if_not_empty (1.1.11), то такой параметр с пустым значением передаваться на сервер не будет:

fastcgi_param HTTPS           $https if_not_empty;

Задаёт адрес FastCGI-сервера. Адрес может быть указан в виде доменного имени или адреса, и порта, например,

fastcgi_pass localhost:9000;

или в виде пути UNIX-сокета:

fastcgi_pass unix:/tmp/fastcgi.socket;

Если доменному имени соответствует несколько адресов, то все они будут использоваться по очереди (round-robin). И, кроме того, адрес может быть группой серверов.

Разрешает передавать от FastCGI-сервера клиенту запрещённые для передачи поля заголовка.

fastcgi_read_timeout 60s;

Задаёт таймаут при чтении ответа FastCGI-сервера. Таймаут устанавливается не на всю передачу ответа, а только между двумя операциями чтения. Если по истечении этого времени FastCGI-сервер ничего не передаст, соединение закрывается.

fastcgi_send_timeout 60s;

Задаёт таймаут при передаче запроса FastCGI-серверу. Таймаут устанавливается не на всю передачу запроса, а только между двумя операциями записи. Если по истечении этого времени FastCGI-сервер не примет новых данных, соединение закрывается.

Задаёт регулярное выражение, выделяющее значение для переменной $fastcgi_path_info. Регулярное выражение должно иметь два выделения, из которых первое становится значением переменной $fastcgi_script_name, а второе - значением переменной $fastcgi_path_info. Например, при таких настройках

location ~ ^(.+\.php)(.*)$ {
    fastcgi_split_path_info       ^(.+\.php)(.*)$;
    fastcgi_param SCRIPT_FILENAME /path/to/php$fastcgi_script_name;
    fastcgi_param PATH_INFO       $fastcgi_path_info;

и запросе “/show.php/article/0001” параметр SCRIPT_FILENAME будет равен “/path/to/php/show.php”, а параметр PATH_INFO - “/article/0001”.

fastcgi_store off;

Разрешает сохранение на диск файлов. Параметр on сохраняет файлы в соответствии с путями, указанными в директивах alias или root. Параметр off запрещает сохранение файлов. Кроме того, имя файла можно задать явно с помощью строки с переменными:

fastcgi_store /data/www$original_uri;

Время изменения файлов выставляется согласно полученному полю “Last-Modified” в заголовке ответа. Ответ сначала записывается во временный файл, а потом этот файл переименовывается. Начиная с версии 0.8.9, временный файл и постоянное место хранения ответа могут располагаться на разных файловых системах, но нужно учитывать, что в этом случае вместо дешёвой операции переименовывания в пределах одной файловой системы файл копируется с одной файловой системы на другую. Поэтому лучше, если сохраняемые файлы будут находиться на той же файловой системе, что и каталог с временными файлами, задаваемый директивой fastcgi_temp_path для данного location.

Директиву можно использовать для создания локальных копий статических неизменяемых файлов, например, так:

location /images/ {
    root                   /data/www;
    open_file_cache_errors off;
    error_page             404 = /fetch$uri;
}

location /fetch/ {
    internal;

    fastcgi_pass         backend:9000;
    ...

    fastcgi_store        on;
    fastcgi_store_access user:rw group:rw all:r;
    fastcgi_temp_path    /data/temp;

    alias                /data/www/;
}

fastcgi_store_access user:rw;

Задаёт права доступа для создаваемых файлов и каталогов, например,

fastcgi_store_access user:rw group:rw all:r;

Если заданы какие-либо права для group или all, то права для user указывать необязательно:

fastcgi_store_access group:rw all:r;

fastcgi_temp_path fastcgi_temp;

Задаёт имя каталога для хранения временных файлов, полученных от другого сервера. В каталоге может использоваться иерархия подкаталогов до трёх уровней. Например, при такой конфигурации

fastcgi_temp_path /spool/nginx/fastcgi_temp 1 2;

временный файл будет следующего вида:

/spool/nginx/fastcgi_temp/7/45/00000123457

Поля заголовка HTTP-запроса передаются FastCGI-серверу в виде параметров. В приложениях и скриптах, запущенных в виде FastCGI-сервера, эти параметры обычно доступны в виде переменных среды. Например, поле заголовка “User-Agent” передаётся как параметр HTTP_USER_AGENT. Кроме полей заголовка HTTP-запроса можно передавать произвольные параметры с помощью директивы fastcgi_param.

В модуле ngx_http_fastcgi_module есть встроенные переменные, которые можно использовать для формирования параметров с помощью директивы fastcgi_param:

$fastcgi_script_name

URI запроса или же, если URI заканчивается слэшом, то URI запроса, дополненное именем индексного файла, задаваемого директивой fastcgi_index. Эту переменную можно использовать для задания параметров SCRIPT_FILENAME и PATH_TRANSLATED, используемых, в частности, для определения имени скрипта в PHP. Например, для запроса “/info/” и при использовании директив

fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name;

параметр SCRIPT_FILENAME будет равен “/home/www/scripts/php/info/index.php”.

При использовании директивы fastcgi_split_path_info переменная $fastcgi_script_name равна значению первого выделения, задаваемого этой директивой.

$fastcgi_path_info

значение второго выделения, задаваемого директивой fastcgi_split_path_info. Эту переменную можно использовать для задания параметра PATH_INFO.