HashiCorp-Konfiguration

Übersicht

In diesem Abschnitt wird erläutert, wie Zabbix für das Abrufen von Geheimnissen aus der HashiCorp Vault KV Secrets Engine – Version 2 konfiguriert wird.

Der Vault sollte wie in der offiziellen HashiCorp-Dokumentation beschrieben bereitgestellt und konfiguriert werden.

Informationen zur Konfiguration von TLS in Zabbix finden Sie unter Speicherung von Geheimnissen.

Abrufen von Datenbankanmeldedaten

Um ein Secret mit Datenbankanmeldedaten erfolgreich abzurufen, müssen beide Komponenten konfiguriert werden:

  • Zabbix Server/Proxy
  • Zabbix Frontend

Server/Proxy

Um den Zabbix Server oder Proxy zu konfigurieren, geben Sie die folgenden Konfigurationsparameter in der Konfigurationsdatei an:

  • Vault - welcher Vault-Anbieter verwendet werden soll.
  • VaultToken - Vault-Authentifizierungstoken (Details finden Sie in der Zabbix-Konfigurationsdatei für Server/Proxy); kann nicht zusammen mit VaultAppRoleID verwendet werden.
  • VaultAppRoleID und VaultAppSecretID - Rollen-ID und Secret-ID für die Vault-Authentifizierung (Details finden Sie in der Zabbix-Konfigurationsdatei für Server/Proxy); können nicht zusammen mit VaultToken verwendet werden.
  • VaultURL - HTTP(S)-URL des Vault-Servers.
  • VaultDBPath - Pfad zum Vault-Secret mit den Datenbankanmeldedaten (diese Option kann nur verwendet werden, wenn DBUser und DBPassword nicht angegeben sind). Der Zabbix Server oder Proxy ruft die Anmeldedaten über die Schlüssel „password“ und „username“ ab.
  • VaultPrefix - benutzerdefiniertes Präfix für den Vault-Pfad oder die Abfrage, abhängig vom Vault; wenn nicht angegeben, wird der am besten geeignete Standardwert verwendet. Beachten Sie, dass das Präfix mit / beginnen und enden muss.

Die Konfigurationsparameter Vault, VaultToken (oder VaultAppRoleID/VaultAppSecretID), VaultURL und VaultPrefix werden auch für die Vault-Authentifizierung verwendet, wenn Secret-Vault-Makros durch den Zabbix Server verarbeitet werden (und durch den Zabbix Proxy, falls konfiguriert). Der Zabbix Server und die Proxys öffnen keine Secret-Makros, die Datenbankanmeldedaten aus VaultDBPath enthalten.

Es wird dringend empfohlen, für verschiedene Proxys unterschiedliche Token zu verwenden.

Der Zabbix Server und der Zabbix Proxy lesen die Vault-bezogenen Konfigurationsparameter beim Start aus zabbix_server.conf und zabbix_proxy.conf. Zusätzlich lesen der Zabbix Server und der Zabbix Proxy die Umgebungsvariable VAULT_TOKEN einmalig beim Start aus und setzen sie zurück, damit sie über geforkte Skripte nicht verfügbar ist. Es ist ein Fehler, wenn sowohl der Parameter VaultToken als auch VAULT_TOKEN einen Wert enthalten.

Beispiel
  1. Konfigurieren Sie die Parameter des Zabbix Servers.

Verwenden Sie die Beispielwerte für Token, Rollen-ID oder Secret-ID aus der Dokumentation nicht in Produktionsumgebungen.

  • Wenn Sie die Umgebungsvariable VAULT_TOKEN verwenden, geben Sie die folgenden Parameter in der Konfigurationsdatei des Servers (zabbix_server.conf) an und setzen Sie die Variable:
Vault=HashiCorp
VaultURL=https://127.0.0.1:8200
VaultDBPath=database
VaultPrefix=/v1/secret/data/zabbix/

Setzen Sie die Umgebungsvariable VAULT_TOKEN, bevor der Zabbix Server gestartet wird:

export VAULT_TOKEN=hvs.CAESIIG_PILmULFYOsEyWHxkZ2mF2a8VPKNLE8eHqd4autYGGh4KHGh2cy5aeTY0NFNSaUp3ZnpWbDF1RUNjUkNTZEg
zabbix_server -c /etc/zabbix/zabbix_server.conf
  • Wenn Sie den Parameter VaultToken verwenden, geben Sie die folgenden Parameter in der Konfigurationsdatei des Zabbix Servers an:

Wenn Sie den Parameter VaultToken verwenden, wird das Token im Klartext in der Konfigurationsdatei gespeichert. Setzen Sie die Dateiberechtigungen auf 0600, damit nur der Benutzer, unter dem der Zabbix Server oder Proxy ausgeführt wird, die Datei lesen kann.

