Configuration HashiCorp

Vue d’ensemble

Cette section explique comment configurer Zabbix pour récupérer des secrets depuis le moteur de secrets KV de HashiCorp Vault - version 2.

Le vault doit être déployé et configuré comme décrit dans la documentation officielle de HashiCorp.

Pour en savoir plus sur la configuration de TLS dans Zabbix, consultez Stockage des secrets.

Récupération des identifiants de la base de données

Pour récupérer correctement un secret contenant les identifiants de la base de données, il est nécessaire de configurer les deux éléments suivants :

  • Le serveur/proxy Zabbix
  • L'interface Zabbix

Serveur/proxy

Pour configurer le serveur ou le proxy Zabbix, spécifiez les paramètres de configuration suivants dans le fichier de configuration :

  • Vault - fournisseur de coffre-fort à utiliser.
  • VaultToken - jeton d'authentification du coffre-fort (voir le fichier de configuration du serveur/proxy Zabbix pour plus de détails) ; ne peut pas être utilisé avec VaultAppRoleID.
  • VaultAppRoleID et VaultAppSecretID - ID de rôle et ID secret d'authentification du coffre-fort (voir le fichier de configuration du serveur/proxy Zabbix pour plus de détails) ; ne peuvent pas être utilisés avec VaultToken.
  • VaultURL - URL HTTP(S) du serveur du coffre-fort.
  • VaultDBPath - chemin vers le secret du coffre-fort contenant les identifiants de la base de données (cette option ne peut être utilisée que si DBUser et DBPassword ne sont pas spécifiés). Le serveur ou le proxy Zabbix récupérera les identifiants à l'aide des clés "password" et "username".
  • VaultPrefix - préfixe personnalisé pour le chemin ou la requête du coffre-fort, selon le coffre-fort ; s'il n'est pas spécifié, la valeur par défaut la plus appropriée sera utilisée. Notez que le préfixe doit commencer et se terminer par /.

Les paramètres de configuration Vault, VaultToken (ou VaultAppRoleID/VaultAppSecretID), VaultURL et VaultPrefix sont également utilisés pour l'authentification auprès du coffre-fort lors du traitement des macros secrètes du coffre-fort par le serveur Zabbix (et par le proxy Zabbix, s'il est configuré). Le serveur Zabbix et les proxies n'ouvriront pas les macros secrètes du coffre-fort contenant les identifiants de la base de données provenant de VaultDBPath.

L'utilisation de jetons différents pour différents proxies est fortement recommandée.

Le serveur Zabbix et le proxy Zabbix lisent les paramètres de configuration liés au coffre-fort depuis zabbix_server.conf et zabbix_proxy.conf au démarrage.

De plus, le serveur Zabbix et le proxy Zabbix lisent la variable d'environnement VAULT_TOKEN une fois au démarrage et la désactivent afin qu'elle ne soit pas accessible par l'intermédiaire de scripts forkés ; une erreur se produit si les paramètres VaultToken et VAULT_TOKEN contiennent tous deux une valeur.

Exemple
  1. Configurez les paramètres du serveur Zabbix.

N'utilisez pas les valeurs d'exemple du token, de l'ID de rôle ou de l'ID secret fournies dans la documentation dans les environnements de production.

  • Si vous utilisez la variable d'environnement VAULT_TOKEN, spécifiez les paramètres suivants dans le fichier de configuration du serveur Zabbix (zabbix_server.conf) et définissez la variable :
Vault=HashiCorp
VaultURL=https://127.0.0.1:8200
VaultDBPath=database
VaultPrefix=/v1/secret/data/zabbix/

Définissez la variable d'environnement VAULT_TOKEN pour le serveur Zabbix avant son démarrage :

export VAULT_TOKEN=hvs.CAESIIG_PILmULFYOsEyWHxkZ2mF2a8VPKNLE8eHqd4autYGGh4KHGh2cy5aeTY0NFNSaUp3ZnpWbDF1RUNjUkNTZEg
zabbix_server -c /etc/zabbix/zabbix_server.conf
  • Si vous utilisez le paramètre VaultToken, spécifiez les paramètres suivants dans le fichier de configuration du serveur Zabbix :

