nginx

Модуль ngx_http_fastcgi_module


english
русский

简体中文
עברית
日本語
türkçe

новости [en]
об nginx
скачать
безопасность [en]
pgp ключи [en]
документация
faq
ссылки [en]
книги [en]
поддержка
пожертвования [en]

trac
wiki
twitter
nginx.com
Пример конфигурации
Директивы
     fastcgi_bind
     fastcgi_buffer_size
     fastcgi_buffers
     fastcgi_busy_buffers_size
     fastcgi_cache
     fastcgi_cache_bypass
     fastcgi_cache_key
     fastcgi_cache_lock
     fastcgi_cache_lock_timeout
     fastcgi_cache_methods
     fastcgi_cache_min_uses
     fastcgi_cache_path
     fastcgi_cache_use_stale
     fastcgi_cache_valid
     fastcgi_connect_timeout
     fastcgi_hide_header
     fastcgi_ignore_client_abort
     fastcgi_ignore_headers
     fastcgi_index
     fastcgi_intercept_errors
     fastcgi_keep_conn
     fastcgi_max_temp_file_size
     fastcgi_next_upstream
     fastcgi_no_cache
     fastcgi_param
     fastcgi_pass
     fastcgi_pass_header
     fastcgi_read_timeout
     fastcgi_pass_request_body
     fastcgi_pass_request_headers
     fastcgi_send_lowat
     fastcgi_send_timeout
     fastcgi_split_path_info
     fastcgi_store
     fastcgi_store_access
     fastcgi_temp_file_write_size
     fastcgi_temp_path
Параметры, передаваемые FastCGI-серверу
Встроенные переменные

Модуль 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_bind адрес | off;
умолчание:
контекст: http, server, location

Эта директива появилась в версии 0.8.22.

Задаёт локальный IP-адрес, который будет использоваться в исходящих соединениях с FastCGI-сервером. В значении параметра допустимо использование переменных (1.3.12). Специальное значение off (1.3.12) отменяет действие унаследованной с предыдущего уровня конфигурации директивы fastcgi_bind, позволяя системе самостоятельно выбирать локальный адрес.

синтаксис: fastcgi_buffer_size размер;
умолчание:
fastcgi_buffer_size 4k|8k;
контекст: http, server, location

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

синтаксис: fastcgi_buffers число размер;
умолчание:
fastcgi_buffers 8 4k|8k;
контекст: http, server, location

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

синтаксис: fastcgi_busy_buffers_size размер;
умолчание:
fastcgi_busy_buffers_size 8k|16k;
контекст: http, server, location

Ограничивает суммарный размер буферов, которые могут быть заняты для отправки ответа клиенту, пока ответ ещё не прочитан целиком. Оставшиеся буферы тем временем могут использоваться для чтения ответа и, при необходимости, буферизации части ответа во временный файл. По умолчанию размер ограничен двумя буферами, заданными директивами fastcgi_buffer_size и fastcgi_buffers.

синтаксис: fastcgi_cache зона | off;
умолчание:
fastcgi_cache off;
контекст: http, server, location

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

синтаксис: fastcgi_cache_bypass строка ...;
умолчание:
контекст: http, server, location

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

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

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

синтаксис: fastcgi_cache_key строка;
умолчание:
контекст: http, server, location

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

fastcgi_cache_key localhost:9000$request_uri;

синтаксис: fastcgi_cache_lock on | off;
умолчание:
fastcgi_cache_lock off;
контекст: http, server, location

Эта директива появилась в версии 1.1.12.

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

синтаксис: fastcgi_cache_lock_timeout время;
умолчание:
fastcgi_cache_lock_timeout 5s;
контекст: http, server, location

Эта директива появилась в версии 1.1.12.

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

синтаксис: fastcgi_cache_methods GET | HEAD | POST ...;
умолчание:
fastcgi_cache_methods GET HEAD;
контекст: http, server, location

Эта директива появилась в версии 0.7.59.

Если метод запроса клиента указан в этой директиве, то ответ будет закэширован. Методы “GET” и “HEAD” всегда добавляются в список, но тем не менее рекомендуется перечислять их явно. См. также директиву fastcgi_no_cache.

синтаксис: fastcgi_cache_min_uses число;
умолчание:
fastcgi_cache_min_uses 1;
контекст: http, server, location

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

синтаксис: fastcgi_cache_path путь [levels=уровни] keys_zone=имя:размер [inactive=время] [max_size=размер] [loader_files=число] [loader_sleep=время] [loader_threshold=время];
умолчание:
контекст: 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, и при превышении его размеров удаляет наименее востребованные данные.

Через минуту после старта активируется специальный процесс “cache loader”, который загружает в зону кэша информацию о ранее закэшированных данных, хранящихся на файловой системе. Загрузка происходит итерациями. За одну итерацию загружается не более loader_files элементов (по умолчанию 100). Кроме того, время работы одной итерации ограничено параметром loader_threshold (по умолчанию 200 миллисекунд). Между итерациями делается пауза на время, заданное параметром loader_sleep (по умолчанию 50 миллисекунд).

синтаксис: fastcgi_cache_use_stale error | timeout | invalid_header | updating | http_500 | http_503 | http_404 | off ...;
умолчание:
fastcgi_cache_use_stale off;
контекст: http, server, location

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

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

Чтобы минимизировать число обращений к FastCGI-серверам при заполнении нового элемента кэша, можно воспользоваться директивой fastcgi_cache_lock.

синтаксис: fastcgi_cache_valid [код ...] время;
умолчание:
контекст: 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;

