Директивы модуля ngx_http_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;
}

Директивы

syntax: fastcgi_buffer_size размер
default: fastcgi_buffer_size 4k/8k
context: http, server, location

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

syntax: fastcgi_buffers число размер
default: fastcgi_buffers 8 4k/8k
context: http, server, location

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

syntax: fastcgi_cache [зона|off]
default: off
context: http, server, location

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

syntax: fastcgi_cache_key строка
default: нет
context: http, server, location

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

 
fastcgi_cache_key  localhost:9000$request_uri;

syntax: fastcgi_cache_path путь [levels=уровни] keys_zone=название:размер [inactive=время] [max_size=размер]
default: нет
context: http

Директива задаёт путь и другие параметры кэша. Данные кэша хранятся в файлах. Ключом и именем файла в кэше является результат функции 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, и при превышении его размеров удаляет самые невостребованные данные.

syntax: fastcgi_cache_min_uses число
default: fastcgi_cache_min_uses 1
context: http, server, location

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

syntax: fastcgi_cache_valid ответ [ответ ...] время
default: нет
context: http, server, location

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

 
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;

syntax: fastcgi_connect_timeout время
default: fastcgi_connect_timeout 60
context: http, server, location

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

syntax: fastcgi_index имя
default: нет
context: http, server, location

Директива задаёт имя файла, который при создании переменной $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".

syntax: fastcgi_hide_header имя
context: http, server, location

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

syntax: fastcgi_ignore_client_abort [on|off]
default: fastcgi_ignore_client_abort off
context: http, server, location

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

syntax: fastcgi_ignore_headers имя [имя ...]
context: http, server, location

Директива fastcgi_ignore_headers запрещает обработку некоторых строк заголовка из ответа FastCGI-сервера. В директиве можно указать строки "X-Accel-Redirect", "X-Accel-Expires", "Expires" и "Cache-Control".

syntax: fastcgi_intercept_errors on|off
default: fastcgi_intercept_errors off
context: http, server, location

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

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

error — произшла ошибка соединения с сервером, передачи ему запроса или чтения заголовка ответа сервера;
timeout — произошёл таймаут во время соединения с сервером, передачи ему запроса или чтения заголовка ответа сервера;
invalid_header — сервер вернул пустой или неверный ответ;
http_500 — сервер вернул ответ с кодом 500;
http_503 — сервер вернул ответ с кодом 503;
http_404 — сервер вернул ответ с кодом 404;
off — запрещает передачу запроса следующему серверу;

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

syntax: fastcgi_param параметр значение
default: нет
context: http, server, location

Директива задаёт параметр, который будут передаваться 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;

syntax: fastcgi_pass fastcgi-server
default: нет
context: location, if в location

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

    fastcgi_pass   localhost:9000;

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

    fastcgi_pass   unix:/tmp/fastcgi.socket;

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

syntax: fastcgi_pass_header имя
context: http, server, location

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

syntax: fastcgi_read_timeout время
default: fastcgi_read_timeout 60
context: http, server, location

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

syntax: fastcgi_redirect_errors on|off

Директива переименована в fastcgi_intercept_errors.

syntax: fastcgi_send_timeout время
default: fastcgi_send_timeout 60
context: http, server, location

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

syntax: fastcgi_split_path_info regex
default: нет
context: location

Директива задаёт регулярное выражение, выделяющее значение для переменной $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".

syntax: fastcgi_store on | off | строка
default: fastcgi_store off
context: http, server, location

Директива разрешает сохранение на диск файлов. Параметр "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/;
}

syntax: fastcgi_store_access пользователи:права [пользователи:права] ...
default: fastcgi_store_access user:rw
context: http, server, location

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

fastcgi_store_access  user:rw  group:rw  all:r;

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

fastcgi_store_access  group:rw  all:r;

syntax: fastcgi_temp_path путь [ уровень1 [ уровень2 [ уровень3 ] ] ]
default: fastcgi_temp_path fastcgi_temp
context: http, server, location

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

fastcgi_temp_path  /spool/nginx/fastcgi_temp 1 2;

имя временного будет такого вида:

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

Параметры, передаваемые FastCGI-серверу

Строки заголовка 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.

ПерсональныйсайтИгоряСысоева