BLOG | NGINX

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

NGINX-Parte-de-F5-horiz-preto-tipo-RGB
Miniatura de Owen Garrett
Owen Garrett
Publicado em 25 de outubro de 2016

Editor – A postagem do blog anunciando o lançamento original do suporte a módulos dinâmicos (no NGINX Open Source 1.9.11, fevereiro de 2016) redireciona para cá. O processo de construção descrito nessa postagem está obsoleto.

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

  • Esta postagem 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.
  • A segunda postagem fornece orientação e ferramentas para automatizar compilações 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 incluem verificação de dependência de versão.

 

O NGINX Open Source 1.11.5 e o NGINX Plus Release R11 introduziram compatibilidade binária para módulos dinâmicos. Este artigo explica como compilar módulos de terceiros para uso com NGINX Open Source e 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 Criando pacotes instaláveis para módulos dinâmicos .

Para ser breve, o restante desta postagem se refere apenas ao NGINX Plus, exceto quando a diferença entre ele e o NGINX Open Source for relevante. Exceto quando indicado, todas as declaraçõ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 no NGINX Wiki. Há um grande ecossistema de módulos de terceiros , que vão desde intérpretes de linguagem até soluções de segurança, e alguns deles estão incluídos e são suportados no 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 em tempo de execução. Você pode compilar esses módulos para uso com o NGINX Plus, construindo-os com o NGINX Open Source, conforme ilustrado nos dois exemplos abaixo:

  1. Obtenha a versão correspondente do NGINX Open Source
  2. Obtenha as fontes do módulo e altere o arquivo de configuração do módulo, se necessário
  3. Crie o módulo dinâmico em relação à versão NGINX Open Source, com o argumento --with-compat para o comando configure
  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 “Olá Mundo”

Este exemplo usa um módulo simples Hello World para mostrar como atualizar a 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.

Passo 1: Obtenha o lançamento do NGINX Open Source

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

    $ nginx -v versão nginx: nginx/1.11.5 (nginx-plus-r11)
    
  2. Baixe o pacote NGINX Open Source correspondente em nginx.org/download :

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

Passo 2: Obter as fontes 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
    
  2. O arquivo de shell de configuração de um módulo define como ele é construído, e seu formato é diferente para módulos dinâmicos do que para módulos construídos estaticamente em um binário NGINX Open Source.

    Modifique o arquivo nginx-hello-world-module/config para conter o seguinte:

    ngx_addon_name=ngx_http_hello_world_module
    
    se teste -n "$ngx_module_link"; então
    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/módulo
    senão
    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 como compilar módulos dinâmicos, incluindo instruções sobre como atualizar o arquivo de configuração de um módulo do formato antigo, consulte o NGINX Wiki .

Etapa 3: Compilar 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 suportado pelo NGINX Open Source e pelo NGINX Plus. Em seguida, execute make modules para construir o módulo:

    $ cd nginx-1.11.5/ $ ./configure --with-compat --add-dynamic-module=../nginx-hello-world-module $ make módulos
    
  2. Copie a biblioteca de módulos (arquivo .so ) para /etc/nginx/modules :

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

Passo 4: Carregue e use o módulo

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

    load_module módulos/ngx_http_hello_world_module.so;
    
  2. No contexto http , adicione um bloco de localização com a diretiva hello_world fornecida pelo módulo Hello World. Solicitações para o local retornam a resposta hello world .

    servidor {
    ouvir 80;
    
    localização / {
    ola_mundo;
    }
    }
    
  3. Recarregue sua configuração do NGINX Plus e teste-a com uma solicitação simples:

    $ nginx -s reload $ curl http://localhost/ olá mundo
    

Exemplo: O Firewall de Aplicativo Web NAXSI

O NAXSI é um firewall de aplicativo da Web (WAF) de alto desempenho e fácil de usar que usa 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 NAXSI foi atualizado para estar em conformidade com o novo formato do arquivo de shell de configuração , portanto, construir um módulo dinâmico para o NGINX Plus é simples. O processo é baseado 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 módulos $ 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 no seu arquivo nginx.conf :

load_module módulos/ngx_http_naxsi_module.so;

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

# Edite esta diretiva 'include' para apontar para seu arquivo naxsi_core.rules
include /home/owen/src/naxsi/naxsi_config/naxsi_core.rules;

