Модуль ngx_http_scgi_module

• Пример конфигурации
• Директивы
• scgi_bind
• scgi_buffer_size
• scgi_buffering
• scgi_buffers
• scgi_busy_buffers_size
• scgi_cache
• scgi_cache_background_update
• scgi_cache_bypass
• scgi_cache_key
• scgi_cache_lock
• scgi_cache_lock_age
• scgi_cache_lock_timeout
• scgi_cache_max_range_offset
• scgi_cache_methods
• scgi_cache_min_uses
• scgi_cache_path
• scgi_cache_purge
• scgi_cache_revalidate
• scgi_cache_use_stale
• scgi_cache_valid
• scgi_connect_timeout
• scgi_force_ranges
• scgi_hide_header
• scgi_ignore_client_abort
• scgi_ignore_headers
• scgi_intercept_errors
• scgi_limit_rate
• scgi_max_temp_file_size
• scgi_next_upstream
• scgi_next_upstream_timeout
• scgi_next_upstream_tries
• scgi_no_cache
• scgi_param
• scgi_pass
• scgi_pass_header
• scgi_pass_request_body
• scgi_pass_request_headers
• scgi_read_timeout
• scgi_request_buffering
• scgi_send_timeout
• scgi_socket_keepalive
• scgi_store
• scgi_store_access
• scgi_temp_file_write_size
• scgi_temp_path

Модуль ngx_http_scgi_module позволяет передавать запросы на сервер SCGI.

Пример конфигурации

location / {
    include   scgi_params;
    scgi_pass localhost:9000;
}

Директивы

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

Параметр transparent (1.11.0) позволяет устанавливать исходящие соединения к серверу SCGI с нелокального IP-адреса, например, с реального IP-адреса клиента:

scgi_bind $remote_addr transparent;

Для работы этого параметра обычно требуется запускать процессы nginx с правами суперпользователя. На Linux это не обязательно (1.13.8), так как если указан параметр transparent, процессы worker наследуют возможность CAP_NET_RAW от master-процесса. Также необходимо настроить таблицу маршрутизации ядра для перехвата сетевого трафика от сервера SCGI.

Устанавливает размер буфера для чтения первой части ответа, полученного от сервера SCGI. Эта часть обычно содержит небольшой заголовок ответа. По умолчанию размер буфера равен одной странице памяти. Это либо 4К, либо 8К в зависимости от платформы. Его можно сделать меньше.

Включает или выключает буферизацию ответов от сервера SCGI.

При включенной буферизации nginx получает ответ от сервера SCGI как можно скорее, сохраняя его в буферы, заданные директивами scgi_buffer_size и scgi_buffers. Если весь ответ не помещается в память, часть его может быть сохранена во временный файл на диске. Запись во временные файлы контролируется директивами scgi_max_temp_file_size и scgi_temp_file_write_size.

При выключенной буферизации ответ передаётся клиенту синхронно, сразу по мере его получения. nginx не будет пытаться прочитать весь ответ от сервера SCGI. Максимальный размер данных, которые nginx может получить от сервера за раз, устанавливается директивой scgi_buffer_size.

Буферизация также может быть включена или выключена путём передачи «yes» или «no» в поле заголовка ответа «X-Accel-Buffering». Эта возможность может быть отключена с помощью директивы scgi_ignore_headers.

Устанавливает количество и размер буферов для чтения ответа от сервера SCGI для одного соединения. По умолчанию размер буфера равен одной странице памяти. Это либо 4К, либо 8К в зависимости от платформы.

При включенной буферизации ответов от сервера SCGI ограничивает общее количество занятых буферов, которые могут быть заняты отправкой ответа клиенту, пока ответ ещё не полностью прочитан. В это время остальные буферы могут быть использованы для чтения ответа и, при необходимости, буферизации части ответа во временный файл. По умолчанию size ограничен размером двух буферов, заданных директивами scgi_buffer_size и scgi_buffers.

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

