Applying changes to configuration files

On Windows, use securityadmin.bat in place of securityadmin.sh. For more information, see Windows usage.

The Security plugin stores its configuration—including users, roles, permissions, and backend settings—in a system index on the OpenSearch cluster. Storing these settings in an index lets you change settings without restarting the cluster and eliminates the need to edit configuration files on every individual node. This is accomplished by running the securityadmin.sh script.

The first job of the script is to initialize the .opendistro_security index. This loads your initial configuration into the index using the configuration files in /config/opensearch-security. After the .opendistro_security index is initialized, you can use OpenSearch Dashboards or the REST API to manage your users, roles, and permissions.

The script can be found at /plugins/opensearch-security/tools/securityadmin.sh. This is a relative path showing where the securityadmin.sh script is located. The absolute path depends on the directory where you’ve installed OpenSearch. For example, if you use Docker to install OpenSearch, the path will resemble the following: /usr/share/opensearch/plugins/opensearch-security/tools/securityadmin.sh.

The securityadmin.sh script requires SSL/TLS HTTP to be enabled for your OpenSearch cluster. Set plugins.security.ssl.http.enabled: true in your opensearch.yml file before proceeding. If your cluster does not use SSL/TLS on the HTTP layer but requires securityadmin.sh, enable SSL/TLS on a single node, such as theingest node, and then run securityadmin.sh on that node. Enable this setting by configuring the REST layer TLS settings on only one node. Restarting OpenSearch on that node is necessary following any change to the opensearch.yml file.

A word of caution

If you make changes to the configuration files in config/opensearch-security, OpenSearch does not automatically apply these changes. Instead, you must run securityadmin.sh to load the updated files into the index. The securityadmin.sh file can be found in <OPENSEARCH_HOME>/plugins/opensearch-security/tools/securityadmin.[sh|bat].

Running securityadmin.sh overwrites one or more portions of the .opendistro_security index. Run it with extreme care to avoid losing your existing resources. Consider the following example:

1. You initialize the .opendistro_security index.
2. You create ten users using the REST API.
3. You decide to create a new reserved user using internal_users.yml, found in <OPENSEARCH_HOME>/config/opensearch-security/ directory.
4. You run securityadmin.sh again to load the new reserved user into the index.
5. You lose all ten users that you created using the REST API.

To avoid this situation, back up your current configuration before making changes and re-running the script:

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

If you use the -f argument rather than -cd, you can load a single YAML file into the index rather than the entire directory of YAML files. For example, if you create ten new roles, you can safely load internal_users.yml into the index without losing your roles; only the internal users get overwritten.

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

To resolve all environment variables before applying the security configurations, use the -rev parameter.

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

The following example shows an environment variable in the config.yml file:

password: ${env.LDAP_PASSWORD}

Configure the admin certificate

In order to use securityadmin.sh, you must add the distinguished names (DNs) of all admin certificates to opensearch.yml. If you use the demo certificates, for example, opensearch.yml might contain the following lines for the kirk certificate:

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

You can’t use node certificates as admin certificates. The two must be separate. Also, do not add white space between the parts of the DN.

Basic usage

The securityadmin.sh tool can be run from any machine that has access to the HTTP port of your OpenSearch cluster (the default port is 9200). You can change the Security plugin configuration without having to access your nodes through SSH.

Each node also includes the tool at plugins/opensearch-security/tools/securityadmin.sh. You might need to make the script executable before running it:

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

To print all available command line options, run the script with no arguments:

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

Using securityadmin with PEM files

To load your initial configuration (all YAML files), you might use the following command:

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

• The -cd option specifies where the Security plugin configuration files can be found.
• The -icl (--ignore-clustername) option tells the Security plugin to upload the configuration regardless of the cluster name. As an alternative, you can also specify the cluster name with the -cn (--clustername) option.
• Because the demo certificates are self-signed, this command disables hostname verification with the -nhnv (--disable-host-name-verification) option.
• The -cacert, -cert and -key options define the location of your root CA certificate, the admin certificate, and the private key for the admin certificate. If the private key has a password, specify it with the -keypass option.

The following table shows the PEM options.

Using securityadmin with keystore and truststore files

JKS format keystore files are compatible with securityadmin.sh, as shown in the following example setting:

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

Use the following options to control the keystore and truststore settings.

The certificate authority (CA) that signs the admin certificate can differ from the one used for signing transport or HTTP certificates. The CA does, however, need to be added to the truststore in order to validate the certificate. See Generate node and client certificates for more information.

Sample commands

Apply all YAML files in config/opensearch-security/ using PEM certificates:

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

Apply a single YAML file (config.yml) using PEM certificates:

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

Apply all YAML files in config/opensearch-security/ with keystore and truststore files:

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

OpenSearch settings

If you run a default OpenSearch installation, which listens on port 9200 and uses opensearch as a cluster name, you can omit the following settings altogether. Otherwise, specify your OpenSearch settings by using the following switches.

Certificate validation settings

Use the following options to control certificate validation.

Configuration files settings

The following switches define which configuration files you want to push to the Security plugin. You can either push a single file or specify a directory containing one or more configuration files.

To upload all configuration files in a directory, use this:

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

If you want to push a single configuration file, use this:

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

The file type must be one of the following:

• config
• roles
• rolesmapping
• internalusers
• actiongroups

Cipher settings

You probably won’t need to change cipher settings. If you need to, use the following options.

Backup, restore, and migrate

You can download all current configuration files from your cluster with the following command:

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

This command dumps the current Security plugin configuration from your cluster to individual files in the directory you specify. You can then use these files as backups or to load the configuration into a different cluster. This command is useful when moving a proof-of-concept to production or if you need to add additional reserved or hidden resources:

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

To upload the dumped files to another cluster:

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

To migrate configuration YAML files from the Open Distro for Elasticsearch 0.x.x format to the OpenSearch 1.x.x format:

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

Other options

Windows usage

On Windows, the equivalent of securityadmin.sh is the securityadmin.bat script located in the \path\to\opensearch-2.18.0\plugins\opensearch-security\tools\ directory.

When running the example commands in the preceding sections, use the command prompt or Powershell. Open the command prompt by entering cmd or Powershell by entering powershell in the search box next to Start on the taskbar.

For example, to print all available command line options, run the script with no arguments:

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

When entering a multiline command, use the caret (^) character to escape the next character in the command line.

For example, to load your initial configuration (all YAML files), use the following command:

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