Migrando de zabbix-agent para zabbix-agent2 de forma controlada

Trocar zabbix-agent por zabbix-agent2 parece uma operação simples:

1
2

apt install zabbix-agent2
systemctl enable --now zabbix-agent2

Em produção, isso pode terminar com dois serviços disputando a mesma porta.

Em uma migração real, a configuração do Agent 2 passava na validação, o systemd iniciava o processo e, segundos depois, aparecia:

1

Listen failed: listen tcp 0.0.0.0:10050: bind: address already in use

O serviço entrava em auto-restart e repetia o ciclo.

A causa imediata daquele erro estava clara: a TCP 10050 já tinha dono.

O aprendizado maior foi que migração de agente precisa ser tratada como troca de serviço, não como instalação de pacote.

Primeiro: descobrir o que já está escutando #

Antes de instalar qualquer coisa:

1

ss -lntp | grep ':10050'

Também:

1
2

systemctl status zabbix-agent --no-pager
systemctl status zabbix-agent2 --no-pager

E:

1
2

systemctl is-enabled zabbix-agent 2>/dev/null || true
systemctl is-enabled zabbix-agent2 2>/dev/null || true

O objetivo é responder:

1
2
3
4
5

agent clássico existe?
agent2 já existe?
qual está ativo?
qual processo possui a porta 10050?
há auto-restart configurado?

Sem isso, o pacote novo pode ser instalado sobre um estado que já conflita com ele.

Configuração válida não significa serviço executável #

No caso real, o log mostrava algo importante:

1
2

Validating configuration file ...
Validation successful

Logo depois:

1
2

cannot start server listener
bind: address already in use

São duas validações diferentes.

A primeira diz:

o arquivo de configuração é sintaticamente aceitável.

A segunda responde:

o processo consegue realmente ocupar os recursos que precisa no host?

Por isso eu não encerro uma migração em:

1

zabbix_agent2 -T -c /etc/zabbix/zabbix_agent2.conf

Esse comando é útil, mas insuficiente.

Preserve o contrato do agente antigo antes de removê-lo #

Antes da troca, eu registraria pelo menos:

1
2

grep -E '^(Server|ServerActive|Hostname|HostnameItem|HostMetadata|Timeout)=' \
  /etc/zabbix/zabbix_agentd.conf 2>/dev/null

E, se Agent 2 já existir:

1
2

grep -E '^(Server|ServerActive|Hostname|HostnameItem|HostMetadata|Timeout)=' \
  /etc/zabbix/zabbix_agent2.conf 2>/dev/null

Também:

1
2

hostname
getent hosts monitor.example.com

O ponto não é copiar cegamente a configuração antiga.

É saber quais propriedades fazem parte do contrato de monitoramento:

• identidade do host;
• Server/ServerActive;
• metadata de auto-registro;
• timeouts;
• UserParameters;
• includes;
• TLS, quando usado.

O passo crítico: parar o serviço antigo antes de liberar a porta #

Se a estratégia é substituir o agent clássico:

1
2

sudo systemctl stop zabbix-agent
sudo systemctl disable zabbix-agent

Depois confirmar:

1

ss -lntp | grep ':10050' || true

A porta precisa estar livre antes de iniciar o Agent 2 — salvo se o desenho deliberadamente usa outra porta.

Só então:

1
2

sudo systemctl enable zabbix-agent2
sudo systemctl restart zabbix-agent2

Purge pode fazer sentido, mas não deve ser o primeiro movimento cego #

Em outra automação real, a role tinha uma etapa explícita de remoção de instalações antigas de zabbix-agent e zabbix-agent2 antes da instalação desejada.

Essa abordagem reduz resíduos de pacote/configuração quando o padrão do host está bem conhecido.

Mas em ambiente heterogêneo eu ainda faria preflight antes de purge.

Perguntas importantes:

1
2
3
4
5

há UserParameter customizado?
há PSK/certificado local?
há include customizado?
a configuração antiga precisa ser migrada?
o host depende de checagens passivas?

Remover primeiro e descobrir depois é uma forma ruim de documentar dependências.

O dpkg também pode falhar porque o pós-instalação tenta iniciar o serviço #

Uma execução Ansible recuperada mostrou a instalação do pacote zabbix-agent2 falhando durante o dpkg.

