elasticsearch-syskeygen

Generate the system_key file in the default $ES_HOME/config directory

$ elasticsearch-syskeygen

elasticsearch-syskeygen [--force]
[--path.conf path]

--force
    Forces the generation of a new system key, overwriting any existing key in the keystore without prompting for confirmation. Use with caution as it will invalidate previously encrypted data if not handled properly.

--path.conf
    Specifies the path to the Elasticsearch configuration directory (e.g., /etc/elasticsearch). This tells the command where to locate or create the Elasticsearch keystore. If not specified, the command will attempt to use default locations or environment variables.

The elasticsearch-syskeygen command is a utility provided with Elasticsearch to generate a system key. This key is crucial for enhancing the security of your Elasticsearch cluster by encrypting sensitive information stored within the Elasticsearch keystore. It ensures that sensitive settings, such as passwords for realms or repository credentials, are stored securely on disk. When this command is executed, it creates a new system key, stores it in the configured Elasticsearch keystore, and marks it for use in encrypting future entries or decrypting existing ones. The system key is essential for features like built-in security and encrypted settings in the keystore. Without a valid system key, certain security features might not function correctly, and sensitive data could be less protected.

The system key is highly sensitive. Losing or compromising this key can render encrypted data in your Elasticsearch keystore inaccessible or vulnerable. Always ensure proper filesystem permissions are set on the keystore and the system key file, typically allowing read/write only to the Elasticsearch user. It is critical to back up your system key in a secure, offline location. This key is typically node-specific; ensure consistency if managing multiple nodes manually in a cluster where shared encrypted settings are used.

The elasticsearch-syskeygen command implicitly interacts with the Elasticsearch keystore. Before generating a key, ensure the keystore is initialized (e.g., using elasticsearch-keystore create). The system key is stored within this keystore, protecting sensitive data such as realm passwords and secure settings.

It is paramount to back up the generated system key. While the command places it in the keystore, having a secure, offline backup is crucial for disaster recovery. Without it, recovering encrypted data after a system failure or accidental keystore corruption would be impossible.

Ensure that the user running the elasticsearch-syskeygen command has appropriate read and write permissions to the Elasticsearch configuration directory and the keystore file. Incorrect permissions can prevent the key from being generated or properly stored, leading to security and operational issues.

The system key feature was introduced in Elasticsearch primarily to enhance security by allowing encryption of sensitive settings within the Elasticsearch keystore, alongside the broader development of X-Pack security features. Its purpose evolved as Elasticsearch's security capabilities matured, providing a more robust mechanism for protecting credentials and other confidential data stored on disk. This command streamlines the process of generating this vital security component.

elasticsearch-keystore(1), elasticsearch(1)