Conectar um servidor Zabbix

Conectar um servidor Zabbix é o primeiro passo para o Sentrya ler os problemas do seu monitoramento. A conexão é testada de verdade antes de salvar, e as credenciais ficam cifradas no servidor.

Antes de começar

Tenha a URL completa da API JSON-RPC, terminando em api_jsonrpc.php (ex.: https://zbx.empresa.com/api_jsonrpc.php). O Sentrya não completa a URL: se você informar só o endereço da interface web, a verificação falha.
Tenha um Token de API gerado no Zabbix (Usuários → Tokens de API a partir do 6.4; Administração → Geral → Tokens de API antes; ou, para o próprio usuário, Configurações do usuário → Tokens de API) ou um usuário e senha do Zabbix.
Você precisa ser Admin ou Operador. Visualizadores veem a lista de servidores, mas não adicionam, verificam nem removem.

O Zabbix precisa ser alcançável pela internet. Nesta forma de conexão, endereços de rede interna (10.x, 192.168.x, localhost) são recusados. Se o seu Zabbix fica numa rede interna, use o Sentrya Connector: ele liga o Zabbix ao Sentrya só com uma conexão de saída, sem abrir porta no firewall. Um servidor já conectado direto pode passar para o Connector depois, sem perder incidentes, histórico, ouvintes nem visões: com o Connector já instalado e online, o administrador usa Passar para o Sentrya Connector no menu do servidor, em Servidores Zabbix. O caminho inverso, Voltar para conexão direta, pede a URL e uma credencial nova. Qualquer troca de conexão desfaz os vínculos das pessoas com o Zabbix naquele servidor: cada uma vincula de novo, porque o token de cada pessoa só pode ir ao endereço em que foi criado.

Adicionar o servidor

Abra Ajustes → Servidores Zabbix Na aba Perfil, toque em Ajustes e depois em Servidores Zabbix.
Toque em "Adicionar novo Zabbix" No iOS é o "+" no topo da tela; no Android, o botão abaixo da lista.
Preencha "Nome do servidor" e "URL da API" O nome é livre e aparece como Origem dos incidentes. A URL deve incluir api_jsonrpc.php.
Escolha a "Autenticação" Token de API (recomendado: não expira) ou Usuário e senha. Com usuário e senha, o Sentrya faz o login no Zabbix e guarda o token de sessão por você, renovando-o quando expira.
Toque em "Salvar" O servidor testa a conexão na API real do seu Zabbix. Se qualquer etapa falhar, nada é salvo e o motivo aparece na tela.

O que a verificação faz

Ao salvar (e sempre que você toca em Verificar conexão), o Sentrya chama apiinfo.version, sem autenticação, para confirmar que a URL é uma API Zabbix e ler a versão; depois chama host.get com a credencial para confirmar que ela é aceita e contar os hosts visíveis. Só então o servidor é gravado com o status Conectado. Token, usuário e senha são cifrados antes de ir para o banco e nunca voltam pela API.

O usuário da coleta

Depois de uma verificação que dá certo, o Sentrya descobre quem é o usuário do Zabbix da credencial, o usuário da coleta, e de que tipo ele é (Super admin, Admin ou User). O nome dele aparece nos avisos de em nome de quem o ACK sai: no formulário de ACK de quem não tem Vínculo com o Zabbix, na coluna ACK sai como da lista de Usuários e no aviso do convite por email, no painel administrativo.

Autenticação	Como o Sentrya descobre o usuário
Usuário e senha	No próprio `user.login` da verificação, que já devolve o usuário e o tipo.
Token de API	`user.checkAuthentication` com o token (Zabbix 6.0 ou mais novo); no 5.4, `token.get` com o próprio token. Depois, `user.get` do próprio usuário para ler o nome e o tipo.
Sentrya Connector	Só `user.get` com `editable`, que devolve o próprio usuário.

Isso acontece ao salvar o servidor, a cada Verificar conexão que dá certo e ao trocar a conexão. Descobrir o usuário nunca impede salvar nem verificar: se não der, o Sentrya segue sem o nome, e os avisos dizem "o usuário da coleta". Uma verificação que falha não apaga o nome que já estava certo. Com um token de API de Super admin no Zabbix 5.4, ou com um Super admin pelo Sentrya Connector, o Sentrya descobre só o tipo, não o nome.

Permissões e vínculo (painel administrativo)

No painel administrativo, em Conexões → Zabbix, o menu de cada servidor tem Permissões e vínculo. Só o administrador da empresa abre esse cartão. Ele mostra:

Usuário da coleta: o nome do usuário, por exemplo api.sentrya, com o selo Super admin ou o tipo dele (Admin ou Usuário), quando foi verificado e quantas pessoas estão vinculadas naquele servidor. Se o Sentrya ainda não sabe quem é o usuário da coleta, o cartão oferece Verificar conexão.
O interruptor Usar permissões do Zabbix, com a data da última cópia das permissões, quantas pessoas veem por elas e o botão Atualizar permissões agora. Veja a seção a seguir.
O interruptor Vincular automaticamente pelo login Microsoft e o botão Vincular agora. Veja Vincular pelo Microsoft 365.
Vínculos recusados: quem tocou em Não sou eu depois de um vínculo automático, com Liberar de novo.
Tokens criados pelo Sentrya: os tokens de API que o Sentrya criou naquele Zabbix para assinar os reconhecimentos de cada pessoa, com quando e por quem foram criados e quando vencem. O token em si nunca aparece.
Tokens a apagar no Zabbix, só quando há algum. Veja abaixo.

Sem Super admin, o vínculo automático e as permissões do Zabbix ficam indisponíveis. O cartão avisa que o usuário da coleta não é Super admin, impede ligar os dois interruptores, com o motivo, e leva a Dar Super admin ao usuário da coleta. A coleta, os reconhecimentos e o vínculo que cada pessoa faz com um token de API ou com usuário e senha continuam funcionando. Sem Super admin, o Sentrya também não renova nem apaga os tokens que criou: eles vencem em um ano, e os que precisam sair do Zabbix vão para Tokens a apagar no Zabbix.

Usar permissões do Zabbix

Com esta opção, quem está vinculado passa a ver, naquele servidor, o que o próprio Zabbix libera para o usuário dele, no lugar do acesso inicial. As regras completas estão em Grupos visíveis: o que cada um enxerga.

Abra Permissões e vínculo Em Conexões → Zabbix, abra o menu do servidor e escolha Permissões e vínculo. Confira se o usuário da coleta tem o selo Super admin: só ele consegue ler as permissões dos outros usuários do Zabbix.
Ligue o interruptor Ligue Usar permissões do Zabbix. A confirmação explica: "Quem estiver vinculado neste servidor passa a ver só o que o Zabbix libera para ele, com as mesmas regras do Zabbix: grupo de hosts negado esconde os hosts dele, e com filtro de tag só valem os grupos com “todas as tags”. Quem não estiver vinculado continua com o acesso inicial. Quem tiver o vínculo quebrado não vê nada deste servidor até revincular."
Confira a primeira cópia Ao ligar, o Sentrya lê na hora as permissões de todas as pessoas vinculadas naquele servidor. O cartão mostra quando foi a última cópia, quantas pessoas veem pelas permissões do Zabbix e, se a leitura falhou, o último erro.

Depois disso, o Sentrya copia as permissões de novo a cada cerca de 10 minutos. Mudou algo no Zabbix e não quer esperar? Toque em Atualizar permissões agora. Se o Zabbix estiver fora do ar, vale a última cópia.

A opção vem desligada em todo servidor, e só o administrador da empresa liga. Desligar faz todos voltarem ao acesso inicial naquele servidor.

Se alguém tirar o Super admin do usuário da coleta no Zabbix depois de ligar a opção, a cópia seguinte percebe e para. O cartão mostra "A última atualização das permissões falhou. O usuário da coleta não é Super admin: sem ele o Zabbix não mostra as permissões das outras pessoas. Enquanto isso, vale o que foi lido em …", com a data da cópia que continua valendo. Os vínculos das pessoas não são desfeitos, o interruptor continua ligado (dá para desligar) e o vínculo automático pelo Microsoft fica indisponível. Quando o usuário da coleta voltar a ser Super admin, toque em Verificar conexão: o Sentrya confere o usuário de novo, e a cópia volta na rodada seguinte, ou na hora com Atualizar permissões agora.

Antes de ligar, peça o vínculo à equipe. Quem não está vinculado continua com o acesso inicial, mas quem está com o vínculo com problema deixa de ver os incidentes daquele servidor. Use o filtro Vínculo Zabbix em Usuários para achar quem precisa revincular.

Tokens a apagar no Zabbix

São tokens de API que o Sentrya criou para alguém e depois precisou apagar (a pessoa desvinculou, tocou em Não sou eu, foi desativada ou excluída, a conexão do servidor mudou, ou o Sentrya criou o token e não conseguiu terminar o vínculo ou a renovação), mas não conseguiu apagar no Zabbix: o usuário da coleta não é Super admin, o servidor está num Sentrya Connector que não guarda os tokens de pessoa (de uma versão anterior, ou com eles desligados), ou o Zabbix não respondeu. O Sentrya já não usa nenhum deles, mas eles continuam válidos na lista de tokens do Zabbix até alguém apagá-los.

Cada linha mostra a pessoa (ou "Conta já excluída"), o usuário do Zabbix dono do token, o ID do token no Zabbix, quando foi criado e o motivo.
A cada hora, o Sentrya tenta apagá-los de novo sozinho nos servidores cujo usuário da coleta é Super admin, em conexão direta ou num Sentrya Connector que guarda os tokens de pessoa (por exemplo, depois de atualizar o conector ou de religar os tokens de pessoa nele). O que ele apaga sai da lista.
Num Sentrya Connector que guarda os tokens de pessoa, quando o Sentrya apaga o token de uma pessoa, leva junto os tokens dela que estavam nesta lista naquele servidor. Com o usuário da coleta Super admin, eles saem do Zabbix e da lista.
Se preferir, apague o token no Zabbix e use Já apaguei no Zabbix. A lista de tokens de todos os usuários fica em Usuários → Tokens de API (Users → API tokens) a partir do Zabbix 6.4 e em Administração → Geral → Tokens de API (Administration → General → API tokens) nas versões anteriores; apagar o token de outro usuário exige um Super admin. A confirmação lembra de conferir antes que o token já não está lá; o Sentrya só para de mostrá-lo.

Excluir o servidor não apaga esses tokens. A lista some junto com o servidor. Por isso, quando um servidor com tokens a apagar é excluído, os administradores da empresa recebem uma notificação push, "Tokens do Sentrya ficaram no Zabbix", e um e-mail com a lista: o servidor e o endereço dele e, para cada token, o usuário do Zabbix, o ID do token e a pessoa do Sentrya. O e-mail explica onde fica a lista de tokens no Zabbix. O token em si nunca vai no e-mail.

No app e no Sentrya Web, o cartão do servidor Zabbix também tem Permissões e vínculo para o administrador: o usuário da coleta, o interruptor Usar permissões do Zabbix com Atualizar permissões agora, a data da última cópia e o último erro, e o interruptor Vincular automaticamente pelo login Microsoft com Vincular agora e o resumo do resultado. Se o usuário da coleta deixou de ser Super admin, o cartão avisa que a cópia das permissões parou e que quem está vinculado continua vendo o que foi lido por último. Vínculos recusados e tokens a apagar aparecem como contagem, com Gerenciar no /admin, e se gerenciam no painel administrativo. Se o Sentrya ainda não sabe quem é o usuário da coleta, o app e o Sentrya Web dizem "Ainda não sabemos qual é o usuário da coleta. Verifique a conexão deste servidor no /admin.", sem botão nessa seção.

Permissões mínimas no Zabbix

O Sentrya só enxerga o que a credencial enxerga: o usuário dono do token precisa ler os hosts que você quer acompanhar. Métodos da API chamados:

Método	Para quê
`apiinfo.version`	Verificar a URL e registrar a versão.
`user.login`	Autenticação por usuário e senha (e renovação da sessão). Na verificação, devolve também quem é o usuário da coleta.
`user.checkAuthentication`, `token.get`	Descobrir o dono de um token de API (o usuário da coleta). Do `token.get` só se leem o id do token e o id do dono, nunca o token.
`host.get`	Contar hosts na verificação; listar hosts nos filtros e no assistente de ouvintes.
`problem.get`	Coletar os problemas abertos.
`trigger.get`	Descobrir o host de cada problema, filtrar triggers monitoradas, montar ouvintes.
`hostgroup.get`	Grupos de hosts (Grupos visíveis e filtros).
`event.get`	Semear as Recorrências (30 dias) e ler o Histórico de ACKs feito no Zabbix.
`event.acknowledge`	Reconhecer incidente, comentar, mudar severidade e fechar problema pelo app.
`user.get`, `usergroup.get`	Para Entrada da equipe e Vínculo com o Zabbix, que exigem uma credencial que consiga listar usuários (na prática, Super Admin). O `user.get` também lê o nome e o tipo do próprio usuário da coleta e, no vínculo pelo Microsoft 365, procura o usuário de cada pessoa. Com Usar permissões do Zabbix, os dois leem os grupos de usuários de quem está vinculado, os direitos deles nos grupos de hosts e os filtros de tag.
`token.create`, `token.generate`, `token.get`, `token.delete`	Criar, renovar e apagar o token de API de cada pessoa vinculada: no vínculo pelo Microsoft 365, no vínculo por senha de quem não pode criar o próprio token e ao desfazer vínculos. Exige Super admin.

Sem permissão de ACK no Zabbix, o app mostra a mensagem real do Zabbix ("o Zabbix recusou a operação: …"). Se a trigger não permite fechamento manual, o app avisa que você ainda pode reconhecer (ACK) sem fechar.

Versões do Zabbix

Funciona com Zabbix 5.x, 6.x e 7.x: o token vai no cabeçalho Authorization: Bearer (6.4+) com recuo para o campo auth em versões anteriores; o login tenta username (5.4+) e recua para user; o filtro de sintomas só é aplicado em 6.4+. Ressalva: ambientes com mais de 5 000 problemas abertos ao mesmo tempo são paginados com um parâmetro do problem.get que existe a partir do Zabbix 6.0.

O card do servidor

Nome e pílula de status: Conectado, Erro ou Conectando…. Em erro, a última mensagem de falha aparece no card.
hosts monitorados (da última verificação) e problemas ativos — contagem que respeita os seus Grupos visíveis; o Admin vê o total.
"sincronizado há …" ou "nunca sincronizado".
Verificar conexão — refaz o teste e atualiza status, hosts e erro; com usuário e senha, renova a sessão. Se a conexão voltou num servidor já confirmado, uma coleta imediata é agendada. Antes da confirmação, o botão é Fazer primeira coleta (Primeira coleta).

Limite por plano

A quantidade de servidores Zabbix por empresa depende do plano; ao atingir o limite, salvar devolve um erro e nada é criado. Veja Planos e limites.

Erros comuns ao salvar

Mensagem no app	Causa provável	O que fazer
não foi possível conectar à URL informada	DNS errado, firewall, Zabbix fora do ar, certificado HTTPS inválido ou resposta lenta demais.	Teste a URL de fora da sua rede; confira o certificado.
a URL não respondeu como uma API Zabbix	A URL aponta para a interface web ou para algo que não devolve JSON-RPC.	Use o caminho completo terminado em `api_jsonrpc.php`.
o Zabbix recusou o token de API	Token inválido, expirado ou de usuário desabilitado. Com usuário e senha: credenciais incorretas.	Gere um token novo ou confira usuário e senha.
a URL aponta para um endereço de rede interna, que não é permitido	A URL resolve para IP privado, loopback ou link-local.	Informe o endereço público do seu Zabbix ou, se ele não tem um, use o Sentrya Connector.
o Zabbix recusou a operação: …	A credencial autenticou, mas o Zabbix negou a chamada.	Leia a mensagem do Zabbix e ajuste as permissões do usuário/token.
falha ao verificar a conexão	Erro inesperado (ex.: resposta maior que o limite aceito).	Tente de novo; se persistir, use Sugestões e relatos.