Compilando módulos dinâmicos de terceiros para NGINX e NGINX Plus

Owen GarrettDiretor Sênior de Gestão de Produtos

Editor – A publicação no blog que anunciou o lançamento original do suporte a módulos dinâmicos (no NGINX Open Source 1.9.11, em fevereiro de 2016) redireciona para esta página. O processo de compilação descrito naquela publicação está obsoleto.

Este post faz parte de uma série de duas partes sobre o uso de módulos dinâmicos de terceiros com o NGINX Open Source e o NGINX Plus.

• Este post fornece instruções passo a passo para compilar módulos dinâmicos de terceiros que podem ser carregados pelo NGINX Open Source ou NGINX Plus em tempo de execução.
• O segundo post fornece orientações e ferramentas para automatizar a compilação de módulos dinâmicos de terceiros para um ambiente de produção. Ele explica como criar pacotes instaláveis para módulos dinâmicos de terceiros que incluam a verificação de dependências de versão.

NGINX Open Source 1.11.5 e NGINX Plus Release R11 introduziram a compatibilidade binária para módulos dinâmicos. Este artigo explica como compilar módulos de terceiros para uso com o NGINX Open Source e o NGINX Plus em um ambiente de desenvolvimento. Para obter instruções sobre como criar, implantar e atualizar módulos dinâmicos de terceiros em um ambiente de produção, consulte Criação de pacotes instaláveis para módulos dinâmicos.

Para fins de concisão, o restante deste artigo se refere apenas ao NGINX Plus, exceto quando a diferença entre ele e o NGINX Open Source for relevante. Salvo indicação em contrário, todas as afirmações sobre o NGINX Plus também se aplicam ao NGINX Open Source.

Visão geral dos módulos dinâmicos

Os módulos que podem ser carregados no NGINX Plus são escritos em C e estão em conformidade com a API descrita em Estendendo o NGINX na Wiki do NGINX. Há um amplo ecossistema de módulos de terceiros, que abrange desde interpretadores de linguagens até soluções de segurança, e alguns deles são incluídos e compatíveis com o NGINX Plus.

Outros módulos de terceiros e módulos que você mesmo criou precisam ser compilados de forma independente e carregados dinamicamente no NGINX Plus durante a execução. Você pode compilar esses módulos para uso com o NGINX Plus, compilando-os com base no NGINX Open Source, conforme ilustrado nos dois exemplos abaixo:

1. Obtenha a versão correspondente do NGINX Open Source
2. Obtenha o código-fonte do módulo e altere o arquivo config do módulo, se necessário
3. Compile o módulo dinâmico com base na versão do NGINX Open Source, usando o argumento --with-compat no comando configure command
4. Carregue o módulo dinâmico resultante (o arquivo .so) no NGINX Plus e use-o como se fosse um módulo integrado

Exemplo: um módulo simples de “Olá, mundo”

Este exemplo usa um simples módulo Hello World para mostrar como atualizar o código-fonte de um módulo e carregá-lo no NGINX Plus. O módulo “Hello World” implementa uma diretiva simples (hello_world) que responde às solicitações com uma mensagem simples.

Etapa 1: Obtenha a versão do NGINX Open Source

1. Determine a versão do NGINX Open Source correspondente à sua instalação do NGINX Plus. Neste exemplo, é a versão 1.11.5 do NGINX.

$ nginx -vnginx version: nginx/1.11.5 (nginx-plus-r11)

1. Baixe o pacote correspondente do NGINX Open Source em nginx.org/download:

$ wget https://nginx.org/download/nginx-1.11.5.tar.gz$ tar -xzvf nginx-1.11.5.tar.gz

Etapa 2: Obtenha o código-fonte do módulo

1. Obtenha o código-fonte do módulo NGINX “Hello World” no GitHub:

$ git clone https://github.com/perusio/nginx-hello-world-module.git

1. O arquivo de shell config de um módulo define como ele é compilado, e seu formato é diferente para módulos dinâmicos em comparação com módulos compilados estaticamente em um binário do NGINX Open Source. Modifique o arquivo nginx-hello-world-module/config para que contenha o seguinte:

ngx_addon_name=ngx_http_hello_world_module

