[comment]: # translation:outdated

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

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

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

本节说明要从HashiCorp Vault KV Secrets Engine - Version 2检索秘文，应该如何配置Zabbix。

保险库应按照官方[HashiCorp文档](https://www.vaultproject.io/docs/secrets/kv/kv-v2)中描述的方式部署和配置。

要了解如何在Zabbix中配置TLS，请参阅[*存储秘密*](/manual/config/secrets#configuring_tls)。

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

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

要成功检索包含数据库凭据的秘文，需要同时配置：

- Zabbix server/proxy
- Zabbix前端

##### Server/proxy

要配置Zabbix [server](/manual/appendix/config/zabbix_server)或[proxy](/manual/appendix/config/zabbix_proxy)，请在配置文件中指定以下配置参数：

- `Vault` - 应使用的保险库提供者；
- `VaultToken` - 保险库认证令牌（详见Zabbix server/proxy配置文件获取详细信息）；
- `VaultURL` - 保险库服务器的HTTP\[S\] URL；
- `VaultDBPath` - 指向包含数据库凭据的保险库秘密的路径；Zabbix server或proxy将通过键"password"和"username"检索凭据；
- `VaultPrefix` - 保险库路径或查询的自定义前缀，具体取决于保险库；如果未指定，则将使用最合适的默认值。

:::noteimportant
Zabbix server在处理保险库秘密宏时，也使用`Vault`，`VaultToken`，`VaultURL`和`VaultPrefix`配置参数进行保险库认证。
:::

Zabbix server和Zabbix proxy在启动时从*zabbix_server.conf*和*zabbix_proxy.conf*文件中读取与保险库相关的配置参数。
此外，Zabbix server和Zabbix proxy在启动期间会从`VAULT_TOKEN`环境变量中读取一次，并在启动后取消设置该变量，以确保它不会通过分叉脚本可用；如果`VaultToken`和`VAULT_TOKEN`参数同时包含值，则会出现错误。

[comment]: # ({/41ff19ac-9c0ce526})

[comment]: # ({1285edf4-19842818})
**示例**

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

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

2. 使用以下CLI命令在保险库中创建所需的秘密：

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

# 在挂载点“secret/”和路径“zabbix/database”下放置具有用户名和密码键的新秘密。
vault kv put -mount=secret zabbix/database username=zabbix password=<password>

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

# 最后使用Curl测试；请注意，在挂载点之后和“/v1”之前，需要手动添加“data”参数，并查看--capath参数。
curl --header "X-Vault-Token: <VaultToken>" https://127.0.0.1:8200/v1/secret/data/zabbix/database
```

3. 结果是，Zabbix server将检索以下用于数据库认证的凭据：

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

[comment]: # ({/1285edf4-19842818})

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

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

:::noteimportant
如果自上次前端安装以来保险库凭据已更改，请重新运行前端安装或更新`zabbix.conf.php`。另请参阅：[更新现有配置](#updating_existing_configuration)。
:::

在**前端安装**期间，必须在*配置数据库连接*步骤中指定配置参数：

![](../../../../assets/en/manual/config/hashicorp_setup.png){width="600"}

- 将*Store credentials in*参数设置为 "HashiCorp Vault"。
- 指定连接参数：

| 参数 | 必填项 | 默认值 | 描述 |
|---|---|---|------|
| *Vault API endpoint*（保险库API端点） | 是 | https://localhost:8200 | 指定连接到保险库的URL，格式为 `scheme://host:port` |
| *Vault prefix*（保险库前缀） | 否 | /v1/secret/data/ | 提供用于保险库路径或查询的自定义前缀。如果未指定，则使用默认值。 |
| *Vault secret path*（保险库秘密路径） | 否 | | 从中检索数据库凭据的秘密路径，通过键"password"和"username"。<br>例如： `secret/zabbix/database` |
| *Vault authentication token*（保险库认证令牌） | 否 | | 提供用于只读访问秘密路径的认证令牌。<br>请参阅[HashiCorp文档](https://learn.hashicorp.com/tutorials/vault/tokens)了解如何创建令牌和保险库策略。 |

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

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

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

- Zabbix server已配置为与HashiCorp Vault配合使用，详见[配置](/manual/config/secrets/hashicorp#server_and_proxies)。
- [*Administration → General → Other*](/manual/web_interface/frontend_sections/administration/general#other-parameters)中的*Vault provider*参数设置为 "HashiCorp Vault"（默认）。

![HashiCorp Vault Provider Setting](../../../../assets/en/manual/config/provider_hashicorp.png)

:::noteclassic
只有Zabbix server需要从保险库获取*Vault secret*宏值。
其他Zabbix组件（proxy，前端）不需要此类访问权限。
:::

用户宏值应包含一个引用路径（如`path:key`，例如`secret/zabbix:password`）。
在Zabbix server配置期间指定的认证令牌（通过`VaultToken`参数）必须为此路径提供只读访问权限。

详细了解Zabbix如何处理*Vault secret*宏值，请参阅[*Vault secret macros*](/manual/config/macros/secret_macros#vault_secret)。

[comment]: # ({/3d81689d-2e69e703})

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

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

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

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

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

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

1. 在Zabbix中，添加一个类型为 "Vault secret" 的用户宏 {$PASSWORD}，其值为 `secret/zabbix:password`。

![HashiCorp Vault Macro Example](../../../../assets/en/manual/config/hashi_macro.png)

2. 使用以下CLI命令在保险库中创建所需的秘密：

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

# 在挂载点“secret/”和路径“zabbix”下放置键为password的新秘密。
vault kv put -mount=secret zabbix password=<password>

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

# 最后使用Curl测试；请注意，在挂载点之后和“/v1”之前，需要手动添加“data”参数，并查看--capath参数。
curl --header "X-Vault-Token: <VaultToken>" https://127.0.0.1:8200/v1/secret/data/zabbix
```

3. 结果是，Zabbix将把宏 {$PASSWORD} 解析为值：<password>

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

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

要更新从HashiCorp Vault检索秘密的现有配置，请按照以下步骤进行操作：

1. 根据[*Database credentials*](#database-credentials)部分的说明，更新Zabbix server或proxy配置文件参数。

2. 通过重新配置Zabbix前端并指定所需的参数来更新DB连接设置，具体步骤如[*Frontend*](#frontend)部分所述。
   要重新配置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']            = 'secret/zabbix/database';
   $DB['VAULT_TOKEN']              = '<mytoken>';
   $DB['VAULT_CERT_FILE']          = '';
   $DB['VAULT_KEY_FILE']           = '';
   $DB['VAULT_PREFIX']             = '';
   ```

3. 根据需要，按照[*User macro values*](#frontend)部分的说明配置用户宏值。

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

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