Apply configuration changes

The Security plugin stores its configuration—including users, roles, and permissions—in an index on the Elasticsearch cluster (.opendistro_security). Storing these settings in an index lets you change settings without restarting the cluster and eliminates the need to place configuration files on any node.

After changing any of the configuration files in plugins/opendistro_security/securityconfig, however, you must run plugins/opendistro_security/tools/securityadmin.sh to load these new settings into the index. This script identifies itself against a cluster through an admin TLS certificate, in .pem, .jks, .p12, or .pfx format.

If the .opendistro_security index is already initialized, you can also use Kibana to change users, roles, and permissions. However, you need to run securityadmin.sh at least once to initialize the index and configure your authentication and authorization methods.

Table of contents

1. Configure the admin certificate
2. Basic usage
3. Sample commands
4. Using securityadmin with Keystore and Truststore files
   1. Elasticsearch settings
   2. Certificate validation settings
   3. Configuration files settings
   4. Cipher settings
   5. Backup and Restore
   6. Other options

Configure the admin certificate

You can configure all certificates that should have admin privileges in elasticsearch.yml stating their respective Distinguished Names (DNs). If you use the demo certificates, for example, you can use the kirk certificate:

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

Do not use node certificates as admin certificates. Best practice is to keep these certificates separate. Also, do not use any whitespace between the parts of the DN.

Basic usage

securityadmin.sh can be run from any machine that has access to the transport port of your Elasticsearch cluster (default is 9300); you can change the Security plugin configuration without having to access your nodes via SSH.

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

chmod +x plugins/opendistro_security/tools/securityadmin.sh

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

./plugins/opendistro_security/tools/securityadmin.sh

To load configuration changes to Security plugin, you need to provide your admin certificate to the tool:

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

• The -cd option speficies where the Security plugin configuration files to upload to the cluster 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, we also disable 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.

All PEM options:

Sample commands

Apply configuration in securityconfig using PEM certificates:

/usr/share/elasticsearch/plugins/opendistro_security/tools/securityadmin.sh -cacert /etc/elasticsearch/root-ca.pem -cert /etc/elasticsearch/kirk.pem -key /etc/elasticsearch/kirk-key.pem -cd /usr/share/elasticsearch/plugins/opendistro_security/securityconfig/

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

./securityadmin.sh -f ../securityconfig/config.yml -icl -nhnv -cert /etc/elasticsearch/kirk.pem -cacert /etc/elasticsearch/root-ca.pem -h -key /etc/elasticsearch/kirk-key.pem -t config

Apply configuration in securityconfig with keystore and truststore files:

./securityadmin.sh \
   -cd /usr/share/elasticsearch/plugins/opendistro_security/securityconfig/ \
   -ks /path/to/keystore.jks \
   -kspass changeit \
   -ts /path/to/truststore.jks \
   -tspass changeit
   -nhnv
   -icl

Using securityadmin with Keystore and Truststore files

You can also use keystore files in JKS format in conjunction with securityadmin.sh:

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

Use the following options to control the key and truststore settings:

Elasticsearch settings

If you run a default Elasticsearch installation, which listens on transport port 9300, and uses elasticsearch as cluster name, you can omit the following settings altogether. Otherwise, specify your Elasticsearch 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 file(s) 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:

./securityadmin.sh -cd ../securityconfig -ts ... -tspass ... -ks ... -kspass ...

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

./securityadmin.sh -f ../securityconfig/internal_users.yml -t internalusers  \
    -ts ... -tspass ... -ks ... -kspass ...

The file type must be one of:

• 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 and Restore

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

./securityadmin.sh -r -ts ... -tspass ... -ks ... -kspass ...

This command dumps the current Security plugin configuration from your cluster to individual files in the working directory. 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.

You can specify the download location with the -cd option:

./securityadmin.sh -r -h staging.example.com -p 9300  \
    -cd /etc/backup/ -ts ... -tspass ... -ks ... -kspass ...

To upload the dumped files to another cluster:

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

Other options