CGI#

O módulo adiciona suporte para CGI.

É importante observar que CGI não é adequado para:

  • alto QPS;

  • tráfego pesado;

  • alta concorrência.

Instalação#

Para instalar o módulo, use um dos seguintes pacotes:

  • Angie: angie-module-cgi

  • Angie PRO: angie-pro-module-cgi

Carregando o módulo#

Para carregar o módulo no contexto de main{}:

load_module modules/ngx_http_cgi_module.so;

Exemplo de configuração#

server {
    listen 80;

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

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

Um bloco location também pode executar o mesmo script para cada requisição que trata, independentemente do URI da requisição:

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

Aqui cgi_pass executa sozinho o script indicado; cgi on não é necessário neste location. Cada diretiva cgi_set_var adiciona uma variável ao ambiente do script, com um valor que pode ser construído a partir de variáveis do Angie. Um valor literal escrito diretamente em cgi_set_var não chega ao script sem alterações, portanto passe esse valor por meio de uma variável própria: set $hook_mode test; e, em seguida, cgi_set_var HOOK_MODE $hook_mode;. Além das variáveis CGI padrão, o script não recebe nada do ambiente dos processos worker do Angie: os valores definidos com a diretiva env não chegam até ele, portanto tudo o que ele precisa da configuração é passado por meio de cgi_set_var. A saída de erro padrão do script vai para o log de erros do Angie no nível warn, de modo que essas mensagens aparecem apenas quando o nível de log é warn ou menos severo. Um cabeçalho Status: na saída do script define o código de resposta; sem esse cabeçalho, o código de resposta é 200. O Exemplo com CGI e octoDNS do guia de ACME constrói um hook DNS-01 da mesma forma, no bloco location nomeado que acme_hook exige, passando as variáveis ACME ao script que atualiza o registro DNS.

Script de teste#

Um exemplo de script executável de teste test.sh:

#!/bin/sh
echo "Content-Type: text/plain" # Adiciona cabeçalho à resposta
echo "" # Separador entre cabeçalhos e corpo da resposta

# Variáveis de ambiente
echo "query string: $QUERY_STRING"
echo "server addr: $SERVER_ADDR"
echo "server port: $SERVER_PORT"

# Cabeçalhos da requisição via variáveis de ambiente
echo "http host: $HTTP_HOST"
echo "http accept: $HTTP_ACCEPT"
echo "http Some-Field: $HTTP_SOME_FIELD"

body=$(cat) # Lê o corpo da requisição em uma variável
echo "Request body: $body"

Colocando o script#

De acordo com a configuração, o script deve ser colocado no diretório /usr/share/angie/cgi-bin/. A instalação do módulo não cria esse diretório, portanto crie-o primeiro:

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

O arquivo deve ter permissões de leitura e execução.

Exemplo de execução de requisição#

$ 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"}

Informações adicionais#

Versão: v0.15.2

Documentação detalhada e código-fonte estão disponíveis em: pjincz/nginx-cgi