Configuração do HashiCorp

Visão geral

Esta seção explica como configurar o Zabbix para recuperar segredos do HashiCorp Vault KV Secrets Engine - Version 2.

O vault deve ser implantado e configurado conforme descrito na documentação oficial da HashiCorp.

Para saber mais sobre como configurar TLS no Zabbix, consulte Storage of secrets.

Recuperando credenciais do banco de dados

Para recuperar com sucesso um segredo com credenciais do banco de dados, é necessário configurar ambos:

• Zabbix server/proxy
• Zabbix frontend

Server/proxy

Para configurar o Zabbix server ou proxy, especifique os seguintes parâmetros de configuração no arquivo de configuração:

• Vault - qual provedor de cofre deve ser usado;
• VaultToken - token de autenticação do cofre (consulte o arquivo de configuração do Zabbix server/proxy para detalhes); não pode ser usado com VaultAppRoleID;
• VaultAppRoleID e VaultAppSecretID - ID da função de autenticação do cofre e ID secreto (consulte o arquivo de configuração do Zabbix server/proxy para detalhes); não podem ser usados com VaultToken;
• VaultURL - URL HTTP[S] do servidor do cofre;
• VaultDBPath - caminho para o segredo do cofre que contém as credenciais do banco de dados (esta opção só pode ser usada se DBUser e DBPassword não estiverem especificados); o Zabbix server ou proxy recuperará as credenciais pelas chaves "password" e "username";
• VaultPrefix - prefixo personalizado para o caminho ou consulta do cofre, dependendo do cofre; se não for especificado, será usado o padrão mais adequado.

O Zabbix server e o Zabbix proxy leem os parâmetros de configuração relacionados ao cofre de zabbix_server.conf e zabbix_proxy.conf na inicialização. Além disso, o Zabbix server e o Zabbix proxy lerão a variável de ambiente VAULT_TOKEN uma vez durante a inicialização e a removerão, para que ela não fique disponível por meio de scripts filhos; é um erro se os parâmetros VaultToken e VAULT_TOKEN contiverem um valor.

Exemplo

1. Em zabbix_server.conf, especifique os seguintes parâmetros.

Usando VaultToken:

Vault=HashiCorp
VaultToken=hvs.CAESIIG_PILmULFYOsEyWHxkZ2mF2a8VPKNLE8eHqd4autYGGh4KHGh2cy5aeTY0NFNSaUp3ZnpWbDF1RUNjUkNTZEg
VaultURL=https://127.0.0.1:8200
VaultDBPath=database
VaultPrefix=/v1/secret/data/zabbix/

Ou, usando VaultAppRoleID:

Vault=HashiCorp
VaultAppRoleID=6f1567f1-538d-7d70-e8e4-5d3e59471b2e
VaultAppSecretID=89dac8b1-f7d6-96a7-2ecf-f94d2de3d6f1
VaultURL=https://127.0.0.1:8200
VaultDBPath=database
VaultPrefix=/v1/secret/data/zabbix/

2. Execute os seguintes comandos CLI para criar o segredo necessário no vault:

# Habilite o ponto de montagem "secret/" se ainda não estiver habilitado; observe que "kv-v2" deve ser usado.
vault secrets enable -path=secret/ kv-v2

# Adicione novos segredos com as chaves username e password sob o ponto de montagem "secret/" e o caminho "zabbix/database".
vault kv put -mount=secret zabbix/database username=zabbix password=<password>

# Teste se o segredo foi adicionado com sucesso.
vault kv get secret/zabbix/database

# Por fim, teste com Curl; observe que "data" precisa ser adicionado manualmente após o ponto de montagem e "/v1" antes do ponto de montagem; veja também o parâmetro --capath.
curl --header "X-Vault-Token: <VaultToken>" https://127.0.0.1:8200/v1/secret/data/zabbix/database

3. Como resultado, o server Zabbix recuperará as seguintes credenciais para autenticação no banco de dados:

• Username: zabbix
• Password: <password>

Frontend

O frontend do Zabbix pode ser configurado para recuperar credenciais do banco de dados do vault durante a instalação do frontend ou atualizando o arquivo de configuração do frontend (zabbix.conf.php).

Durante a instalação do frontend, os parâmetros de conexão devem ser especificados na etapa Configure DB Connection.

Exemplo de configuração usando autenticação por token:

Exemplo de configuração usando autenticação AppRole:

Recuperando valores de macro de usuário

Para usar o HashiCorp Vault para armazenar valores de macro de usuário Vault secret, certifique-se de que:

• O Zabbix server/proxy esteja configurado para funcionar com o HashiCorp Vault.
• O parâmetro Vault provider em Administration > General > Other esteja definido como "HashiCorp Vault" (padrão).

O valor da macro deve conter um caminho de referência (como path:key, por exemplo, macros:password). O token de autenticação especificado durante a configuração do Zabbix server/proxy (pelo parâmetro VaultToken) deve fornecer acesso somente leitura a esse caminho.

