将更改应用到配置文件

在 Windows 上，使用 securityadmin.bat 替代 securityadmin.sh。

Security 插件将其配置（包括用户、角色、权限和后端设置）存储在 UDB-SX 集群上的系统索引中。将这些设置存储在索引中可以让您更改设置而无需重启集群，并消除了在每个单独节点上编辑配置文件的需要。这是通过运行 securityadmin.sh 脚本来实现的。

该脚本的作用是初始化 .opendistro_security 索引。这将使用 udbsx/udbsx-25.0.0/config/udbsx-security 中的配置文件将您的初始配置加载到索引中。.opendistro_security 索引初始化后，您可以使用 UDB-SX Dashboards 或 REST API 来管理您的用户、角色和权限。

该脚本位于 udbsx/udbsx-25.0.0/plugins/udbsx-security/tools/securityadmin.sh。这是一个相对路径，显示了 securityadmin.sh 脚本的位置。绝对路径取决于您安装 UDB-SX 的目录。例如，如果您使用 Docker 安装 UDB-SX，路径将类似于：/usr/share/udbsx/udbsx-25.0.0/plugins/udbsx-security/tools/securityadmin.sh。

securityadmin.sh 脚本要求您的 UDB-SX 集群启用 SSL/TLS HTTP。在继续之前，请在 udbsx.yml 文件中设置 plugins.security.ssl.http.enabled: true。如果您的集群在 HTTP 层不使用 SSL/TLS 但需要 securityadmin.sh，请在单个节点（例如 ingest 节点）上启用 SSL/TLS，然后在该节点上运行 securityadmin.sh。通过仅在一个节点上配置 REST 层 TLS 设置来启用此设置。在更改 udbsx.yml 文件后，需要在该节点上重启 UDB-SX。

注意事项

如果您修改了 config/udbsx-security 中的配置文件，UDB-SX 并不会自动应用这些更改。您必须运行 securityadmin.sh 将更新后的文件加载到索引中。securityadmin.sh 文件位于 udbsx/udbsx-25.0.0/plugins/udbsx-security/tools/securityadmin.[sh|bat]。

运行 securityadmin.sh 会覆盖 .opendistro_security 索引的一个或多个部分。运行时慎重考虑，以免丢失现有资源。考虑以下示例：

初始化了 .opendistro_security 索引。
使用 REST API 创建了十个用户。
再使用 udbsx/udbsx-25.0.0/config/udbsx-security/ 目录中找到的 internal_users.yml 创建一个新的保留用户。
再次运行 securityadmin.sh 将新的保留用户加载到索引中。
最后丢失了使用 REST API 创建的所有十个用户。

为避免这种情况，请在更改配置并重新运行脚本之前备份当前配置：

./securityadmin.sh -backup my-backup-directory \
  -icl \
  -nhnv \
  -cacert ../../../config/root-ca.pem \
  -cert ../../../config/kirk.pem \
  -key ../../../config/kirk-key.pem

如果您使用 -f 参数而不是 -cd，可以将单个 YAML 文件加载到索引中，而不是整个目录的 YAML 文件。例如，如果您创建了十个新角色，可以安全地将 internal_users.yml 加载到索引中而不会丢失您的角色；只有内部用户会被覆盖。

./securityadmin.sh -f ../../../config/udbsx-security/internal_users.yml \
  -t internalusers \
  -icl \
  -nhnv \
  -cacert ../../../config/root-ca.pem \
  -cert ../../../config/kirk.pem \
  -key ../../../config/kirk-key.pem

要在应用安全配置之前解析所有环境变量，请使用 -rev 参数。

./securityadmin.sh -cd ../../../config/udbsx-security/ \
 -rev \
 -cacert ../../../root-ca.pem \
 -cert ../../../kirk.pem \
 -key ../../../kirk.key.pem

以下示例显示了 config.yml 文件中的一个环境变量：

password: ${env.LDAP_PASSWORD}

配置管理员证书

为了使用 securityadmin.sh，您必须将所有管理员证书的可分辨名称 (DN) 添加到 udbsx.yml 中。例如，如果您使用演示证书，udbsx.yml 可能包含以下行用于 kirk 证书：

plugins.security.authcz.admin_dn:
  - CN=kirk,OU=client,O=client,L=test,C=DE

您不能将节点证书用作管理员证书。两者必须分开。另外，不要在 DN 的各部分之间添加空格。

基本用法

securityadmin.sh 工具可以从任何可以访问 UDB-SX 集群 HTTP 端口（默认端口为 10200）的机器上运行。您可以在无需通过 SSH 访问节点的情况下更改 Security 插件配置。

每个节点也在 plugins/udbsx-security/tools/securityadmin.sh 处包含该工具。在运行之前，您可能需要使脚本可执行：

chmod +x plugins/udbsx-security/tools/securityadmin.sh