Vault=HashiCorp
VaultToken=hvs.CAESIIG_PILmULFYOsEyWHxkZ2mF2a8VPKNLE8eHqd4autYGGh4KHGh2cy5aeTY0NFNSaUp3ZnpWbDF1RUNjUkNTZEg
VaultURL=https://127.0.0.1:8200
VaultDBPath=database
VaultPrefix=/v1/secret/data/zabbix/
  • Wenn Sie den Parameter VaultAppRoleID verwenden, geben Sie die folgenden Parameter in der Konfigurationsdatei des Zabbix Servers an:

Wenn Sie den Parameter VaultAppSecretID verwenden, wird die Secret-ID im Klartext in der Konfigurationsdatei gespeichert. Setzen Sie die Dateiberechtigungen auf 0600, damit nur der Benutzer, unter dem der Zabbix Server oder Proxy ausgeführt wird, die Datei lesen kann.

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. Führen Sie die folgenden CLI-Befehle aus, um das erforderliche Secret im Vault zu erstellen:
# Aktivieren Sie den Mount-Punkt "secret/", falls er noch nicht aktiviert ist; beachten Sie, dass "kv-v2" verwendet werden muss.
vault secrets enable -path=secret/ kv-v2

# Legen Sie neue Secrets mit den Schlüsseln username und password unter dem Mount-Punkt "secret/" und dem Pfad "zabbix/database" ab.
vault kv put -mount=secret zabbix/database username=zabbix password=<password>

# Testen Sie, ob das Secret erfolgreich hinzugefügt wurde.
vault kv get secret/zabbix/database

# Testen Sie abschließend mit Curl; beachten Sie, dass "data" nach dem Mount-Punkt und "/v1" vor dem Mount-Punkt manuell hinzugefügt werden müssen; siehe auch den Parameter --capath.
curl --header "X-Vault-Token: <VaultToken>" https://127.0.0.1:8200/v1/secret/data/zabbix/database
  1. Als Ergebnis ruft der Zabbix Server die folgenden Anmeldedaten für die Datenbankauthentifizierung ab:
  • Benutzername: zabbix
  • Passwort: <password>

Frontend

Das Zabbix-Frontend kann so konfiguriert werden, dass es die Datenbankanmeldedaten entweder während der Installation des Frontends oder durch Aktualisieren der Frontend-Konfigurationsdatei (zabbix.conf.php) aus dem Vault abruft.

Wenn sich die Vault-Anmeldedaten seit der vorherigen Frontend-Installation geändert haben, aktualisieren Sie die vorhandene Konfiguration.

Während der Frontend-Installation müssen die Verbindungsparameter im Schritt Configure DB Connection angegeben werden.

Konfigurationsbeispiel mit Token-Authentifizierung:

Konfigurationsbeispiel mit AppRole-Authentifizierung:

Parameter Mandatory Default value Description
Store credentials in no Wählen Sie HashiCorp Vault aus.
Vault API endpoint yes https://localhost:8200 Geben Sie die URL für die Verbindung zum Vault im Format scheme://host:port an.
Vault prefix no /v1/secret/data/ Geben Sie ein benutzerdefiniertes Präfix für den Vault-Pfad oder die Abfrage an. Wenn kein Präfix angegeben wird, wird der Standardwert verwendet.
Beispiel: /v1/secret/data/zabbix/
Vault secret path yes Ein Pfad zum Secret, aus dem die Anmeldedaten für die Datenbank anhand der Schlüssel „password“ und „username“ abgerufen werden sollen.
Beispiel: database
Vault authentication type no Wählen Sie den Vault-Authentifizierungstyp aus:
Token – Token-Authentifizierung verwenden;
AppRole – die AppRole-Authentifizierungsmethode verwenden.
Vault authentication token yes Geben Sie ein Authentifizierungstoken für den schreibgeschützten Zugriff auf den Secret-Pfad an.
Informationen zum Erstellen von Token und Vault-Richtlinien finden Sie in der HashiCorp-Dokumentation.
Dieses Feld ist nur verfügbar, wenn Token als Vault-Authentifizierungstyp ausgewählt ist.
Vault authentication role ID yes Geben Sie die Rollen-ID der AppRole an.
Informationen zu AppRoles finden Sie in der HashiCorp-Dokumentation.
Dieses Feld ist nur verfügbar, wenn AppRole als Vault-Authentifizierungstyp ausgewählt ist.
Vault authentication secret ID yes Geben Sie die für die AppRole ausgestellte Secret-ID an.
Informationen zu AppRoles finden Sie in der HashiCorp-Dokumentation.
Dieses Feld ist nur verfügbar, wenn AppRole als Vault-Authentifizierungstyp ausgewählt ist.

Abrufen von Benutzer-Makrowerten

