You are viewing documentation for the development version, it may be incomplete.
Join our translation project and help translate Zabbix documentation into your native language.

2 HashiCorp configuration

Overview

This section explains how to configure Zabbix for retrieving secrets from HashiCorp Vault KV Secrets Engine - Version 2.

The vault should be deployed and configured as described in the official HashiCorp documentation.

To learn about configuring TLS in Zabbix, see Storage of secrets.

Retrieving database credentials

To retrieve a secret with database credentials successfully, it is required to configure both:

  • Zabbix server/proxy
  • Zabbix frontend
Server/proxy

To configure Zabbix server or proxy, specify the following configuration parameters in the configuration file:

  • Vault - which vault provider should be used;
  • VaultToken - vault authentication token (see Zabbix server/proxy configuration file for details);
  • VaultURL - vault server HTTP[S] URL;
  • VaultDBPath - path to the vault secret containing database credentials; Zabbix server or proxy will retrieve the credentials by keys "password" and "username";
  • VaultPrefix - custom prefix for the vault path or query, depending on the vault; if not specified, the most suitable default will be used.

Zabbix server also uses the Vault, VaultToken, VaultURL, and VaultPrefix configuration parameters for vault authentication when processing vault secret macros.

Zabbix server and Zabbix proxy read the vault-related configuration parameters from zabbix_server.conf and zabbix_proxy.conf upon startup. Additionally, Zabbix server and Zabbix proxy will read the VAULT_TOKEN environment variable once during startup and will unset it so that it would not be available through forked scripts; it is an error if both VaultToken and VAULT_TOKEN parameters contain a value.

Example

  1. In zabbix_server.conf, specify the following parameters:
Vault=HashiCorp
       VaultToken=hvs.CAESIIG_PILmULFYOsEyWHxkZ2mF2a8VPKNLE8eHqd4autYGGh4KHGh2cy5aeTY0NFNSaUp3ZnpWbDF1RUNjUkNTZEg
       VaultURL=https://127.0.0.1:8200
       VaultDBPath=secret/zabbix/database
       VaultPrefix=/v1/secret/data/
  1. Run the following CLI commands to create the required secret in the vault:
# Enable "secret/" mount point if not already enabled; note that "kv-v2" must be used.
       vault secrets enable -path=secret/ kv-v2
       
       # Put new secrets with keys username and password under mount point "secret/" and path "zabbix/database".
       vault kv put -mount=secret zabbix/database username=zabbix password=<password>
       
       # Test that secret is successfully added.
       vault kv get secret/zabbix/database
       
       # Finally test with Curl; note that "data" need to be manually added after mount point and "/v1" before the mount point, also see --capath parameter.
       curl --header "X-Vault-Token: <VaultToken>" https://127.0.0.1:8200/v1/secret/data/zabbix/database
  1. As a result, Zabbix server will retrieve the following credentials for database authentication:
  • Username: zabbix
  • Password: <password>
Frontend

Zabbix frontend can be configured to retrieve database credentials from the vault either during frontend installation or by updating the frontend configuration file (zabbix.conf.php).

If vault credentials have been changed since the previous frontend installation, rerun the frontend installation or update zabbix.conf.php. See also: Updating existing configuration.

During frontend installation the configuration parameters must be specified at the Configure DB Connection step:

  • Set the Store credentials in parameter to "HashiCorp Vault".
  • Specify the connection parameters:
Parameter Mandatory Default value Description
Vault API endpoint yes https://localhost:8200 Specify the URL for connecting to the vault in the format scheme://host:port
Vault prefix no /v1/secret/data/ Provide a custom prefix for the vault path or query. If not specified, the default is used.
Vault secret path no A path to the secret from where credentials for the database shall be retrieved by the keys "password" and "username".
Example: secret/zabbix/database
Vault authentication token no Provide an authentication token for read-only access to the secret path.
See HashiCorp documentation for information about creating tokens and vault policies.

Retrieving user macro values

To use HashiCorp Vault for storing Vault secret user macro values, make sure that:

Only Zabbix server requires access to Vault secret macro values from the vault. Other Zabbix components (proxy, frontend) do not need such access.

The macro value should contain a reference path (as path:key, for example, secret/zabbix:password). The authentication token specified during Zabbix server configuration (by the VaultToken parameter) must provide read-only access to this path.

See Vault secret macros for detailed information on macro value processing by Zabbix.

Path syntax

The symbols forward slash ("/") and colon (":") are reserved.

A forward slash can only be used to separate a mount point from a path (e.g., secret/zabbix where the mount point is "secret" and the path is "zabbix"). In the case of Vault macros, a colon can only be used to separate a path/query from a key.

It is possible to URL-encode the forward slash and colon symbols if there is a need to create a mount point with the name that is separated by a forward slash (e.g., foo/bar/zabbix, where the mount point is "foo/bar" and the path is "zabbix", can be encoded as "foo%2Fbar/zabbix") and if a mount point name or path need to contain a colon.

Example

  1. In Zabbix, add a user macro {$PASSWORD} of type "Vault secret" and with the value secret/zabbix:password

  1. Run the following CLI commands to create required secret in the vault:
# Enable "secret/" mount point if not already enabled; note that "kv-v2" must be used.
       vault secrets enable -path=secret/ kv-v2
       
       # Put new secret with key password under mount point "secret/" and path "zabbix".
       vault kv put -mount=secret zabbix password=<password>
       
       # Test that secret is successfully added.
       vault kv get secret/zabbix
       
       # Finally test with Curl; note that "data" need to be manually added after mount point and "/v1" before the mount point, also see --capath parameter.
       curl --header "X-Vault-Token: <VaultToken>" https://127.0.0.1:8200/v1/secret/data/zabbix
  1. As a result, Zabbix will resolve the macro {$PASSWORD} to the value: <password>

Updating existing configuration

To update an existing configuration for retrieving secrets from a HashiCorp Vault:

  1. Update the Zabbix server or proxy configuration file parameters as described in the Database credentials section.

  2. Update the DB connection settings by reconfiguring Zabbix frontend and specifying the required parameters as described in the Frontend section. To reconfigure Zabbix frontend, open the frontend setup URL in the browser:

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

Alternatively, these parameters can be set in the frontend configuration file (zabbix.conf.php):

$DB['VAULT']                    = 'HashiCorp';
       $DB['VAULT_URL']                = 'https://localhost:8200';
       $DB['VAULT_DB_PATH']            = 'secret/zabbix/database';
       $DB['VAULT_TOKEN']              = '<mytoken>';
       $DB['VAULT_CERT_FILE']          = '';
       $DB['VAULT_KEY_FILE']           = '';
       $DB['VAULT_PREFIX']             = '';
  1. Configure user macros as described in the User macro values section, if necessary.

To update an existing configuration for retrieving secrets from a CyberArk Vault, see CyberArk configuration.