Si vous utilisez le paramètre VaultToken, le token est stocké en texte brut dans le fichier de configuration. Définissez les permissions du fichier sur 0600 afin que seul l'utilisateur exécutant le serveur Zabbix ou le proxy puisse le lire.

Vault=HashiCorp
VaultToken=hvs.CAESIIG_PILmULFYOsEyWHxkZ2mF2a8VPKNLE8eHqd4autYGGh4KHGh2cy5aeTY0NFNSaUp3ZnpWbDF1RUNjUkNTZEg
VaultURL=https://127.0.0.1:8200
VaultDBPath=database
VaultPrefix=/v1/secret/data/zabbix/
  • Si vous utilisez le paramètre VaultAppRoleID, spécifiez les paramètres suivants dans le fichier de configuration du serveur Zabbix :

Si vous utilisez le paramètre VaultAppSecretID, l'ID secret est stocké en texte brut dans le fichier de configuration. Définissez les permissions du fichier sur 0600 afin que seul l'utilisateur exécutant le serveur Zabbix ou le proxy puisse le lire.

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. Exécutez les commandes CLI suivantes pour créer le secret requis dans le coffre :
# Activez le point de montage « secret/ » s'il n'est pas déjà activé ; notez que « kv-v2 » doit être utilisé.
vault secrets enable -path=secret/ kv-v2

# Ajoutez de nouveaux secrets avec les clés username et password sous le point de montage « secret/ » et le chemin « zabbix/database ».
vault kv put -mount=secret zabbix/database username=zabbix password=<password>

# Vérifiez que le secret a bien été ajouté.
vault kv get secret/zabbix/database

# Effectuez enfin un test avec Curl ; notez que « data » doit être ajouté manuellement après le point de montage et « /v1 » avant le point de montage ; consultez également le paramètre --capath.
curl --header "X-Vault-Token: <VaultToken>" https://127.0.0.1:8200/v1/secret/data/zabbix/database
  1. Par conséquent, le serveur Zabbix récupérera les identifiants suivants pour l'authentification à la base de données :
  • Nom d'utilisateur : zabbix
  • Mot de passe : <password>

Interface

L’interface Zabbix peut être configurée pour récupérer les identifiants de la base de données depuis le coffre-fort, soit lors de l’installation de l’interface, soit en mettant à jour le fichier de configuration de l’interface (zabbix.conf.php).

Si les identifiants du coffre-fort ont changé depuis l’installation précédente de l’interface, mettez à jour la configuration existante.

Lors de l’installation de l’interface, les paramètres de connexion doivent être spécifiés à l’étape Configure DB Connection.

Exemple de configuration utilisant l’authentification par jeton :

Exemple de configuration utilisant l’authentification AppRole :

Paramètre Obligatoire Valeur par défaut Description
Store credentials in non Sélectionnez HashiCorp Vault.
Vault API endpoint oui https://localhost:8200 Spécifiez l’URL de connexion au coffre-fort au format scheme://host:port
Vault prefix non /v1/secret/data/ Indiquez un préfixe personnalisé pour le chemin ou la requête du coffre-fort. S’il n’est pas spécifié, la valeur par défaut est utilisée.
Exemple : /v1/secret/data/zabbix/
Vault secret path oui Chemin vers le secret à partir duquel les identifiants de la base de données doivent être récupérés à l’aide des clés « password » et « username ».
Exemple : database
Vault authentication type non Sélectionnez le type d’authentification du coffre-fort :
Token - utiliser l’authentification par jeton ;
AppRole - utiliser la méthode d’authentification AppRole.
Vault authentication token oui Indiquez un jeton d’authentification permettant un accès en lecture seule au chemin du secret.
Consultez la documentation HashiCorp pour obtenir des informations sur la création de jetons et les stratégies du coffre-fort.
Ce champ est disponible uniquement si Token est sélectionné comme type d’authentification du coffre-fort.
Vault authentication role ID oui Indiquez l’ID de rôle de l’AppRole.
Consultez la documentation HashiCorp pour obtenir des informations sur les AppRoles.
Ce champ est disponible uniquement si AppRole est sélectionné comme type d’authentification du coffre-fort.
Vault authentication secret ID oui Indiquez l’ID secret attribué à l’AppRole.
Consultez la documentation HashiCorp pour obtenir des informations sur les AppRoles.
Ce champ est disponible uniquement si AppRole est sélectionné comme type d’authentification du coffre-fort.