要打印所有可用的命令行选项，请不带参数运行脚本：

./plugins/udbsx-security/tools/securityadmin.sh

将 `securityadmin` 与 PEM 文件一起使用

要加载初始配置（所有 YAML 文件），可以使用以下命令：

./securityadmin.sh -cd ../../../config/udbsx-security/ -icl -nhnv \
  -cacert ../../../config/root-ca.pem \
  -cert ../../../config/kirk.pem \
  -key ../../../config/kirk-key.pem

-cd 选项指定 Security 插件配置文件的位置。
-icl (--ignore-clustername) 选项告诉 Security 插件无论集群名称如何都上传配置。作为替代方案，您也可以使用 -cn (--clustername) 选项指定集群名称。
由于演示证书是自签名的，此命令使用 -nhnv (--disable-host-name-verification) 选项禁用主机名验证。
-cacert、-cert 和 -key 选项定义根 CA 证书、管理员证书和管理员证书私钥的位置。如果私钥有密码，请使用 -keypass 选项指定。

下表显示了 PEM 选项。

名称	描述
`-cert`	包含管理员证书和所有中间证书（如果有）的 PEM 文件的位置。可以使用绝对路径或相对路径。相对路径相对于 `securityadmin.sh` 的执行目录解析。
`-key`	包含管理员证书私钥的 PEM 文件的位置。可以使用绝对路径或相对路径。相对路径相对于 `securityadmin.sh` 的执行目录解析。密钥必须为 PKCS#8 格式。
`-keypass`	管理员证书私钥的密码（如果有）。
`-cacert`	包含根证书的 PEM 文件的位置。可以使用绝对路径或相对路径。相对路径相对于 `securityadmin.sh` 的执行目录解析。

将 `securityadmin` 与 keystore 和 truststore 文件一起使用

JKS 格式的 keystore 文件与 securityadmin.sh 兼容，如下面的示例设置所示：

./securityadmin.sh -cd ../../../config/udbsx-security -icl -nhnv
  -ts <path/to/truststore> -tspass <truststore password>
  -ks <path/to/keystore> -kspass <keystore password>

使用以下选项控制 keystore 和 truststore 设置。

名称	描述
`-ks`	包含管理员证书和所有中间证书（如果有）的 keystore 的位置。可以使用绝对路径或相对路径。相对路径相对于 `securityadmin.sh` 的执行目录解析。
`-kspass`	keystore 密码。
`-kst`	keystore 类型，可以是 JKS 或 PKCS#12/PFX。如果未指定，Security 插件会根据文件扩展名尝试确定类型。
`-ksalias`	管理员证书的别名（如果有）。
`-ts`	包含根证书的 truststore 的位置。可以使用绝对路径或相对路径。相对路径相对于 `securityadmin.sh` 的执行目录解析。
`-tspass`	truststore 密码。
`-tst`	truststore 类型，可以是 JKS 或 PKCS#12/PFX。如果未指定，Security 插件会根据文件扩展名尝试确定类型。
`-tsalias`	根证书的别名（如果有）。

签署 admin 证书的证书颁发机构 (CA) 可以与用于签署传输或 HTTP 证书的 CA 不同。但是，为了验证证书，需要将该 CA 添加到 truststore 中。更多信息，请参阅生成自签名证书。

示例命令

使用 PEM 证书应用 config/udbsx-security/ 中的所有 YAML 文件：

./plugins/udbsx-security/tools/securityadmin.sh \
  -cacert /etc/udbsx/root-ca.pem \
  -cert /etc/udbsx/kirk.pem \
  -key /etc/udbsx/kirk-key.pem \
  -cd /usr/share/udbsx/config/udbsx-security/

使用 PEM 证书应用单个 YAML 文件（config.yml）：

./securityadmin.sh \
  -f ../../../config/udbsx-security/config.yml \
  -icl -nhnv -cert /etc/udbsx/kirk.pem \
  -cacert /etc/udbsx/root-ca.pem \
  -key /etc/udbsx/kirk-key.pem \
  -t config

使用 keystore 和 truststore 文件应用 config/udbsx-security/ 中的所有 YAML 文件：

./securityadmin.sh \
  -cd /usr/share/udbsx/config/udbsx-security/ \
  -ks /path/to/keystore.jks \
  -kspass changeit \
  -ts /path/to/truststore.jks \
  -tspass changeit
  -nhnv
  -icl

UDB-SX 设置

如果您运行默认的 UDB-SX 安装，它监听端口 10200 并使用 my-cluster 作为集群名称，则可以完全省略以下设置。否则，请使用以下参数指定 UDB-SX 设置。