Параметры кэширования могут также быть заданы непосредственно в заголовке ответа. Такой способ приоритетнее, чем задание времени кэширования с помощью директивы. Поле заголовка “X-Accel-Expires” задаёт время кэширования ответа в секундах. Значение 0 запрещает кэшировать ответ. Если значение начинается с префикса @, оно задаёт абсолютное время в секундах с начала эпохи, до которого ответ может быть закэширован. Если в заголовке нет поля “X-Accel-Expires”, параметры кэширования определяются по полям заголовка “Expires” или “Cache-Control”. Ответ, в заголовке которого есть поле “Set-Cookie”, не будет кэшироваться. Обработка одного или более из этих полей заголовка может быть отключена при помощи директивы fastcgi_ignore_headers.

синтаксис: fastcgi_connect_timeout время;
умолчание:
fastcgi_connect_timeout 60s;
контекст: http, server, location

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

синтаксис: fastcgi_hide_header поле;
умолчание:
контекст: http, server, location

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

синтаксис: fastcgi_ignore_client_abort on | off;
умолчание:
fastcgi_ignore_client_abort off;
контекст: http, server, location

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

синтаксис: fastcgi_ignore_headers поле ...;
умолчание:
контекст: http, server, location

Запрещает обработку некоторых полей заголовка из ответа 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_index имя;
умолчание:
контекст: 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”.

синтаксис: fastcgi_intercept_errors on | off;
умолчание:
fastcgi_intercept_errors off;
контекст: http, server, location

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

синтаксис: fastcgi_keep_conn on | off;
умолчание:
fastcgi_keep_conn off;
контекст: http, server, location

Эта директива появилась в версии 1.1.4.

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

синтаксис: fastcgi_max_temp_file_size размер;
умолчание:
fastcgi_max_temp_file_size 1024m;
контекст: http, server, location

Если ответ не вмещается целиком в буферы памяти, заданные директивами fastcgi_buffer_size и fastcgi_buffers, часть ответа может быть записана во временный файл. Эта директива задаёт максимальный размер временного файла. Размер данных, сбрасываемых во временный файл за один раз, задаётся директивой fastcgi_temp_file_write_size.

Значение 0 отключает возможность буферизации ответов во временные файлы.

синтаксис: fastcgi_next_upstream error | timeout | invalid_header | http_500 | http_503 | http_404 | off ...;
умолчание:
fastcgi_next_upstream error timeout;
контекст: http, server, location

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

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

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

синтаксис: fastcgi_no_cache строка ...;
умолчание:
контекст: http, server, location

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

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

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

синтаксис: fastcgi_param параметр значение [if_not_empty];
умолчание:
контекст: 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;

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

fastcgi_param HTTPS           $https if_not_empty;

синтаксис: fastcgi_pass адрес;
умолчание:
контекст: location, if в location

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

fastcgi_pass localhost:9000;

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

fastcgi_pass unix:/tmp/fastcgi.socket;

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

синтаксис: fastcgi_pass_header поле;
умолчание:
контекст: http, server, location

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

синтаксис: fastcgi_read_timeout время;
умолчание:
fastcgi_read_timeout 60s;
контекст: http, server, location

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

синтаксис: fastcgi_pass_request_body on | off;
умолчание:
fastcgi_pass_request_body on;
контекст: http, server, location

Если запрещено, то исходное тело запроса не будет передано на FastCGI-сервер. См. также директиву fastcgi_pass_request_headers.

синтаксис: fastcgi_pass_request_headers on | off;
умолчание:
fastcgi_pass_request_headers on;
контекст: http, server, location

Если запрещено, то поля заголовка исходного запроса не будут переданы на FastCGI-сервер. См. также директивы fastcgi_pass_request_body.

синтаксис: fastcgi_send_lowat размер;
умолчание:
fastcgi_send_lowat 0;
контекст: http, server, location

При установке в ненулевое значение nginx будет пытаться минимизировать число операций отправки на исходящих соединениях с FastCGI-сервером либо при помощи флага NOTE_LOWAT метода kqueue, либо при помощи параметра сокета SO_SNDLOWAT, с указанным размером.

Эта директива игнорируется на Linux, Solaris и Windows.

синтаксис: fastcgi_send_timeout время;
умолчание:
fastcgi_send_timeout 60s;
контекст: http, server, location

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

синтаксис: fastcgi_split_path_info regex;
умолчание:
контекст: 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”.

синтаксис: fastcgi_store on | off | строка;
умолчание:
fastcgi_store off;
контекст: 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/;
}

синтаксис: fastcgi_store_access пользователи:права ...;
умолчание:
fastcgi_store_access user:rw;
контекст: http, server, location

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

fastcgi_store_access user:rw group:rw all:r;

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

fastcgi_store_access group:rw all:r;

синтаксис: fastcgi_temp_file_write_size размер;
умолчание:
fastcgi_temp_file_write_size 8k|16k;
контекст: http, server, location

Ограничивает размер данных, сбрасываемых во временный файл за один раз, при включённой буферизации ответов FastCGI-сервера во временные файлы. По умолчанию размер ограничен двумя буферами, заданными директивами fastcgi_buffer_size и fastcgi_buffers. Максимальный размер временного файла задаётся директивой fastcgi_max_temp_file_size.

синтаксис: fastcgi_temp_path путь [уровень1 [уровень2 [уровень3]]];
умолчание:
fastcgi_temp_path fastcgi_temp;
контекст: http, server, location

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

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.