BLOG | NGINX

Recuperando-se de uma atualização com falha do NGINX Plus: 'módulo "M" versão X em vez de Y'

NGINX-Parte-de-F5-horiz-preto-tipo-RGB
Miniatura de Liam Crilly
Liam Crilly
Publicado em 14 de março de 2017

Se você estiver usando módulos dinâmicos, poderá ver um erro como este durante a atualização para uma nova versão do NGINX ou NGINX Plus:

Configurando o nginx-plus (1.11.10-1~xenial) ... nginx: [emerg] módulo "/etc/nginx/modules/ngx_http_geoip_module.so" versão 1011005 em vez de 1011006 em /etc/nginx/nginx.conf:7 nginx: teste do arquivo de configuração /etc/nginx/nginx.conf falhou invoke-rc.d: initscript nginx, ação "upgrade" falhou.

O motivo mais provável é que você não atualizou o módulo dinâmico especificado (arquivo .so ):

  • Se você estiver executando o NGINX Open Source, os módulos dinâmicos deverão ser compilados na versão para a qual você está atualizando.
  • Se você estiver executando o NGINX Plus, os módulos dinâmicos deverão ser compilados com a versão NGINX Open Source que corresponde à versão do NGINX Plus para a qual você está atualizando.

Para ser breve, nos referiremos apenas ao NGINX Plus a partir de agora.

Não entrar em pânico!

Tenha certeza de que esta mensagem de erro não indica que seu servidor NGINX Plus está inativo. As atualizações do NGINX Plus são perfeitas, então a versão antiga continua em execução quando uma atualização falha. Entretanto, a atualização está incompleta e seu sistema está em um estado inconsistente:

  • Os processos NGINX Plus na memória estão executando a versão antiga
  • Todos os arquivos no disco relacionados ao NGINX Plus correspondem à nova versão
  • O módulo dinâmico mencionado na mensagem de erro é compilado com a versão antiga

Não reinicie o nginx manualmente nem reinicie o sistema. Isso causará tempo de inatividade porque novos processos do NGINX Plus não poderão ser iniciados enquanto houver módulos dinâmicos fora de sincronia com a nova versão do NGINX Plus.

Observe que a mensagem de erro se refere apenas ao primeiro módulo incompatível encontrado durante o processo de atualização, portanto, é importante encontrar todas as diretivas load_module na sua configuração e garantir que cada módulo seja compilado com a versão apropriada do NGINX. Versões corretas de todos os módulos dinâmicos de terceiros certificados e criados pelo NGINX são fornecidas para cada versão do NGINX Plus<, portanto, você precisa recompilar apenas os módulos não certificados. Este artigo descreve como concluir o processo de atualização com segurança.

O que deu errado?

O NGINX 1.11.5 e o NGINX Plus R11 introduziram a capacidade de compilar módulos dinâmicos no NGINX Open Source e carregá-los no NGINX Plus. Essa compatibilidade binária requer que o módulo e o NGINX Plus compartilhem a mesma versão base de código aberto. A atualização do NGINX Plus sem primeiro instalar módulos dinâmicos criados com a versão correspondente do NGINX Open Source falha devido a essa incompatibilidade de versões.

Se o seu módulo dinâmico foi fornecido por um fornecedor terceirizado, você precisa entrar em contato com o fornecedor para obter uma nova versão, correspondente à versão do NGINX para a versão do NGINX Plus para a qual você pretende atualizar. Se o seu módulo dinâmico foi compilado a partir do código-fonte (e você tem acesso ao código-fonte), continue lendo.

O Caminho para a Recuperação

Passo 0: Preparar o ambiente de construção

Recomendamos fortemente que você compile módulos dinâmicos em um sistema separado, ao qual nos referimos aqui como “ambiente de construção”. Isso minimiza o risco e a complexidade do sistema em que você está executando o NGINX Plus com o módulo dinâmico (chamamos isso de “ambiente de produção”). O ambiente de construção deve ter o mesmo sistema operacional e versão do ambiente de produção ; além disso, os seguintes componentes devem ser instalados:

  • Utilitário UnZip
  • Compilador e utilitário make
  • Biblioteca de expressões regulares compatíveis com Perl (arquivos de desenvolvimento)
  • Bibliotecas de compressão Zlib (arquivos de desenvolvimento)