Разрешает запуск фонового подзапроса для обновления истекшего элемента кэша, в то время как клиенту возвращается устаревший кэшированный ответ. Обратите внимание, что необходимо разрешить использование устаревшего кэшированного ответа во время его обновления.

Определяет условия, при которых ответ не будет взят из кэша. Если хотя бы одно значение строковых параметров не пустое и не равно «0», то ответ не будет взят из кэша:

scgi_cache_bypass $cookie_nocache $arg_nocache$arg_comment;
scgi_cache_bypass $http_pragma    $http_authorization;

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

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

scgi_cache_key localhost:9000$request_uri;

При включении, только один запрос за раз будет разрешён для заполнения нового элемента кэша, определённого согласно директиве scgi_cache_key, передавая запрос на сервер SCGI. Другие запросы к этому элементу кэша будут либо ожидать появления ответа в кэше, либо освобождения блокировки кэша для этого элемента, до истечения времени, заданного директивой scgi_cache_lock_timeout.

Если последний запрос к серверу SCGI для заполнения нового элемента кэша не завершился за указанное time, может быть отправлен ещё один запрос к серверу SCGI.

Устанавливает таймаут для scgi_cache_lock. Когда таймаут time истекает, запрос отправляется на сервер SCGI, но ответ не кэшируется.

До версии 1.7.8 ответ мог кэшироваться.

Устанавливает смещение в байтах для запросов с указанием диапазона (byte-range). Если диапазон выходит за пределы смещения, запрос с указанием диапазона будет отправлен на сервер SCGI, и ответ не будет кэширован.

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

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

Устанавливает путь и другие параметры кэша. Данные кэша хранятся в файлах. Имя файла в кэше получается путём применения функции MD5 к ключа кэша. Параметр levels определяет уровни иерархии кэша: от 1 до 3, каждый уровень принимает значения 1 или 2. Например, в следующей конфигурации

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

имена файлов в кэше будут выглядеть следующим образом:

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

Кэшированный ответ сначала записывается во временный файл, а затем файл переименовывается. Начиная с версии 0.8.9, временные файлы и кэш могут быть размещены на разных файловых системах. Однако следует учитывать, что в этом случае файл копируется между двумя файловыми системами вместо операции переименования. Поэтому рекомендуется, чтобы для заданного местоположения кэш и каталог с временными файлами находились на одной файловой системе. Каталог для временных файлов настраивается параметром use_temp_path (1.7.10). Если этот параметр опущен или имеет значение on, будет использоваться каталог, заданный директивой scgi_temp_path для данного расположения. Если значение установлено на off, временные файлы будут размещены непосредственно в каталоге кэша.

Кроме того, все активные ключи и информация о данных хранятся в области общей памяти, размер которой name и size настраиваются параметром keys_zone. Одна мегабайтовая область может хранить около 8 тысяч ключей.

В рамках коммерческой подписки область общей памяти также хранит расширенную информацию о кэше ngx_http_api_module, поэтому для одинакового количества ключей необходимо указать больший размер области. Например, одна мегабайтовая область может хранить около 4 тысяч ключей.

Данные кэша, которые не обращаются в течение времени, указанного параметром inactive, удаляются из кэша независимо от их актуальности. По умолчанию inactive устанавливается в 10 минут.

Специальный процесс «менеджер кэша» отслеживает максимальный размер кэша, установленный параметром max_size, и минимальное количество свободного места, установленное параметром min_free (1.19.1) на файловой системе с кэшем. При превышении размера или недостатке свободного места он удаляет наименее недавно использованные данные. Данные удаляются итерациями, настраиваемыми параметрами manager_files, manager_threshold, и manager_sleep (1.11.5). За одну итерацию удаляется не более manager_files элементов (по умолчанию 100). Продолжительность одной итерации ограничена параметром manager_threshold (по умолчанию 200 миллисекунд). Между итерациями делается пауза, настраиваемая параметром manager_sleep (по умолчанию 50 миллисекунд).

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