O pacote foi desempacotado, mas o pós-instalação não conseguiu completar a ativação do serviço.

O resultado foi:

1

failed=1

no PLAY RECAP.

Isso é importante porque o erro superficial pode aparecer como:

1

apt/dpkg retornou rc=100

quando o próximo passo é olhar:

1
2

systemctl status zabbix-agent2
journalctl -u zabbix-agent2 --no-pager

O gerenciador de pacotes pode estar apenas propagando uma falha do serviço.

Validação em camadas #

Depois da troca, eu valido nesta ordem.

1. Configuração #

1

zabbix_agent2 -T -c /etc/zabbix/zabbix_agent2.conf

2. Serviço #

1
2

systemctl is-active zabbix-agent2
systemctl status zabbix-agent2 --no-pager

3. Porta #

1

ss -lntp | grep ':10050'

4. Processo antigo #

1
2

systemctl is-active zabbix-agent 2>/dev/null || true
ps aux | grep -E '[z]abbix_agent(d|2)'

5. Log #

1

journalctl -u zabbix-agent2 -n 100 --no-pager

6. Conectividade com o Server #

Para active checks, por exemplo:

1

nc -vz monitor.example.com 10051

quando essa for a arquitetura.

7. Zabbix frontend/API #

Confirmar que o host continua recebendo dados e que os itens esperados deixam de ficar unsupported/stale.

Agent 2 não deve ser escolhido só porque é “mais novo” #

Outro ambiente real exigiu o contrário: o procedimento correto era manter agent clássico 6.0 LTS, alinhado ao padrão daquela monitoria, e remover uma instalação anterior baseada no repositório 7.0.

Isso reforça uma regra:

versão e tipo de agente são decisões do ambiente, não uma atualização automática por preferência.

Antes da migração, validar:

• versão do Zabbix Server/Proxy;
• templates usados;
• plugins Agent 2 necessários;
• sistema operacional/arquitetura;
• auto-registro;
• checagens ativas/passivas;
• política da equipe de monitoria.

Rollback precisa ser simples #

Se o Agent 2 não funcionar e o pacote antigo ainda estiver disponível/configurado, um rollback controlado pode ser:

1
2
3
4

sudo systemctl stop zabbix-agent2
sudo systemctl disable zabbix-agent2
sudo systemctl enable zabbix-agent
sudo systemctl start zabbix-agent

Depois validar novamente porta, logs e recebimento de dados.

Se houve purge, o rollback passa a depender de reinstalação/restauração da configuração — por isso a decisão de remover definitivamente deve vir depois da validação.

Checklist de migração #

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

[ ] identificar versão/padrão esperado da monitoria
[ ] capturar configuração do agent atual
[ ] listar UserParameters/includes/TLS
[ ] confirmar processo que ocupa 10050
[ ] instalar/preparar Agent 2
[ ] parar e desabilitar agent antigo
[ ] confirmar 10050 livre
[ ] validar config Agent 2
[ ] iniciar Agent 2
[ ] confirmar 10050 no processo correto
[ ] revisar journal
[ ] validar 10051/ServerActive quando aplicável
[ ] validar itens no Zabbix
[ ] só depois decidir purge definitivo do agent antigo

O que a evidência permite concluir #

A fonte recuperada comprova um host onde:

• zabbix-agent estava ativo;
• o Agent 2 validava sua configuração;
• o Agent 2 falhava repetidamente ao tentar bind na TCP 10050;
• o systemd fazia novas tentativas automáticas.

Outra execução comprova uma instalação Agent 2 via Ansible que terminou com falha do pacote/serviço e PLAY RECAP failed=1.

Essas fontes sustentam o risco operacional da coexistência e a necessidade de validação por camadas.

Elas não são usadas para afirmar que todo ambiente deve migrar para Agent 2.

O principal aprendizado #

Migrar agente de monitoramento é uma troca de responsabilidade sobre o host.

O momento crítico não é quando o pacote novo aparece em dpkg -l.

É quando você consegue provar:

1
2
3
4
5

serviço antigo saiu
porta foi liberada
serviço novo assumiu
configuração está correta
dados continuam chegando

Sem isso, você pode ter instalado o Agent 2 e, ao mesmo tempo, perdido o monitoramento.