Модуль ngx_http_scgi_module

• Пример конфигурации
• Директивы
• scgi_allow_upstream
• scgi_bind
• scgi_bind_dynamic
• 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_request_dynamic
• 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;
}

Директивы

Определяет условия, при которых доступ к SCGI-серверу разрешён или запрещён. Если все строковые параметры не пусты и не равны «0», доступ разрешён. Условия проверяются каждый раз перед установлением соединения с SCGI-сервером. Значения параметров могут содержать переменные:

geo $upstream_last_addr $allow {
    volatile;
    10.10.0.0/24        1;
}

server {
    listen 127.0.0.1:8080;

    location / {
        scgi_pass           localhost:9000;
        scgi_allow_upstream $allow;
        ...
    }
}

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

Заставляет исходящие соединения с SCGI-сервером использовать указанный локальный IP-адрес и, при необходимости, порт (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 рабочие процессы наследуют возможность CAP_NET_RAW от главного процесса. Также необходимо настроить таблицу маршрутизации ядра для перехвата сетевого трафика от SCGI-сервера.

При включении директива bind выполняется при каждой попытке установить соединение.

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

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

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

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

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

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

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

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

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

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

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

Задаёт путь и другие параметры кэша. Данные кэша хранятся в файлах. Имя файла в кэше является результатом применения функции 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 временные файлы и кэш можно размещать в разных файловых системах. Однако учтите, что в этом случае файл копируется между файловыми системами вместо дешёвой операции переименования. Поэтому рекомендуется для каждого location размещать кэш и каталог временных файлов в одной файловой системе. Каталог временных файлов задаётся параметром use_temp_path (1.7.10). Если этот параметр не указан или задано значение on, будет использоваться каталог, заданный директивой scgi_temp_path для данного location. Если задано значение off, временные файлы будут помещаться непосредственно в каталог кэша.

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

В рамках коммерческой подписки в зоне разделяемой памяти также хранится расширенная информация о кэше, поэтому для того же количества ключей требуется указать больший размер зоны. Например, в зоне размером один мегабайт может храниться около 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» задают параметры кэширования ответа;
• «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

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

denied

сервер отклонил соединение (1.29.3);

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

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, denied и 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.

Задаёт parameter, который должен передаваться SCGI-серверу. value может содержать текст, переменные или их сочетание. Эти директивы наследуются с предыдущего уровня конфигурации только в том случае, если на текущем уровне не определено ни одной директивы 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-серверов используется один запрос. Если эта функция включена, создаётся отдельный экземпляр запроса, что позволяет настраивать запрос для каждого сервера.

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

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

scgi_store /data/www$original_uri;

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;

scgi_store_access group:rw all:r;

scgi_temp_path /spool/nginx/scgi_temp 1 2;

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