Configuração do HashiCorp
Visão geral
Esta seção explica como configurar o Zabbix para recuperar segredos do HashiCorp Vault KV Secrets Engine - Versão 2.
O vault deve ser implantado e configurado conforme descrito na documentação oficial da HashiCorp.
Para saber mais sobre como configurar o TLS no Zabbix, consulte Armazenamento de segredos.
Recuperando credenciais do banco de dados
Para recuperar com êxito um segredo com credenciais do banco de dados, é necessário configurar ambos:
- Zabbix server/proxy
- Zabbix frontend
Server/proxy
Para configurar o server ou proxy do Zabbix, especifique os seguintes parâmetros de configuração no arquivo de configuração:
Vault- qual provedor de vault deve ser usado.VaultToken- token de autenticação do vault (consulte o arquivo de configuração do Zabbix server/proxy para obter detalhes); não pode ser usado comVaultAppRoleID.VaultAppRoleIDeVaultAppSecretID- ID da função e ID secreto de autenticação do vault (consulte o arquivo de configuração do Zabbix server/proxy para obter detalhes); não podem ser usados comVaultToken.VaultURL- URL HTTP(S) do server do vault.VaultDBPath- caminho para o segredo do vault que contém as credenciais do banco de dados (essa opção só pode ser usada se DBUser e DBPassword não forem especificados). O Zabbix server ou proxy recuperará as credenciais pelas chaves "password" e "username".VaultPrefix- prefixo personalizado para o caminho ou a consulta do vault, dependendo do vault; se não for especificado, será usado o padrão mais adequado. Observe que o prefixo deve começar e terminar com/.
Os parâmetros de configuração Vault, VaultToken (ou VaultAppRoleID/VaultAppSecretID), VaultURL e VaultPrefix também são usados para a autenticação no vault ao processar macros secretas do vault pelo Zabbix server (e pelo Zabbix proxy, se configurado). O Zabbix server e os proxies não abrirão macros secretas do vault que contenham credenciais do banco de dados de VaultDBPath.
É altamente recomendável usar tokens diferentes para proxies diferentes.
O Zabbix server e o Zabbix proxy leem os parâmetros de configuração relacionados ao vault de zabbix_server.conf e zabbix_proxy.conf durante a inicialização.
Além disso, o Zabbix server e o Zabbix proxy leem a variável de ambiente VAULT_TOKEN uma vez durante a inicialização e a removem para que ela não fique disponível por meio de scripts bifurcados; é um erro se os parâmetros VaultToken e VAULT_TOKEN contiverem um valor.
Exemplo
- Configure os parâmetros do Zabbix server.
Não use os valores de exemplo de token, ID da função ou ID secreto da documentação em ambientes de produção.
- Se estiver usando a variável de ambiente
VAULT_TOKEN, especifique os seguintes parâmetros no arquivo de configuração do server do Zabbix (zabbix_server.conf) e defina a variável:
Vault=HashiCorp
VaultURL=https://127.0.0.1:8200
VaultDBPath=database
VaultPrefix=/v1/secret/data/zabbix/Defina a variável de ambiente VAULT_TOKEN para o Zabbix server antes de iniciá-lo:
export VAULT_TOKEN=hvs.CAESIIG_PILmULFYOsEyWHxkZ2mF2a8VPKNLE8eHqd4autYGGh4KHGh2cy5aeTY0NFNSaUp3ZnpWbDF1RUNjUkNTZEg
zabbix_server -c /etc/zabbix/zabbix_server.conf- Se estiver usando o parâmetro
VaultToken, especifique os seguintes parâmetros no arquivo de configuração do Zabbix server:
Se você usar o parâmetro VaultToken, o token será armazenado em texto simples no arquivo de configuração.
Defina as permissões do arquivo como 0600 para que somente o usuário que executa o Zabbix server ou o proxy possa lê-lo.
Vault=HashiCorp
VaultToken=hvs.CAESIIG_PILmULFYOsEyWHxkZ2mF2a8VPKNLE8eHqd4autYGGh4KHGh2cy5aeTY0NFNSaUp3ZnpWbDF1RUNjUkNTZEg
VaultURL=https://127.0.0.1:8200
VaultDBPath=database
VaultPrefix=/v1/secret/data/zabbix/- Se estiver usando o parâmetro
VaultAppRoleID, especifique os seguintes parâmetros no arquivo de configuração do Zabbix server:
Se você usar o parâmetro VaultAppSecretID, o ID secreto será armazenado em texto simples no arquivo de configuração.
Defina as permissões do arquivo como 0600 para que somente o usuário que executa o Zabbix server ou o proxy possa lê-lo.
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/- Execute os seguintes comandos da CLI para criar o segredo necessário no vault:
# Habilite o ponto de montagem "secret/" se ele 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 no ponto de montagem "secret/" e no 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 o Curl; observe que "data" deve ser adicionado manualmente após o ponto de montagem e "/v1" antes do ponto de montagem; consulte também o parâmetro --capath.
curl --header "X-Vault-Token: <VaultToken>" https://127.0.0.1:8200/v1/secret/data/zabbix/database- Como resultado, o Zabbix server recuperará as seguintes credenciais para autenticação no banco de dados:
- Nome de usuário: zabbix
- Senha: <password>
Frontend
O frontend do Zabbix pode ser configurado para recuperar as 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).
Se as credenciais do vault tiverem sido alteradas desde a instalação anterior do frontend, atualize a configuração existente.
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:
| Parameter | Mandatory | Default value | Description |
|---|---|---|---|
| Store credentials in | no | Selecione HashiCorp Vault. | |
| Vault API endpoint | yes | https://localhost:8200 | Especifique a URL para conexão com o vault no formato scheme://host:port |
| Vault prefix | no | /v1/secret/data/ | Forneça um prefixo personalizado para o caminho ou a consulta do vault. Se não for especificado, o padrão será usado. Exemplo: /v1/secret/data/zabbix/ |
| Vault secret path | yes | Um caminho para o secret do qual as credenciais do banco de dados deverão ser recuperadas pelas chaves "password" e "username". Exemplo: database |
|
| Vault authentication type | no | Selecione o tipo de autenticação do vault: Token - usar autenticação por token; AppRole - usar o método de autenticação AppRole. |
|
| Vault authentication token | yes | Forneça um token de autenticação para acesso somente leitura ao caminho do secret. Consulte a documentação da HashiCorp para obter informações sobre como criar tokens e políticas do vault. Este campo só estará disponível se Token estiver selecionado como o tipo de autenticação do vault. |
|
| Vault authentication role ID | yes | Forneça o ID da role do AppRole. Consulte a documentação da HashiCorp para obter informações sobre AppRoles. Este campo só estará disponível se AppRole estiver selecionado como o tipo de autenticação do vault. |
|
| Vault authentication secret ID | yes | Forneça o ID do secret emitido para o AppRole. Consulte a documentação da HashiCorp para obter informações sobre AppRoles. Este campo só estará disponível se AppRole estiver selecionado como o tipo de autenticação do vault. |
Recuperando valores de macros de usuário
Para usar o HashiCorp Vault para armazenar valores de macros de usuário do tipo 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 Zabbix server (e o Zabbix proxy, se configurado) precisa ter acesso aos valores de macros do tipo Vault secret no vault. O Zabbix frontend não precisa desse acesso.
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 Macros do tipo Vault secret para obter informações detalhadas sobre o processamento dos valores de macros 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
- No Zabbix, adicione uma macro de usuário {$PASSWORD} do tipo "Vault secret" e com o valor
macros:password
- 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- Como resultado, o Zabbix resolverá a macro {$PASSWORD} para o valor: <password>
Atualizando a configuração existente
Para atualizar uma configuração existente para recuperar segredos de um HashiCorp Vault:
-
Atualize os parâmetros do arquivo de configuração do Zabbix server ou proxy, conforme descrito na seção Credenciais do banco de dados.
-
Atualize os parâmetros do arquivo de configuração do frontend do Zabbix:
Usando um 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 AppRole do Vault:
$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/';- Configure as 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
- 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 (re)iniciado, mas não foi desbloqueado (necessário na configuração padrão; não é necessário se o Auto Unseal estiver configurado).
- 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.