Кроме того, доступны следующие параметры в рамках нашей коммерческой подписки:

purger=on|off

Указывает, будут ли записи кэша, соответствующие ключу с подстановкой, удаляться с диска процессом очистки кэша (1.7.12). Установка параметра в on (по умолчанию off) активирует процесс «очистки кэша», который постоянно итерирует по всем записям кэша и удаляет записи, соответствующие ключу с подстановкой.

purger_files=number

Устанавливает количество элементов, которые будут сканироваться за одну итерацию (1.7.12). По умолчанию purger_files устанавливается в 10.

purger_threshold=number

Устанавливает продолжительность одной итерации (1.7.12). По умолчанию purger_threshold устанавливается в 50 миллисекунд.

purger_sleep=number

Устанавливает паузу между итерациями (1.7.12). По умолчанию purger_sleep устанавливается в 50 миллисекунд.

В версиях 1.7.3, 1.7.7 и 1.11.10 формат заголовка кэша изменен. Ранее кэшированные ответы будут считаться недействительными после обновления до более новой версии nginx.

Определяет условия, при которых запрос будет рассматриваться как запрос очистки кэша. Если хотя бы одно значение строковых параметров не пустое и не равно “0”, то запись кэша с соответствующим ключом кэша удаляется. Результат успешной операции отображается возвращением ответа 204 (No Content).

Если ключ кэша запроса очистки заканчивается звездочкой (“*”), все записи кэша, соответствующие ключу с подстановкой, будут удалены из кэша. Однако эти записи останутся на диске до тех пор, пока они не будут удалены из-за неактивности, или обработаны процессом очистки кэша (1.7.12), или клиент не попытается получить доступ к ним.

Пример конфигурации:

scgi_cache_path /data/nginx/cache keys_zone=cache_zone:10m;

map $request_method $purge_method {
    PURGE   1;
    default 0;
}

server {
    ...
    location / {
        scgi_pass        backend;
        scgi_cache       cache_zone;
        scgi_cache_key   $uri;
        scgi_cache_purge $purge_method;
    }
}

Эта функциональность доступна в рамках нашей коммерческой подписки.

Включает повторную проверку просроченных элементов кэша с помощью условных запросов с заголовками «If-Modified-Since» и «If-None-Match».

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

Параметр error также разрешает использование устаревшего кэшированного ответа, если сервер SCGI для обработки запроса не может быть выбран.

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

Использование устаревшего кэшированного ответа также может быть включено непосредственно в заголовке ответа на определённое количество секунд после того, как ответ стал устаревшим (1.11.10). Это имеет меньший приоритет, чем использование параметров директивы.

• Расширение «stale-while-revalidate» поля заголовка «Cache-Control» позволяет использовать устаревший кэшированный ответ, если он в настоящее время обновляется.
• Расширение «stale-if-error» поля заголовка «Cache-Control» позволяет использовать устаревший кэшированный ответ в случае ошибки.

Для минимизации числа обращений к серверам SCGI при заполнении нового элемента кэша можно использовать директиву scgi_cache_lock.

Устанавливает время кэширования для различных кодов ответов. Например, следующие директивы

scgi_cache_valid 200 302 10m;
scgi_cache_valid 404      1m;

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

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

scgi_cache_valid 5m;

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

Кроме того, параметр any может быть указан для кэширования любых ответов:

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

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

• Поле заголовка «X-Accel-Expires» устанавливает время кэширования ответа в секундах. Значение нуль отключает кэширование для ответа. Если значение начинается с префикса @, оно устанавливает абсолютное время в секундах с эпохи, до которого ответ может быть кэширован.
• Если заголовок не содержит поля «X-Accel-Expires», параметры кэширования могут быть заданы в полях заголовка «Expires» или «Cache-Control».
• Если заголовок содержит поле «Set-Cookie», такой ответ не будет кэширован.
• Если заголовок содержит поле «Vary» со специальным значением «*», такой ответ не будет кэширован (1.7.7). Если заголовок содержит поле «Vary» с другим значением, такой ответ будет кэширован с учетом соответствующих полей заголовка запроса (1.7.7).