Para garantir que seu ambiente de compilação tenha esses pré-requisitos instalados, execute o seguinte comando.

  • Para Ubuntu/Debian:

    buildenv$ sudo apt-get install descompactar gcc fazer libpcre3-dev zlib1g-dev
  • Para CentOS/RHEL/Oracle Linux:

    buildenv$ sudo yum install descompactar gcc fazer pcre-devel zlib-devel

Passo 1: Obtenha o NGINX Open Source

  1. Trabalhando no ambiente de produção, execute o seguinte comando para identificar a versão do NGINX Open Source que corresponde à versão do NGINX Plus em execução. Está destacado em laranja nesta saída: NGINX 1.11.10, que corresponde ao NGINX Plus R12.

    produção$ nginx -v versão nginx: nginx/ 1.11.10 (nginx-plus-r12)
  2. Trabalhando no ambiente de compilação, baixe as fontes para a versão apropriada do NGINX Open Source.

    build-env$ wget -qO - http://nginx.org/download/nginx-1.11.10 .tar.gz | tar zxfv -

Passo 2: Obter as fontes do módulo dinâmico

Copie o código-fonte do módulo dinâmico para o diretório de compilação de sua escolha. Aqui copiamos um módulo de exemplo “hello world” do NGINX de seu repositório GitHub.

buildenv$ git clone https://github.com/perusio/nginx-hello-world-module.git Clonando em 'nginx-hello-world-module'...

Etapa 3: Compilar o módulo dinâmico

  1. Compile o módulo dinâmico executando primeiro o script de configuração do NGINX com o argumento --with-compat para tornar o módulo dinâmico compatível com o binário do NGINX Plus. Em seguida, execute make modules para compilar apenas o módulo.

    buildenv$ cd nginx-1.11.10/ buildenv$ ./configure --with-compat --add-dynamic-module=../nginx-hello-world-module buildenv$ make módulos
  2. Verifique se o processo de compilação criou o módulo dinâmico como um arquivo .so no subdiretório objs .

    buildenv$ ls objs/*.so objs/ngx_http_hello_world.so
  3. Crie uma cópia do arquivo do módulo com a versão NGINX Open Source no nome do arquivo. Isso simplifica o gerenciamento de várias versões do módulo dinâmico no ambiente de produção.

    buildenv$ cp objs/ngx_http_hello_world.so ./ngx_http_hello_world_1.11.10.so

Passo 4: Copie o módulo dinâmico para o ambiente de produção

Como criamos o módulo dinâmico com a versão NGINX Open Source no nome do arquivo, podemos copiá-lo com segurança para o ambiente de produção sem afetar a operação.

buildenv$ scp ./ngx_http_hello_world_1.11.10.so produção:/etc/nginx/modules

Etapa 5: Trocar o módulo dinâmico

Trabalhando no ambiente de produção, troque o novo arquivo .so para substituir o atual. É seguro fazer isso neste momento porque os módulos dinâmicos são carregados na memória somente quando o nginx é reiniciado ou a configuração é recarregada.

produção$ cd /etc/nginx/modules produção$ cp ngx_http_hello_world.so ngx_http_hello_world_ROLLBACK.so produção$ ln -fs ngx_http_hello_world_1.11.10.so ngx_http_hello_world.so produção$ ls -gG -rw-r--r-- 1 243576 31 de jan 16:18 ngx_http_hello_world_1.11.10.so -rw-r--r-- 1 243576 20 de out 10:40 ngx_http_hello_world_ROLLBACK.so lrwxrwxrwx 1 24 31 de jan 16:26 ngx_http_hello_world.so -> ngx_http_hello_world_1.11.10.so

Etapa 6: Conclua a atualização do NGINX Plus

  1. Execute o seguinte comando para testar se a versão do módulo está correta e se o NGINX Plus está pronto para concluir o processo de atualização.

    production$ nginx -t nginx: a sintaxe do arquivo de configuração /etc/nginx/nginx.conf está ok nginx: o teste do arquivo de configuração /etc/nginx/nginx.conf foi bem-sucedido
  2. Conclua o processo de atualização para que o NGINX Plus esteja usando a nova versão e os módulos dinâmicos.

    produção$ serviço nginx upgrade Iniciando novo mestre nginx: [ OK ] Desligamento normal do antigo nginx: [ OK ]

Evitando a falha de atualização

Na próxima vez que você atualizar o NGINX Plus, poderá economizar tempo e evitar erros seguindo estas instruções antes da atualização para que os módulos dinâmicos atualizados já estejam disponíveis quando você iniciar o processo de atualização.


"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."