Configurazione HashiCorp

Panoramica

Questa sezione spiega come configurare Zabbix per recuperare i secret da HashiCorp Vault KV Secrets Engine - Version 2.

Il vault deve essere distribuito e configurato come descritto nella documentazione ufficiale di HashiCorp.

Per informazioni sulla configurazione di TLS in Zabbix, vedere Storage of secrets.

Recupero delle credenziali del database

Per recuperare correttamente un secret con le credenziali del database, è necessario configurare entrambi:

  • Zabbix server/proxy
  • Zabbix frontend
Server/proxy

Per configurare Zabbix server o proxy, specificare i seguenti parametri di configurazione nel file di configurazione:

  • Vault - quale provider vault deve essere utilizzato;
  • VaultToken - token di autenticazione del vault (vedere il file di configurazione di Zabbix server/proxy per i dettagli); non può essere usato con VaultAppRoleID;
  • VaultAppRoleID e VaultAppSecretID - ID del ruolo di autenticazione del vault e secret ID (vedere il file di configurazione di Zabbix server/proxy per i dettagli); non possono essere usati con VaultToken;
  • VaultURL - URL HTTP[S] del server vault;
  • VaultDBPath - percorso del secret del vault contenente le credenziali del database (questa opzione può essere usata solo se DBUser e DBPassword non sono specificati); Zabbix server o proxy recupererà le credenziali tramite le chiavi "password" e "username";
  • VaultPrefix - prefisso personalizzato per il percorso o la query del vault, a seconda del vault; se non specificato, verrà usato il valore predefinito più adatto.

I parametri di configurazione Vault, VaultToken (o VaultAppRoleID/VaultAppSecretID), VaultURL e VaultPrefix sono utilizzati anche per l'autenticazione al vault durante l'elaborazione delle macro secret vault da parte di Zabbix server (e di Zabbix proxy, se configurato). Zabbix server e i proxy non apriranno le macro secret vault che contengono credenziali DB da VaultDBPath.

Si raccomanda vivamente di usare token diversi per proxy diversi.

Zabbix server e Zabbix proxy leggono i parametri di configurazione relativi al vault da zabbix_server.conf e zabbix_proxy.conf all'avvio. Inoltre, Zabbix server e Zabbix proxy leggeranno la variabile di ambiente VAULT_TOKEN una sola volta durante l'avvio e la annulleranno in modo che non sia disponibile tramite script forkati; è un errore se sia VaultToken sia VAULT_TOKEN contengono un valore.

Esempio

  1. In zabbix_server.conf, specificare i seguenti parametri.

Usando VaultToken:

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

Oppure, 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/
  1. Eseguire i seguenti comandi CLI per creare il secret richiesto nel vault:
# Abilitare il punto di mount "secret/" se non è già abilitato; notare che deve essere usato "kv-v2".
vault secrets enable -path=secret/ kv-v2

# Inserire nuovi secret con le chiavi username e password sotto il punto di mount "secret/" e il path "zabbix/database".
vault kv put -mount=secret zabbix/database username=zabbix password=<password>

# Verificare che il secret sia stato aggiunto correttamente.
vault kv get secret/zabbix/database

# Infine testare con Curl; notare che "data" deve essere aggiunto manualmente dopo il punto di mount e "/v1" prima del punto di mount, vedere anche il parametro --capath.
curl --header "X-Vault-Token: <VaultToken>" https://127.0.0.1:8200/v1/secret/data/zabbix/database
  1. Di conseguenza, il server Zabbix recupererà le seguenti credenziali per l'autenticazione al database:
  • Username: zabbix
  • Password: <password>
Frontend

Zabbix frontend può essere configurato per recuperare le credenziali del database dal vault durante l'installazione del frontend oppure aggiornando il file di configurazione del frontend (zabbix.conf.php).

Se le credenziali del vault sono state modificate dopo la precedente installazione del frontend, eseguire nuovamente l'installazione del frontend oppure aggiornare zabbix.conf.php. Vedi anche: Aggiornamento della configurazione esistente.

Durante l'installazione del frontend i parametri di connessione devono essere specificati nella fase Configure DB Connection.

Esempio di configurazione con autenticazione tramite token:

Esempio di configurazione con autenticazione AppRole:

Parameter Mandatory Default value Description
Store credentials in no Selezionare HashiCorp Vault.
Vault API endpoint yes https://localhost:8200 Specificare l'URL per la connessione al vault nel formato scheme://host:port
Vault prefix no /v1/secret/data/ Fornire un prefisso personalizzato per il percorso o la query del vault. Se non specificato, viene usato quello predefinito.
Esempio: /v1/secret/data/zabbix/
Vault secret path yes Un percorso al secret da cui le credenziali per il database devono essere recuperate tramite le chiavi "password" e "username".
Esempio: database
Vault authentication type no Selezionare il tipo di autenticazione del vault:
Token - usa l'autenticazione tramite token;
AppRole - usa il metodo di autenticazione AppRole.
Vault authentication token yes Fornire un token di autenticazione per l'accesso in sola lettura al percorso del secret.
Vedere la documentazione HashiCorp per informazioni sulla creazione dei token e delle policy del vault.
Questo campo è disponibile solo se come tipo di autenticazione del vault è selezionato Token.
Vault authentication role ID yes Fornire l'ID del ruolo dell'AppRole.
Vedere la documentazione HashiCorp per informazioni sugli AppRole.
Questo campo è disponibile solo se come tipo di autenticazione del vault è selezionato AppRole.
Vault authentication secret ID yes Fornire il secret ID emesso per l'AppRole.
Vedere la documentazione HashiCorp per informazioni sugli AppRole.
Questo campo è disponibile solo se come tipo di autenticazione del vault è selezionato AppRole.

Recupero dei valori delle macro utente

Per utilizzare HashiCorp Vault per memorizzare i valori delle macro utente Vault secret, assicurarsi che:

Zabbix server (e Zabbix proxy, se configurato) richiedono l'accesso ai valori delle macro Vault secret dal vault. Zabbix frontend non necessita di tale accesso.

Il valore della macro dovrebbe contenere un percorso di riferimento (come path:key, ad esempio macros:password). Il token di autenticazione specificato durante la configurazione di Zabbix server/proxy (tramite il parametro VaultToken) deve fornire accesso in sola lettura a questo percorso.

Per informazioni dettagliate sull'elaborazione dei valori delle macro da parte di Zabbix, vedere Vault secret macros.

Sintassi del percorso

I simboli barra obliqua ("/") e due punti (":") sono riservati.

Una barra obliqua può essere usata solo per separare un mount point da un percorso (ad esempio, secret/zabbix, dove il mount point è "secret" e il percorso è "zabbix"). Nel caso delle macro di Vault, i due punti possono essere usati solo per separare un percorso/query da una chiave.

È possibile codificare in URL i simboli barra obliqua e due punti se è necessario creare un mount point con un nome separato da una barra obliqua (ad esempio, foo/bar/zabbix, dove il mount point è "foo/bar" e il percorso è "zabbix", può essere codificato come "foo%2Fbar/zabbix") e se il nome di un mount point o un percorso deve contenere due punti.

Esempio

  1. In Zabbix, aggiungi una macro utente {$PASSWORD} di tipo "Vault secret" e con valore macros:password

  1. Esegui i seguenti comandi CLI per creare il secret richiesto nel vault:
# Abilita il punto di mount "secret/" se non è già abilitato; nota che deve essere usato "kv-v2".
vault secrets enable -path=secret/ kv-v2

# Inserisci un nuovo secret con chiave "password" sotto il punto di mount "secret/" e il percorso "zabbix/macros".
vault kv put -mount=secret zabbix/macros password=<password>

# Verifica che il secret sia stato aggiunto correttamente.
vault kv get secret/zabbix/macros

# Infine verifica con Curl; nota che "data" deve essere aggiunto manualmente dopo il punto di mount e "/v1" prima del punto di mount, vedi anche il parametro --capath.
curl --header "X-Vault-Token: <VaultToken>" https://127.0.0.1:8200/v1/secret/data/zabbix/macros
  1. Di conseguenza, Zabbix risolverà la macro {$PASSWORD} nel valore: <password>

Aggiornamento della configurazione esistente

Per aggiornare una configurazione esistente per il recupero dei segreti da HashiCorp Vault:

  1. Aggiornare i parametri del file di configurazione di Zabbix server o proxy come descritto nella sezione Credenziali del database.

  2. Aggiornare le impostazioni di connessione al DB riconfigurando Zabbix frontend e specificando i parametri richiesti come descritto nella sezione Frontend. Per riconfigurare Zabbix frontend, aprire l'URL di configurazione del frontend nel browser:

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

In alternativa, questi parametri possono essere impostati nel file di configurazione del frontend (zabbix.conf.php).

Utilizzando il token 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/';

Oppure, usando il metodo 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/';
  1. Configurare le macro utente come descritto nella sezione Valori delle macro utente, se necessario.

Per aggiornare una configurazione esistente per il recupero dei segreti da CyberArk Vault, vedere Configurazione CyberArk.

Risoluzione dei problemi

  1. Nel file di log di 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"

Probabile causa: HashiCorp Vault è stato (ri)avviato, ma non è stato unsealed (richiesto nella configurazione predefinita, non richiesto se è configurato Auto Unseal).

  1. Nel file di log di 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"

oppure

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

Probabile causa: VaultAppSecretID è scaduto oppure ha raggiunto il limite di utilizzo in HashiCorp vault.