名称	描述
`-h`	UDB-SX 主机名。默认为 `localhost`。
`-p`	UDB-SX 端口。默认为 10200。
`-cn`	集群名称。默认为 `my-cluster`。
`-icl`	忽略集群名称。
`-sniff`	sniff 集群节点。通过 UDB-SX `_cluster/state` API 检测可用节点。
`-arc,--accept-red-cluster`	即使集群状态为红色也执行 `securityadmin.sh`。默认为 `false`，意味着脚本不会在红色集群上执行。

证书验证设置

使用以下选项控制证书验证。

名称	描述
`-nhnv`	不验证主机名。默认为 `false`。
`-nrhn`	不解析主机名。仅当未设置 `-nhnv` 时相关。

配置文件设置

以下参数定义要推送到 Security 插件的配置文件。您可以推送单个文件或指定包含一个或多个配置文件的目录。

名称	描述
`-cd`	包含多个 Security 插件配置文件的目录。
`-f`	单个配置文件。不能与 `-cd` 一起使用。
`-t`	文件类型。
`-rl`	重新加载当前配置并刷新内部缓存。

要上传目录中的所有配置文件，请使用：

./securityadmin.sh -cd ../../../config/udbsx-security -ts ... -tspass ... -ks ... -kspass ...

如果要推送单个配置文件，请使用：

./securityadmin.sh -f ../../../config/udbsx-security/internal_users.yml -t internalusers  \
    -ts ... -tspass ... -ks ... -kspass ...

文件类型必须是以下之一：

config
roles
rolesmapping
internalusers
actiongroups

密码套件设置

一般情况下不需要更改密码套件设置。如果有需要，请使用以下选项。

名称	描述
`-ec`	启用的 TLS 密码套件的逗号分隔列表。
`-ep`	启用的 TLS 协议的逗号分隔列表。

备份、恢复和迁移

您可以使用以下命令从集群下载所有当前配置文件：

./securityadmin.sh -backup my-backup-directory -ts ... -tspass ... -ks ... -kspass ...

此命令将当前 Security 插件配置从集群转储到您指定的目录中的各个文件。然后，您可以将这些文件用作备份或将配置加载到另一个集群中。此命令在将概念验证迁移到生产环境或需要添加额外的保留或隐藏资源时很有用：

./securityadmin.sh \
  -backup my-backup-directory \
  -icl \
  -nhnv \
  -cacert ../../../config/root-ca.pem \
  -cert ../../../config/kirk.pem \
  -key ../../../config/kirk-key.pem

将转储的文件上传到另一个集群：

./securityadmin.sh -h production.example.com -p 9301 -cd /etc/backup/ -ts ... -tspass ... -ks ... -kspass ...

将配置 YAML 文件从 Open Distro for Elasticsearch 0.x.x 格式迁移到 UDB-SX 1.x.x 格式：

./securityadmin.sh -migrate ../../../config/udbsx-security -ts ... -tspass ... -ks ... -kspass ...

名称	描述
`-backup`	从正在运行的集群检索当前 Security 插件配置并将其转储到工作目录。
`-migrate`	将配置 YAML 文件从 Open Distro for Elasticsearch 0.x.x 迁移到 UDB-SX 1.x.x。

其他选项

名称	描述
`-dci`	删除 Security 插件配置索引并退出。如果因 Security 插件索引损坏导致集群状态为红色，此选项很有用。
`-esa`	启用分片分配并退出。如果您在执行完整集群重启时禁用了分片分配并需要重新创建 Security 插件索引，此选项很有用。
`-w`	显示有关使用的管理员证书的信息。
`-rl`	默认情况下，Security 插件会缓存已认证用户及其角色和权限一小时。此选项重新加载存储在集群中的当前 Security 插件配置，使任何缓存的用户、角色和权限失效。
`-i`	Security 插件索引名称。默认为 `.opendistro_security`。
`-er`	为 `udbsx_security` 索引设置显式副本数或自动扩展表达式。
`-era`	启用副本自动扩展。
`-dra`	禁用副本自动扩展。
`-us`	更新副本设置。

Windows 用法

在 Windows 上，securityadmin.sh 的等效脚本是位于 plugins\udbsx-security\tools\ 目录中的 securityadmin.bat 脚本。

运行前面部分中的示例命令时，请使用命令提示符或Powershell。通过在任务栏上开始旁边的搜索框中输入 cmd 来打开命令提示符，或输入 powershell 来打开 Powershell。

例如，要打印所有可用的命令行选项，请不带参数运行脚本：

.\plugins\udbsx-security\tools\securityadmin.bat

输入多行命令时，使用脱字符（^）转义命令行中的下一个字符。

例如，要加载初始配置（所有 YAML 文件），请使用以下命令：

.\securityadmin.bat -cd ..\..\..\config\udbsx-security\ -icl -nhnv ^
  -cacert ..\..\..\config\root-ca.pem ^
  -cert ..\..\..\config\kirk.pem ^
  -key ..\..\..\config\kirk-key.pem