if test -n "$ngx_module_link"; then
    ngx_module_type=HTTP
    ngx_module_name=ngx_http_hello_world_module
    ngx_module_srcs="$ngx_addon_dir/ngx_http_hello_world_module.c"

    . auto/module
else
    HTTP_MODULES="$HTTP_MODULES ngx_http_hello_world_module"
    NGX_ADDON_SRCS="$NGX_ADDON_SRCS $ngx_addon_dir/ngx_http_hello_world_module.c"
fi

Para obter informações detalhadas sobre a compilação de módulos dinâmicos, incluindo instruções para atualizar o arquivo config de um módulo do formato antigo, consulte a Wiki do NGINX.

Etapa 3: compile o módulo dinâmico

1. Compile o módulo executando primeiro o script configure com o argumento --with-compat, que cria um ambiente de compilação padrão compatível com o NGINX Open Source e o NGINX Plus. Em seguida, execute make modules para compilar o módulo:

$ cd nginx-1.11.5/$ ./configure --with-compat --add-dynamic-module=../nginx-hello-world-module
$ make modules

1. Copie a biblioteca do módulo (.so arquivo) para /etc/nginx/modules:

$ sudo cp objs/ngx_http_hello_world_module.so /etc/nginx/modules/

Etapa 4: Carregue e use o módulo

1. Para carregar o módulo no NGINX Plus, adicione a diretiva load_module ao contexto de nível superior (principal) do arquivo de configuração nginx.conf (não dentro do contexto http ou stream):

load_module modules/ngx_http_hello_world_module.so;

1. No contexto http, adicione um bloco location com a diretiva hello_world fornecida pelo módulo Hello World. As solicitações para o local retornam a resposta hello world.

server {
    listen 80;

    location / {
         hello_world;
    }
}

1. Recarregue a configuração do NGINX Plus e teste-a com uma solicitação simples:

$ nginx -s reload$ curl http://localhost/
hello world

Exemplo: o firewall de aplicações web NAXSI

NAXSI é um firewall de aplicações web (WAF) fácil de usar e de alto desempenho, que utiliza heurística e um sistema de pontuação para identificar solicitações suspeitas, como ataques de XSS e injeção de SQL.

O código-fonte do NAXSI foi atualizado para estar em conformidade com o novo formato do arquivo shell config, portanto, a compilação de um módulo dinâmico para o NGINX Plus é simples. O processo se baseia nas instruções de instalação do NAXSI:

$ git clone https://github.com/nbs-system/naxsi.git$ cd nginx-1.11.5/
$ ./configure --with-compat --add-dynamic-module=../naxsi/naxsi_src
$ make modules
$ sudo cp objs/ngx_http_naxsi_module.so /etc/nginx/modules

Carregue o módulo no núcleo do NGINX Plus adicionando a diretiva load_module ao contexto principal do seu arquivo nginx.conf:

load_module modules/ngx_http_naxsi_module.so;

A configuração do NAXSI é descrita em detalhes na documentação do projeto. A configuração do NGINX a seguir ilustra o módulo em ação:

# Edit this 'include' directive to point to your naxsi_core.rules file
include /home/owen/src/naxsi/naxsi_config/naxsi_core.rules;

server {
    listen 80;

    location / {
        root /usr/share/nginx/html;

        # Enable NAXSI
        SecRulesEnabled;

        # Define where blocked requests go
        DeniedUrl "/50x.html";

        # CheckRules, determining when NAXSI needs to take action
        CheckRule "$SQL >= 8" BLOCK;
        CheckRule "$RFI >= 8" BLOCK;
        CheckRule "$TRAVERSAL >= 4" BLOCK;
        CheckRule "$EVADE >= 4" BLOCK;
        CheckRule "$XSS >= 8" BLOCK;

        # Don’t forget the error_log, where blocked requests are logged
        error_log /tmp/naxsi.log;
    }

    error_page   500 502 503 504  /50x.html;
}

Você pode verificar se o NAXSI está funcionando corretamente com duas solicitações HTTP simples:

• curl http://localhost/ retorna a página de índice padrão do NGINX Plus armazenada em /usr/share/nginx/html.
• curl "http://localhost/?a=<>" aciona a detecção de XSS do NAXSI e bloqueia a solicitação, retornando a página de erro padrão 50x.html de /usr/share/nginx/html. Uma mensagem também é registrada no error_log.