Um HashiCorp Vault zum Speichern von Benutzer-Makrowerten als Vault secret zu verwenden, stellen Sie sicher, dass:

Der Zabbix Server (und der Zabbix Proxy, falls unter Administration > General > Other konfiguriert) benötigt Zugriff auf die Makrowerte als Vault secret im Vault. Das Zabbix Frontend benötigt keinen solchen Zugriff.

Der Makrowert sollte einen Referenzpfad enthalten (als path:key, zum Beispiel macros:password). Das während der Konfiguration des Zabbix Servers/Proxys angegebene Authentifizierungstoken (über den Parameter VaultToken) muss schreibgeschützten Zugriff auf diesen Pfad gewähren.

Ausführliche Informationen zur Verarbeitung von Makrowerten durch Zabbix finden Sie unter Vault secret macros.

Pfadsyntax

Die Symbole Schrägstrich ("/") und Doppelpunkt (":") sind reserviert.

Ein Schrägstrich kann nur verwendet werden, um einen Mountpoint von einem Pfad zu trennen (z. B. secret/zabbix, wobei der Mountpoint "secret" und der Pfad "zabbix" ist). Bei Vault-Makros kann ein Doppelpunkt nur verwendet werden, um einen Pfad/Query von einem Schlüssel zu trennen.

Es ist möglich, die Symbole Schrägstrich und Doppelpunkt per URL-Encoding zu kodieren, wenn ein Mountpoint mit einem Namen erstellt werden soll, der durch einen Schrägstrich getrennt ist (z. B. kann foo/bar/zabbix, wobei der Mountpoint "foo/bar" und der Pfad "zabbix" ist, als "foo%2Fbar/zabbix" kodiert werden) und wenn ein Mountpoint-Name oder Pfad einen Doppelpunkt enthalten muss.

Beispiel

  1. Fügen Sie in Zabbix ein Benutzermakro {$PASSWORD} vom Typ "Vault secret" mit dem Wert macros:password hinzu

  1. Führen Sie die folgenden CLI-Befehle aus, um das erforderliche Secret im Vault zu erstellen:
# Aktivieren Sie den Mount-Punkt "secret/", falls er noch nicht aktiviert ist; beachten Sie, dass "kv-v2" verwendet werden muss.
vault secrets enable -path=secret/ kv-v2

# Legen Sie ein neues Secret mit dem Schlüssel "password" unter dem Mount-Punkt "secret/" und dem Pfad "zabbix/macros" ab.
vault kv put -mount=secret zabbix/macros password=<password>

# Prüfen Sie, ob das Secret erfolgreich hinzugefügt wurde.
vault kv get secret/zabbix/macros

# Testen Sie abschließend mit Curl; beachten Sie, dass "data" nach dem Mount-Punkt und "/v1" vor dem Mount-Punkt manuell hinzugefügt werden muss, siehe auch den Parameter --capath.
curl --header "X-Vault-Token: <VaultToken>" https://127.0.0.1:8200/v1/secret/data/zabbix/macros
  1. Dadurch löst Zabbix das Makro {$PASSWORD} in den Wert <password> auf

Aktualisieren einer vorhandenen Konfiguration

So aktualisieren Sie eine vorhandene Konfiguration zum Abrufen von Geheimnissen aus einem HashiCorp Vault:

  1. Aktualisieren Sie die Parameter der Konfigurationsdatei des Zabbix Servers oder Proxys, wie im Abschnitt Datenbankanmeldeinformationen beschrieben.

  2. Aktualisieren Sie die Parameter der Frontend-Konfigurationsdatei von Zabbix:

Verwendung eines Vault-Tokens:

$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/';

Oder mithilfe der Vault-AppRole-Methode:

$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. Konfigurieren Sie bei Bedarf Benutzermakros, wie im Abschnitt Werte von Benutzermakros beschrieben.

Informationen zum Aktualisieren einer vorhandenen Konfiguration zum Abrufen von Geheimnissen aus einem CyberArk Vault finden Sie unter CyberArk-Konfiguration.

Fehlerbehebung

  1. In der Protokolldatei des Zabbix-Servers/Proxys:
237839:20260729:130916.425 Vault token renew started to fail: cannot login into HashiCorp vault with AppRole method: unsuccessful response code "503"

Wahrscheinliche Ursache: HashiCorp Vault wurde (neu) gestartet, aber nicht entsiegelt (in der Standardkonfiguration erforderlich, bei konfiguriertem Auto Unseal nicht erforderlich).

  1. In der Protokolldatei des Zabbix-Servers/Proxys:
235545:20260729:125617.944 Vault token renew started to fail: cannot login into HashiCorp vault with AppRole method: unsuccessful response code "400"

oder

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

Wahrscheinliche Ursache: VaultAppSecretID ist abgelaufen oder hat im HashiCorp Vault sein Nutzungslimit erreicht.