Récupération des valeurs des macros utilisateur

Pour utiliser HashiCorp Vault afin de stocker les valeurs des macros utilisateur de type secret Vault, assurez-vous que :

Le serveur Zabbix (ainsi que le proxy Zabbix, s'il est configuré) doit pouvoir accéder aux valeurs des macros de type secret Vault dans le coffre. L'interface Zabbix n'a pas besoin de cet accès.

La valeur de la macro doit contenir un chemin de référence (au format path:key, par exemple macros:password). Le jeton d'authentification spécifié lors de la configuration du serveur/proxy Zabbix (à l'aide du paramètre VaultToken) doit fournir un accès en lecture seule à ce chemin.

Consultez Macros de type secret Vault pour obtenir des informations détaillées sur le traitement des valeurs des macros par Zabbix.

Syntaxe du chemin

Les symboles barre oblique ("/") et deux-points (":") sont réservés.

Une barre oblique ne peut être utilisée que pour séparer un point de montage d'un chemin (par exemple, secret/zabbix, où le point de montage est "secret" et le chemin est "zabbix"). Dans le cas des macros Vault, un deux-points ne peut être utilisé que pour séparer un chemin/requête d'une clé.

Il est possible d'encoder en URL les symboles barre oblique et deux-points s'il est nécessaire de créer un point de montage dont le nom contient une barre oblique (par exemple, foo/bar/zabbix, où le point de montage est "foo/bar" et le chemin est "zabbix", peut être encodé en "foo%2Fbar/zabbix") et si le nom d'un point de montage ou un chemin doit contenir un deux-points.

Exemple

  1. Dans Zabbix, ajoutez une macro utilisateur {$PASSWORD} de type "Vault secret" et avec la valeur macros:password

  1. Exécutez les commandes CLI suivantes pour créer le secret requis dans le vault :
# Activer le point de montage "secret/" s'il n'est pas déjà activé ; notez que "kv-v2" doit être utilisé.
vault secrets enable -path=secret/ kv-v2

# Ajouter un nouveau secret avec la clé "password" sous le point de montage "secret/" et le chemin "zabbix/macros".
vault kv put -mount=secret zabbix/macros password=<password>

# Vérifier que le secret a bien été ajouté.
vault kv get secret/zabbix/macros

# Enfin, tester avec Curl ; notez que "data" doit être ajouté manuellement après le point de montage et "/v1" avant le point de montage, voir aussi le paramètre --capath.
curl --header "X-Vault-Token: <VaultToken>" https://127.0.0.1:8200/v1/secret/data/zabbix/macros
  1. En conséquence, Zabbix résoudra la macro {$PASSWORD} en la valeur : <password>

Mise à jour d'une configuration existante

Pour mettre à jour une configuration existante afin de récupérer des secrets depuis un HashiCorp Vault :

  1. Mettez à jour les paramètres du fichier de configuration du serveur ou du proxy Zabbix comme décrit dans la section Identifiants de la base de données.

  2. Mettez à jour les paramètres du fichier de configuration de l'interface Zabbix :

Avec un jeton 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 avec la méthode 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. Configurez les macros utilisateur comme décrit dans la section Valeurs des macros utilisateur, si nécessaire.

Pour mettre à jour une configuration existante afin de récupérer des secrets depuis un CyberArk Vault, consultez la section Configuration de CyberArk.

Dépannage

  1. Dans le fichier journal du serveur/proxy Zabbix :
237839:20260729:130916.425 Vault token renew started to fail: cannot login into HashiCorp vault with AppRole method: unsuccessful response code "503"

Cause probable : HashiCorp Vault a été (re)démarré, mais n’a pas été déscellé (ce qui est requis dans la configuration par défaut, mais pas si l’option Auto Unseal est configurée).

  1. Dans le fichier journal du serveur/proxy Zabbix :
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"

Cause probable : VaultAppSecretID a expiré ou a atteint sa limite d’utilisation dans HashiCorp Vault.