Обработку одного или нескольких из этих полей заголовка ответа можно отключить с помощью директивы scgi_ignore_headers.

Определяет таймаут для установления соединения с сервером SCGI. Следует отметить, что этот таймаут обычно не может превышать 75 секунд.

Включает поддержку байтовых диапазонов для кэшированных и некэшированных ответов от сервера SCGI независимо от поля «Accept-Ranges» в этих ответах.

По умолчанию nginx не передает поля заголовков «Status» и «X-Accel-...» из ответа сервера SCGI клиенту. Директива scgi_hide_header устанавливает дополнительные поля, которые не будут переданы. Если, наоборот, передача полей должна быть разрешена, можно использовать директиву scgi_pass_header.

Определяет, должно ли соединение с сервером SCGI закрываться, когда клиент закрывает соединение, не дожидаясь ответа.

Отключает обработку определённых полей заголовка ответа от сервера SCGI. Могут быть проигнорированы следующие поля: «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) и «Vary» (1.7.7).

Если не отключено, обработка этих полей заголовка имеет следующий эффект:

• «X-Accel-Expires», «Expires», «Cache-Control», «Set-Cookie» и «Vary» устанавливают параметры кэширования ответа caching;
• «X-Accel-Redirect» выполняет внутренний перенаправление на указанный URI;
• «X-Accel-Limit-Rate» устанавливает предел скорости передачи ответа клиенту;
• «X-Accel-Buffering» включает или отключает буферизацию ответа;
• «X-Accel-Charset» устанавливает желаемый кодировку ответа.

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

Ограничивает скорость чтения ответа от сервера SCGI. rate указывается в байтах в секунду. Значение ноль отключает ограничение скорости. Ограничение устанавливается на запрос, поэтому, если nginx одновременно открывает два подключения к серверу SCGI, общая скорость будет вдвое больше заданного предела. Ограничение работает только при включённой буферизации ответов от сервера SCGI. Значение параметра может содержать переменные (1.27.0).

Когда буферизация ответов от сервера SCGI включена, а весь ответ не помещается в буферы, заданные директивами scgi_buffer_size и scgi_buffers, часть ответа может быть сохранена во временный файл. Эта директива устанавливает максимальный size временного файла. Размер данных, записываемых во временный файл за раз, устанавливается директивой scgi_temp_file_write_size.

Нулевое значение отключает буферизацию ответов во временные файлы.

Это ограничение не применяется к ответам, которые будут кэшированы или сохранены на диске.

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

error

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

timeout

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

invalid_header

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

http_500

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

http_503

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

http_403

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

http_404

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

http_429

сервер вернул ответ с кодом 429 (1.11.13);

non_idempotent

обычно запросы с неидемпотентным методом (POST, LOCK, PATCH) не передаются следующему серверу, если запрос уже был отправлен на сервер верхнего уровня (1.9.13); включение этого параметра явно позволяет повторно отправлять такие запросы;

off

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

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

Директива также определяет, что считается неудачной попыткой связи с сервером. Случаи error, timeout и invalid_header всегда считаются неудачными попытками, даже если они не указаны в директиве. Случаи http_500, http_503, и http_429 считаются неудачными попытками только если они указаны в директиве. Случаи http_403 и http_404 никогда не считаются неудачными попытками.

Передача запроса следующему серверу может быть ограничена количеством попыток и временем.

Ограничивает время, в течение которого запрос может быть передан следующему серверу. Значение 0 отключает это ограничение.

Ограничивает количество возможных попыток передачи запроса следующему серверу. Значение 0 отключает это ограничение.

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