Consulte Vault secret macros para obter informações detalhadas sobre o processamento do valor da macro pelo Zabbix.

Sintaxe do caminho

Os símbolos barra ("/") e dois-pontos (":") são reservados.

Uma barra só pode ser usada para separar um ponto de montagem de um caminho (por exemplo, secret/zabbix, em que o ponto de montagem é "secret" e o caminho é "zabbix"). No caso de macros do Vault, um dois-pontos só pode ser usado para separar um caminho/consulta de uma chave.

É possível codificar os símbolos barra e dois-pontos em URL se houver necessidade de criar um ponto de montagem com um nome que contenha uma barra (por exemplo, foo/bar/zabbix, em que o ponto de montagem é "foo/bar" e o caminho é "zabbix", pode ser codificado como "foo%2Fbar/zabbix") e se o nome de um ponto de montagem ou caminho precisar conter um dois-pontos.

Exemplo

1. No Zabbix, adicione uma macro de usuário {$PASSWORD} do tipo "Vault secret" e com o valor macros:password

2. Execute os seguintes comandos CLI para criar o secret necessário no vault:

# Habilite o ponto de montagem "secret/" se ainda não estiver habilitado; observe que "kv-v2" deve ser usado.
vault secrets enable -path=secret/ kv-v2

# Adicione um novo secret com a chave "password" sob o ponto de montagem "secret/" e o caminho "zabbix/macros".
vault kv put -mount=secret zabbix/macros password=<password>

# Teste se o secret foi adicionado com sucesso.
vault kv get secret/zabbix/macros

# Por fim, teste com Curl; observe que "data" precisa ser adicionado manualmente após o ponto de montagem e "/v1" antes do ponto de montagem; veja também o parâmetro --capath.
curl --header "X-Vault-Token: <VaultToken>" https://127.0.0.1:8200/v1/secret/data/zabbix/macros

3. Como resultado, o Zabbix resolverá a macro {$PASSWORD} para o valor: <password>

Atualizando uma configuração existente

Para atualizar uma configuração existente para recuperar segredos de um HashiCorp Vault:

1. Atualize os parâmetros do arquivo de configuração do Zabbix server ou proxy conforme descrito na seção Credenciais do banco de dados.

2. Atualize as configurações de conexão com o banco de dados reconfigurando o Zabbix frontend e especificando os parâmetros necessários conforme descrito na seção Frontend. Para reconfigurar o Zabbix frontend, abra a URL de configuração do frontend no navegador:

• para Apache: http://<server_ip_or_name>/zabbix/setup.php
• para Nginx: http://<server_ip_or_name>/setup.php

Como alternativa, esses parâmetros podem ser definidos no arquivo de configuração do frontend (zabbix.conf.php).

Usando token do Vault:

$DB['VAULT']                    = 'HashiCorp';
$DB['VAULT_URL']                = 'https://localhost:8200';
$DB['VAULT_DB_PATH']            = 'database';
$DB['VAULT_TOKEN']              = 'hvs.CAESIIG_PILmULFYOsEyWHxkZ2mF2a8VPKNLE8eHqd4autYGGh4KHGh2cy5aeTY0NFNSaUp3ZnpWbDF1RUNjUkNTZEg';
$DB['VAULT_PREFIX']             = '/v1/secret/data/zabbix/';

Ou, usando o método Vault AppRole:

$DB['VAULT']                    = 'HashiCorp';
$DB['VAULT_URL']                = 'https://localhost:8200';
$DB['VAULT_DB_PATH']            = 'database';
$DB['VAULT_APP_ROLE_ID']        = '6f1567f1-538d-7d70-e8e4-5d3e59471b2e';
$DB['VAULT_APP_SECRET_ID']      = '89dac8b1-f7d6-96a7-2ecf-f94d2de3d6f1';
$DB['VAULT_PREFIX']             = '/v1/secret/data/zabbix/';

3. Configure macros de usuário conforme descrito na seção Valores de macros de usuário, se necessário.

Para atualizar uma configuração existente para recuperar segredos de um CyberArk Vault, consulte Configuração do CyberArk.

Solução de problemas

1. No arquivo de log do Zabbix server/proxy:

237839:20260729:130916.425 Vault token renew started to fail: cannot login into HashiCorp vault with AppRole method: unsuccessful response code "503"

Causa provável: o HashiCorp Vault foi (reiniciado), mas não foi desbloqueado (necessário na configuração padrão, não necessário se o Auto Unseal estiver configurado).

2. No arquivo de log do Zabbix server/proxy:

235545:20260729:125617.944 Vault token renew started to fail: cannot login into HashiCorp vault with AppRole method: unsuccessful response code "400"

ou

235545:20260729:125718.537 Vault token renew failed: cannot login into HashiCorp vault with AppRole method: unsuccessful response code "400"

Causa provável: VaultAppSecretID expirou ou atingiu seu limite de uso no HashiCorp vault.