server {
listen 80;

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

# Habilitar NAXSI
SecRulesEnabled;

# Definir para onde as solicitações bloqueadas vão
DeniedUrl "/50x.html";

# CheckRules, determinando quando o NAXSI precisa agir
CheckRule "$SQL >= 8" BLOCK;
CheckRule "$RFI >= 8" BLOCK;
CheckRule "$TRAVERSAL >= 4" BLOCK;
CheckRule "$EVADE >= 4" BLOCK;
CheckRule "$XSS >= 8" BLOCK;

# Não se esqueça do error_log, onde as requisições bloqueadas são registradas
error_log /tmp/naxsi.log;
}

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

Você pode verificar a operação correta do NAXSI com um par de 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 . Ele também registra uma mensagem no error_log .

Para implantações de 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 nesta seção se aplicam somente ao NGINX Plus. O conjunto de módulos dinâmicos fornecido com os pacotes NGINX Open Source pré-criados pode ser diferente daqueles fornecidos com o NGINX Plus. Os módulos dinâmicos usados com o NGINX Open Source são suportados da mesma forma que o código-fonte do NGINX e os binários pré-compilados.

O NGINX Plus vem com vários módulos dinâmicos que você também pode baixar diretamente do nosso repositório de módulos. Para uma lista, consulte a página Módulos Dinâmicos . Esses módulos são de dois tipos:

  • Os módulos NGINX Plus são escritos e/ou mantidos pela equipe de engenharia do NGINX. Não os incluímos no NGINX Plus por motivos técnicos (por exemplo, eles têm dependências adicionais) ou porque estão em um estado de visualização. Os módulos de visualização estão em desenvolvimento ativo e só devem ser implantados com muito cuidado. Caso contrário, os módulos NGINX Plus são totalmente suportados pelo NGINX. Para uma lista, filtre por autor NGINX na página Dynamic Modules .
  • Os módulos comunitários certificados NGINX Plus são módulos populares de terceiros que a NGINX testa e distribui, e para os quais fornecemos suporte com instalação e configuração básica. Garantimos que esses módulos não interferem na operação correta do NGINX Plus e os atualizamos conforme necessário a cada lançamento do NGINX Plus ou quando há um lançamento de segurança. Para obter uma lista, filtre por Comunidade de autores na página Módulos dinâmicos .

Além disso, a NGINX certifica módulos de fornecedores comerciais que participam do nosso programa NGINX Plus Certified Modules . Esses módulos são distribuídos e suportados por seus fornecedores. Para obter uma lista, filtre por autor Parceiro Certificado na página Módulos Dinâmicos .

O NGINX não testa nem oferece suporte a módulos que você mesmo compila (outros módulos da comunidade, módulos fornecidos por fornecedores terceirizados que não fazem parte do programa NGINX Plus Certified Modules e módulos personalizados). Se você procurar suporte técnico para um problema, a equipe de suporte do NGINX poderá solicitar que você remova um módulo sem suporte e reproduza a falha como parte do nosso processo de suporte técnico, para que eles possam verificar se a falha é ou não causada pelo módulo sem suporte.

Resumo

O processo de criação de módulos dinâmicos para o NGINX Plus permite que você aproveite o amplo ecossistema de módulos NGINX Open Source, executando-os no núcleo rico e totalmente suportado do NGINX Plus.

Se você estiver usando o NGINX Open Source com extensões de terceiros, essas extensões provavelmente poderão ser compiladas e carregadas no NGINX Plus.

Se você desenvolver módulos comerciais ou comunitários, o novo processo de construção significa que seus usuários podem implantar seus módulos com o NGINX Plus. Para saber mais sobre como certificar um módulo comercial, consulte Módulos certificados pelo NGINX Plus .

Se precisar de ajuda para desenvolver um módulo ou atualizar seu arquivo de configuração , confira os seguintes recursos:

A lista de e-mails de desenvolvedores do NGINX é o lugar ideal para obter assistência da comunidade, e nossa equipe de Serviços Profissionais também ficará feliz em ajudar.

Para experimentar módulos dinâmicos com o NGINX Plus, comece hoje mesmo um teste gratuito de 30 dias ou entre em contato conosco para discutir seus casos de uso .


"Esta postagem do blog pode fazer referência a produtos que não estão mais disponíveis e/ou não têm mais suporte. Para obter as informações mais atualizadas sobre os produtos e soluções F5 NGINX disponíveis, explore nossa família de produtos NGINX . O NGINX agora faz parte do F5. Todos os links anteriores do NGINX.com redirecionarão para conteúdo semelhante do NGINX no F5.com."