Para implantações em produção, você também pode baixar versões assinadas do NAXSI em https://github.com/nbs-system/naxsi/tags e compilá-las de maneira semelhante.

Como oferecemos suporte a módulos dinâmicos no NGINX Plus

Observação: As informações desta seção se aplicam somente ao NGINX Plus. O conjunto de módulos dinâmicos fornecido com os pacotes pré-compilados do NGINX Open Source pode ser diferente daquele fornecido com o NGINX Plus. Os módulos dinâmicos usados com o NGINX Open Source recebem suporte da mesma forma que o código-fonte e os binários pré-compilados do NGINX.

O NGINX Plus inclui vários módulos dinâmicos que também podem ser baixados diretamente do nosso repositório de módulos. Para ver uma lista, consulte a página Módulos dinâmicos. Esses módulos são de dois tipos:

• NGINX Plus são escritos e/ou mantidos pela equipe de engenharia da NGINX. Eles não são incluídos no NGINX Plus por motivos técnicos (por exemplo, por terem dependências adicionais) ou porque estão em fase de prévia. Os módulos em fase de prévia estão em desenvolvimento ativo e devem ser implantados com muito cuidado. Fora isso, os módulos do NGINX Plus contam com suporte completo da NGINX. Para ver uma lista, filtre pelo autor NGINX na página Módulos dinâmicos.
• Módulos da comunidade certificados para o NGINX Plus são módulos populares de terceiros que a NGINX testa e distribui e para os quais oferecemos suporte à instalação e à configuração básica. Garantimos que esses módulos não interferem no funcionamento correto do NGINX Plus e os atualizamos conforme necessário a cada versão do NGINX Plus ou quando há uma versão de segurança. Para ver uma lista, filtre por autor Comunidade na página Módulos dinâmicos.

Além disso, a NGINX certifica módulos de fornecedores comerciais que participam do nosso programa Módulos certificados do NGINX Plus. Esses módulos são distribuídos e recebem suporte de seus respectivos fornecedores. Para ver uma lista, filtre pelo autor Parceiro certificado na página Módulos dinâmicos.

A NGINX não testa nem oferece suporte a módulos compilados por você (outros módulos da comunidade, módulos fornecidos por terceiros que não fazem parte do programa NGINX Plus Certified Modules e módulos personalizados). Se você solicitar suporte técnico para um problema, a equipe de suporte da NGINX poderá pedir que você remova um módulo não compatível e reproduza a falha como parte do nosso processo de suporte técnico, para que possa verificar se a falha é ou não causada pelo módulo não compatível.

Resumo

O processo de compilação de módulos dinâmicos para o NGINX Plus permite aproveitar o amplo ecossistema de módulos do NGINX Open Source, executando-os no núcleo avançado e com suporte completo do NGINX Plus.

Se você usa atualmente o NGINX Open Source com extensões de terceiros, é muito provável que essas extensões possam ser compiladas e carregadas no NGINX Plus.

Se você desenvolve módulos comerciais ou da comunidade, o novo processo de compilação permite que seus usuários implantem seus módulos com o NGINX Plus. Para saber mais sobre a certificação de um módulo comercial, consulte Módulos certificados do NGINX Plus.

Se precisar de ajuda para desenvolver um módulo ou atualizar o arquivo shell de config, consulte os seguintes recursos:

• Guia de Emiller para o desenvolvimento de módulos do NGINX por Evan Miller
• Desenvolvimento de módulos dinâmicos pelo desenvolvedor do NGINX Ruslan Ermilov
• Estendendo o NGINX na Wiki do NGINX
• Conversão de módulos estáticos em módulos dinâmicos na Wiki do NGINX
• Tutorial do NGINX: Desenvolvimento de módulos por Aaron Bedra
• Como criar pacotes instaláveis para módulos dinâmicos em nosso blog

A lista de discussão NGINX Developers é o principal canal para obter ajuda da comunidade, e nossa equipe de Serviços Profissionais também terá prazer em ajudar.

Para experimentar os módulos dinâmicos do NGINX Plus, inicie hoje mesmo uma avaliação gratuita de 30 dias ou entre em contato conosco para conversar sobre seus casos de uso.

Sobre o autor

Owen GarrettDiretor Sênior de Gestão de Produtos

Mais publicações de Owen Garrett