CGI#

Модуль добавляет поддержку CGI.

Важно учитывать, что CGI не подходит для:

  • высокого QPS;

  • интенсивного трафика;

  • высокой параллельности.

Установка#

Для установки модуля используйте один из следующих пакетов:

  • Angie: angie-module-cgi;

  • Angie PRO: angie-pro-module-cgi.

Загрузка модуля#

Подключение модуля в контексте main{}:

load_module modules/ngx_http_cgi_module.so;

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

server {
    listen 80;

    root /usr/share/angie/html;
    index index.html index.htm;

    location /cgi {
        alias /usr/share/angie/cgi-bin;
        cgi on;
    }
}

Блок location может также запускать один и тот же скрипт для всех обрабатываемых запросов, независимо от их URI:

location /hook {
    cgi_set_var HOOK_CLIENT $remote_addr;
    cgi_set_var HOOK_HOST $host;
    cgi_pass /usr/share/angie/cgi-bin/hook.sh;
}

Здесь cgi_pass запускает указанный скрипт сам по себе; cgi on в этом блоке не требуется. Каждая директива cgi_set_var добавляет в окружение скрипта одну переменную, значение которой может строиться из переменных Angie. Литеральное значение, записанное прямо в cgi_set_var, доходит до скрипта измененным, поэтому передавайте такое значение через собственную переменную: set $hook_mode test;, а затем cgi_set_var HOOK_MODE $hook_mode;. Кроме стандартных CGI-переменных скрипт ничего не получает из окружения рабочих процессов Angie: значения, заданные директивой env, ему недоступны, поэтому все, что нужно скрипту из конфигурации, передается через cgi_set_var. Стандартный поток ошибок скрипта попадает в журнал ошибок Angie на уровне warn, поэтому эти сообщения видны только при уровне warn или менее серьезном. Заголовок Status: в выводе скрипта задает код ответа; без него код ответа — 200. В примере с CGI и octoDNS из руководства по ACME хук DNS-01 построен таким же образом, в именованном блоке location, которого требует acme_hook: ACME-переменные передаются скрипту, который обновляет DNS-запись.

Тестовый скрипт#

Пример тестового исполняемого скрипта test.sh:

#!/bin/sh
echo "Content-Type: text/plain" # Добавить заголовок в ответе
echo "" # Разделитель заголовков и тела ответа

# Переменные окружения
echo "query string: $QUERY_STRING"
echo "server addr: $SERVER_ADDR"
echo "server port: $SERVER_PORT"

# Заголовки запроса через переменные окружения
echo "http host: $HTTP_HOST"
echo "http accept: $HTTP_ACCEPT"
echo "http Some-Field: $HTTP_SOME_FIELD"

body=$(cat) # Считывает тело запроса в переменную
echo "Request body: $body"

Размещение скрипта#

Скрипт, в соответствии с конфигурацией, необходимо разместить в каталоге /usr/share/angie/cgi-bin/. При установке модуля этот каталог не создается, поэтому создайте его заранее:

$ sudo install -d /usr/share/angie/cgi-bin

Файл должен иметь права на чтение и выполнение.

Пример выполнения запроса#

$ curl  -H 'Some-Field:some text' -d '{"key1":"value1", "key2":"value2"}' -i \
  'http://127.0.0.1/cgi/hello.sh?a=valueA&b=valueB'

HTTP/1.1 200 OK
Server: Angie/1.12.4
Date: Fri, 16 Oct 2026 19:15:35 GMT
Transfer-Encoding: chunked
Connection: keep-alive
Content-Type: text/plain

query string: a=valueA&b=valueB
server addr: 127.0.0.1
server port: 80
http host: 127.0.0.1
http accept: */*
http Some-Field: some text
Request body: {"key1":"value1", "key2":"value2"}

Дополнительная информация#

Версия: v0.15.2

Подробная документация и исходный код доступны по ссылке: pjincz/nginx-cgi