scgi_no_cache $cookie_nocache $arg_nocache$arg_comment;
scgi_no_cache $http_pragma    $http_authorization;

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

Устанавливает параметр, который должен быть передан серверу SCGI. Параметр может содержать текст, переменные и их комбинацию. Эти директивы наследуются с предыдущего уровня конфигурации только в том случае, если на текущем уровне не определены директивы scgi_param.

Стандартные переменные окружения CGI должны предоставляться как заголовки SCGI, см. файл scgi_params, предоставленный в дистрибутиве:

location / {
    include scgi_params;
    ...
}

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

scgi_param HTTPS $https if_not_empty;

Устанавливает адрес сервера SCGI. Адрес может быть указан как доменное имя или IP-адрес, и порт:

scgi_pass localhost:9000;

или как путь к сокету UNIX-домена:

scgi_pass unix:/tmp/scgi.socket;

Если доменное имя разрешается на несколько адресов, все они будут использоваться в циклическом порядке. Кроме того, адрес может быть указан как группа серверов.

Значение параметра может содержать переменные. В этом случае, если адрес указан как доменное имя, имя ищется среди описанных групп серверов, и, если не найдено, определяется с помощью разрешителя.

Разрешает передачу иначе отключенных полей заголовка с сервера SCGI клиенту.

Указывает, передаётся ли исходное тело запроса серверу SCGI. Смотрите также директиву scgi_pass_request_headers.

Указывает, передаются ли поля заголовков исходного запроса серверу SCGI. Смотрите также директиву scgi_pass_request_body.

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

Включает или отключает буферизацию тела запроса клиента.

При включённой буферизации всё тело запроса считывается с клиента перед отправкой запроса серверу SCGI.

При выключенной буферизации тело запроса отправляется серверу SCGI немедленно по мере получения. В этом случае запрос не может быть передан следующему серверу, если nginx уже начал отправлять тело запроса.

При использовании HTTP/1.1 кодирования с чанками для отправки исходного тела запроса, тело запроса будет буферизовано независимо от значения директивы.

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

Настраивает поведение «TCP keepalive» для исходящих соединений с сервером SCGI. По умолчанию действуют настройки операционной системы для сокета. Если директива установлена в значение “on”, опция сокета SO_KEEPALIVE включается для сокета.

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

scgi_store /data/www$original_uri;

Время изменения файлов устанавливается в соответствии с полученным полем заголовка ответа «Last-Modified». Ответ сначала записывается в временный файл, а затем файл переименовывается. Начиная с версии 0.8.9, временные файлы и постоянное хранилище могут находиться на разных файловых системах. Однако имейте в виду, что в этом случае файл копируется между двумя файловыми системами вместо быстрой операции переименования. Поэтому рекомендуется, чтобы для заданного расположения как сохранённые файлы, так и директория, содержащая временные файлы, установленная директивой scgi_temp_path, находились на одной файловой системе.

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

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

location /fetch/ {
    internal;

    scgi_pass         backend:9000;
    ...

    scgi_store        on;
    scgi_store_access user:rw group:rw all:r;
    scgi_temp_path    /data/temp;

    alias             /data/www/;
}

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

scgi_store_access user:rw group:rw all:r;

Если указаны любые разрешения доступа group или all, то разрешения user могут быть опущены:

scgi_store_access group:rw all:r;

Ограничивает size данных, записываемых во временный файл за раз, когда включена буферизация ответов с сервера SCGI во временные файлы. По умолчанию size ограничено двумя буферами, заданными директивами scgi_buffer_size и scgi_buffers. Максимальный размер временного файла устанавливается директивой scgi_max_temp_file_size.

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

scgi_temp_path /spool/nginx/scgi_temp 1 2;

временный файл может выглядеть так:

/spool/nginx/scgi_temp/7/45/00000123457

См. также параметр use_temp_path директивы scgi_cache_path.