Configurazione HashiCorp
Panoramica
Questa sezione spiega come configurare Zabbix per recuperare i segreti da HashiCorp Vault KV Secrets Engine - Versione 2.
Il vault deve essere distribuito e configurato come descritto nella documentazione ufficiale di HashiCorp.
Per informazioni sulla configurazione di TLS in Zabbix, vedere Archiviazione dei segreti.
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 il server o il proxy Zabbix, specificare i seguenti parametri di configurazione nel file di configurazione:
Vault- provider del vault da utilizzare.VaultToken- token di autenticazione del vault (vedere il file di configurazione del server/proxy Zabbix per i dettagli); non può essere utilizzato conVaultAppRoleID.VaultAppRoleIDeVaultAppSecretID- ID del ruolo e ID secret per l'autenticazione del vault (vedere il file di configurazione del server/proxy Zabbix per i dettagli); non possono essere utilizzati conVaultToken.VaultURL- URL HTTP(S) del server vault.VaultDBPath- percorso del secret del vault contenente le credenziali del database (questa opzione può essere utilizzata solo se DBUser e DBPassword non sono specificati). Il server o il proxy Zabbix 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à utilizzato il valore predefinito più appropriato. Il prefisso deve iniziare e terminare con/.
I parametri di configurazione Vault, VaultToken (oppure VaultAppRoleID/VaultAppSecretID), VaultURL e VaultPrefix vengono utilizzati anche per l'autenticazione del vault durante l'elaborazione delle macro secret del vault da parte del server Zabbix (e del proxy Zabbix, se configurato). Il server Zabbix e i proxy non apriranno le macro secret del vault che contengono le credenziali DB provenienti da VaultDBPath.
Si consiglia vivamente di utilizzare token diversi per proxy diversi.
Il server Zabbix e il proxy Zabbix leggono i parametri di configurazione relativi al vault da zabbix_server.conf e zabbix_proxy.conf all'avvio.
Inoltre, il server Zabbix e il proxy Zabbix leggono la variabile d'ambiente VAULT_TOKEN una volta durante l'avvio e la annullano, in modo che non sia disponibile tramite gli script forked; si verifica un errore se entrambi i parametri VaultToken e VAULT_TOKEN contengono un valore.
Esempio
- Configurare i parametri del server Zabbix.
Non utilizzare in ambienti di produzione i valori di esempio di token, ID ruolo o ID segreto riportati nella documentazione.
- Se si utilizza la variabile d'ambiente
VAULT_TOKEN, specificare i seguenti parametri nel file di configurazione del server Zabbix (zabbix_server.conf) e impostare la variabile:
Vault=HashiCorp
VaultURL=https://127.0.0.1:8200
VaultDBPath=database
VaultPrefix=/v1/secret/data/zabbix/Impostare la variabile d'ambiente VAULT_TOKEN per il server Zabbix prima dell'avvio:
export VAULT_TOKEN=hvs.CAESIIG_PILmULFYOsEyWHxkZ2mF2a8VPKNLE8eHqd4autYGGh4KHGh2cy5aeTY0NFNSaUp3ZnpWbDF1RUNjUkNTZEg
zabbix_server -c /etc/zabbix/zabbix_server.conf- Se si utilizza il parametro
VaultToken, specificare i seguenti parametri nel file di configurazione del server Zabbix:
Se si utilizza il parametro VaultToken, il token viene memorizzato in testo normale nel file di configurazione.
Impostare i permessi del file su 0600, in modo che solo l'utente che esegue il server Zabbix o il proxy possa leggerlo.
Vault=HashiCorp
VaultToken=hvs.CAESIIG_PILmULFYOsEyWHxkZ2mF2a8VPKNLE8eHqd4autYGGh4KHGh2cy5aeTY0NFNSaUp3ZnpWbDF1RUNjUkNTZEg
VaultURL=https://127.0.0.1:8200
VaultDBPath=database
VaultPrefix=/v1/secret/data/zabbix/- Se si utilizza il parametro
VaultAppRoleID, specificare i seguenti parametri nel file di configurazione del server Zabbix:
Se si utilizza il parametro VaultAppSecretID, l'ID segreto viene memorizzato in testo normale nel file di configurazione.
Impostare i permessi del file su 0600, in modo che solo l'utente che esegue il server Zabbix o il proxy possa leggerlo.
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/- Eseguire i seguenti comandi CLI per creare il secret richiesto nel vault:
# Abilitare il punto di montaggio "secret/" se non è già abilitato; tenere presente che è necessario utilizzare "kv-v2".
vault secrets enable -path=secret/ kv-v2
# Inserire nuovi secret con le chiavi username e password nel punto di montaggio "secret/" e nel percorso "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, eseguire un test con Curl; tenere presente che è necessario aggiungere manualmente "data" dopo il punto di montaggio e "/v1" prima del punto di montaggio; vedere anche il parametro --capath.
curl --header "X-Vault-Token: <VaultToken>" https://127.0.0.1:8200/v1/secret/data/zabbix/database- Di conseguenza, il server Zabbix recupererà le seguenti credenziali per l'autenticazione al database:
- Nome utente: zabbix
- Password: <password>
frontend
Il frontend di Zabbix 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 cambiate dall'installazione precedente del frontend, aggiornare la configurazione esistente.
Durante l'installazione del frontend, i parametri di connessione devono essere specificati nel passaggio Configure DB Connection.
Esempio di configurazione con autenticazione tramite token:
Esempio di configurazione con autenticazione AppRole:
| Parametro | Obbligatorio | Valore predefinito | Descrizione |
|---|---|---|---|
| Store credentials in | no | Selezionare HashiCorp Vault. | |
| Vault API endpoint | sì | https://localhost:8200 | Specificare l'URL per la connessione al vault nel formato scheme://host:port |
| Vault prefix | no | /v1/secret/data/ | Specificare un prefisso personalizzato per il percorso o la query del vault. Se non specificato, viene utilizzato il valore predefinito. Esempio: /v1/secret/data/zabbix/ |
| Vault secret path | sì | Percorso del secret dal quale le credenziali del database devono essere recuperate tramite le chiavi "password" e "username". Esempio: database |
|
| Vault authentication type | no | Selezionare il tipo di autenticazione del vault: Token - utilizza l'autenticazione tramite token; AppRole - utilizza il metodo di autenticazione AppRole. |
|
| Vault authentication token | sì | Fornire un token di autenticazione per l'accesso in sola lettura al percorso del secret. Per informazioni sulla creazione di token e policy del vault, consultare la documentazione di HashiCorp. Questo campo è disponibile solo se Token è selezionato come tipo di autenticazione del vault. |
|
| Vault authentication role ID | sì | Fornire l'ID del ruolo dell'AppRole. Per informazioni sulle AppRole, consultare la documentazione di HashiCorp. Questo campo è disponibile solo se AppRole è selezionato come tipo di autenticazione del vault. |
|
| Vault authentication secret ID | sì | Fornire il secret ID emesso per l'AppRole. Per informazioni sulle AppRole, consultare la documentazione di HashiCorp. Questo campo è disponibile solo se AppRole è selezionato come tipo di autenticazione del vault. |
Recupero dei valori delle macro utente
Per utilizzare HashiCorp Vault per archiviare i valori delle macro utente di tipo Vault secret, assicurarsi che:
- Zabbix server/proxy sia configurato per funzionare con HashiCorp Vault.
- Il parametro Vault provider in Administration > General > Other sia impostato su "HashiCorp Vault" (predefinito).
Zabbix server (e Zabbix proxy, se configurato) richiede l'accesso ai valori delle macro Vault secret dal vault. Il frontend di Zabbix non necessita di tale accesso.
Il valore della macro deve contenere un percorso di riferimento (nel formato path:key, ad esempio macros:password).
Il token di autenticazione specificato durante la configurazione di Zabbix server/proxy (tramite il parametro VaultToken) deve fornire l'accesso in sola lettura a questo percorso.
Per informazioni dettagliate sull'elaborazione dei valori delle macro da parte di Zabbix, vedere Macro Vault secret.
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
- In Zabbix, aggiungi una macro utente {$PASSWORD} di tipo "Vault secret" e con valore
macros:password
- 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- 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:
-
Aggiornare i parametri del file di configurazione del server o del proxy Zabbix come descritto nella sezione Credenziali del database.
-
Aggiornare i parametri del file di configurazione del frontend di Zabbix:
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, utilizzando 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/';- 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 di CyberArk.
Risoluzione dei problemi
- Nel file di log del server/proxy Zabbix:
237839:20260729:130916.425 Vault token renew started to fail: cannot login into HashiCorp vault with AppRole method: unsuccessful response code "503"Causa probabile: HashiCorp Vault è stato riavviato, ma non è stato effettuato l'unseal (operazione richiesta nella configurazione predefinita, ma non necessaria se è configurato Auto Unseal).
- Nel file di log del server/proxy Zabbix:
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"Causa probabile: VaultAppSecretID è scaduto o ha raggiunto il limite di utilizzo in HashiCorp Vault.