[comment]: # translation:outdated

[comment]: # ({4dc10e58-317d63e9})
# 2 HashiCorp配置

[comment]: # ({/4dc10e58-317d63e9})

[comment]: # ({8d9b38bd-fdcfe831})
#### 概述

本节介绍如何配置 Zabbix，以便从 HashiCorp Vault KV Secrets Engine - Version 2 检索密钥。

应按照官方 [HashiCorp 文档](https://www.vaultproject.io/docs/secrets/kv/kv-v2) 中的说明部署并配置 vault。

要了解如何在 Zabbix 中配置 TLS，请参见 [*密钥存储*](/manual/config/secrets#configuring-tls)。

[comment]: # ({/8d9b38bd-fdcfe831})

[comment]: # ({4abbcd52-9c0ce526})
#### 检索数据库凭据

要成功检索包含数据库凭据的密钥，需要同时配置以下两项：

-   Zabbix 服务器/proxy
-   Zabbix 前端

##### 服务器/proxy

要配置 Zabbix [服务器](/manual/concepts/server/server_params) 或 [proxy](/manual/concepts/proxy/proxy_params)，
请在配置文件中指定以下配置参数：

-   `Vault` - 应使用哪个 vault 提供程序；
-   `VaultToken` - vault 身份验证令牌（详情请参见 Zabbix 服务器/proxy 配置文件）；
-   `VaultURL` - vault 服务器 HTTP\[S\] URL；
-   `VaultDBPath` - 包含数据库凭据的 vault 密钥路径（仅当未指定 DBUser 和 DBPassword 时才能使用此选项）；Zabbix 服务器或 proxy 将通过键 "password" 和 "username" 检索凭据；
-   `VaultPrefix` - vault 路径或查询的自定义前缀，具体取决于 vault；如果未指定，将使用最合适的默认值。

:::noteimportant
`Vault`、`VaultToken`、`VaultURL` 和 `VaultPrefix` 配置参数也用于 Zabbix 服务器在处理 secret vault 宏时进行 vault 身份验证（如果已[配置](/manual/web_interface/frontend_sections/administration/general#other)，Zabbix proxy 也同样适用）。Zabbix 服务器和 proxy 不会打开包含来自 VaultDBPath 的数据库凭据的 vault secret 宏。<br><br>强烈建议为不同的 proxy 使用不同的令牌。
:::

Zabbix 服务器和 Zabbix proxy 在启动时会从 *zabbix_server.conf* 和 *zabbix_proxy.conf* 中读取与 vault 相关的配置参数。
此外，Zabbix 服务器和 Zabbix proxy 会在启动时读取一次 `VAULT_TOKEN` 环境变量，并将其取消设置，以便通过 fork 的脚本无法访问；如果 `VaultToken` 和 `VAULT_TOKEN` 参数都包含值，则会报错。

[comment]: # ({/4abbcd52-9c0ce526})

[comment]: # ({901bf5bb-19842818})
**示例**

1. 在 *zabbix_server.conf* 中，指定以下参数：

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

2. 运行以下 CLI 命令，在 vault 中创建所需的 secret：

```bash
# 如果尚未启用，则启用 "secret/" 挂载点；请注意，必须使用 "kv-v2"。
vault secrets enable -path=secret/ kv-v2

# 在挂载点 "secret/" 下、路径 "zabbix/database" 中，添加键为 username 和 password 的新 secret。
vault kv put -mount=secret zabbix/database username=zabbix password=<password>

# 测试 secret 是否已成功添加。
vault kv get secret/zabbix/database

# 最后使用 Curl 进行测试；请注意，必须在挂载点后手动添加 "data"，并在挂载点前添加 "/v1"，另请参见 --capath 参数。
curl --header "X-Vault-Token: <VaultToken>" https://127.0.0.1:8200/v1/secret/data/zabbix/database
```

3. 最终，Zabbix 服务器将检索以下用于数据库认证的凭据：

-   用户名：zabbix
-   密码：<password>

[comment]: # ({/901bf5bb-19842818})

[comment]: # ({26ba1bdc-0cae9564})
##### 前端

Zabbix 前端可配置为从 vault 检索数据库凭据，  
可在前端[安装](/manual/installation/frontend)期间进行，或通过更新前端配置文件（`zabbix.conf.php`）进行。 

:::noteimportant
如果自上次前端安装以来 vault 凭据已更改，请重新运行前端安装，  
或更新 `zabbix.conf.php`。另请参见：[更新现有配置](#updating-existing-configuration)。
:::
  
在**前端安装**期间，必须在 *Configure DB Connection* 步骤中指定配置参数：

![](../../../../assets/en/manual/config/hashicorp_setup.png){width="600"}
  
-   将 *Store credentials in* 参数设置为 “HashiCorp Vault”。
-   指定连接参数：

|参数|必填|默认值|描述|
|---|-|---|------|
|*Vault API endpoint*|是|https://localhost:8200|指定用于连接 vault 的 URL，格式为 `scheme://host:port`|
|*Vault prefix*|否|/v1/secret/data/|为 vault 路径或查询提供自定义前缀。如果未指定，则使用默认值。<br>示例：`/v1/secret/data/zabbix/`|
|*Vault secret path*|否| |用于获取数据库凭据的密钥路径，数据库凭据应通过键 “password” 和 “username” 读取。<br>示例：`database`|
|*Vault authentication token*|否| |提供对密钥路径具有只读访问权限的身份验证令牌。<br>有关创建令牌和 vault 策略的信息，请参见 [HashiCorp documentation](https://learn.hashicorp.com/tutorials/vault/tokens)。|

[comment]: # ({/26ba1bdc-0cae9564})

[comment]: # ({9d96212b-2e69e703})
#### 检索用户宏值

要使用 HashiCorp Vault 存储 *Vault secret* 用户宏值，请确保：

- Zabbix 服务器/proxy 已[配置](/manual/config/secrets/hashicorp#serverproxy)为可与 HashiCorp Vault 配合工作；
- [*管理 → 常规 → 其他*](/manual/web_interface/frontend_sections/administration/general#other)中的 *Vault provider* 参数设置为 “HashiCorp Vault”（默认）；

![](../../../../assets/en/manual/config/provider_hashicorp.png)

:::noteclassic
Zabbix 服务器（以及 Zabbix proxy，如果已[配置](/manual/web_interface/frontend_sections/administration/general#other)）需要能够从 vault 访问 *Vault secret* 宏值。  
Zabbix 前端不需要此类访问。
:::

宏值应包含一个引用路径（格式为 `path:key`，例如 `macros:password`）。
在 Zabbix 服务器/proxy 配置期间指定的认证令牌（通过 `VaultToken` 参数）必须对该路径提供只读访问权限。

有关 Zabbix 如何处理宏值的详细信息，请参见 [*Vault secret macros*](/manual/config/macros/secret_macros#vault-secret)。

[comment]: # ({/9d96212b-2e69e703})

[comment]: # ({0481f8ba-b5cf890a})
**路径语法**

斜杠（"/"）和冒号（":"）这两个符号是保留的。

斜杠只能用于将挂载点与路径分隔开（例如，*secret/zabbix* 中挂载点是 "secret"，路径是 "zabbix"）。在保险库宏的情况下，冒号只能用于将路径/查询与键分隔开。

如果需要创建一个由斜杠分隔的挂载点名称（例如 *foo/bar/zabbix*，其中挂载点是 "foo/bar"，路径是 "zabbix"），可以对斜杠和冒号符号进行URL编码。如果需要在挂载点名称或路径中包含冒号，也可以进行URL编码。

[comment]: # ({/0481f8ba-b5cf890a})

[comment]: # ({9f72277f-0c64c650})
**示例**

1. 在 Zabbix 中，添加一个类型为“Vault secret”、值为 `macros:password` 的用户宏 {$PASSWORD}

![](../../../../assets/en/manual/config/hashi_macro.png)

2. 运行以下 CLI 命令，在 vault 中创建所需的 secret：

```bash
# 如果尚未启用，则启用 "secret/" 挂载点；请注意，必须使用 "kv-v2"。
vault secrets enable -path=secret/ kv-v2

# 在挂载点 "secret/" 和路径 "zabbix/macros" 下放置一个键为 "password" 的新 secret。
vault kv put -mount=secret zabbix/macros password=<password>

# 测试 secret 是否已成功添加。
vault kv get secret/zabbix/macros

# 最后使用 Curl 进行测试；请注意，必须在挂载点后手动添加 "data"，并在挂载点前添加 "/v1"，另请参见 --capath 参数。
curl --header "X-Vault-Token: <VaultToken>" https://127.0.0.1:8200/v1/secret/data/zabbix/macros
```

3. 最终，Zabbix 会将宏 {$PASSWORD} 解析为值：<password>

[comment]: # ({/9f72277f-0c64c650})

[comment]: # ({e1678ca3-d8c23996})
#### 更新现有配置

要更新用于从 HashiCorp Vault 检索密钥的现有配置：

1. 按照 [*数据库凭据*](#retrieving-database-credentials) 部分中的说明，更新 Zabbix 服务器或 proxy 配置文件参数。

2. 按照 [*前端*](#frontend) 部分中的说明，重新配置 Zabbix 前端 并指定所需参数，以更新数据库连接设置。  
要重新配置 Zabbix 前端，请在浏览器中打开前端设置 URL：

-   对于 Apache：http://<server_ip_or_name>/zabbix/setup.php
-   对于 Nginx：http://<server_ip_or_name>/setup.php

或者，也可以在[前端配置文件](/manual/installation/frontend#install)（*zabbix.conf.php*）中设置这些参数：

```ini
$DB['VAULT']                    = 'HashiCorp';
$DB['VAULT_URL']                = 'https://localhost:8200';
$DB['VAULT_DB_PATH']            = 'database';
$DB['VAULT_TOKEN']              = '<mytoken>';
$DB['VAULT_CERT_FILE']          = '';
$DB['VAULT_KEY_FILE']           = '';
$DB['VAULT_PREFIX']             = '/v1/secret/data/zabbix/';
```

3. 如有必要，按照 [*用户宏值*](#frontend) 部分中的说明配置用户宏。

要更新用于从 CyberArk Vault 检索密钥的现有配置，请参见 [*CyberArk 配置*](/manual/config/secrets/cyberark#update-existing-configuration)。

[comment]: # ({/e1678ca3-d8c23996})