elasticsearch-certutil

Generate a new Certificate Authority (CA) with default options

$ elasticsearch-certutil ca

$ elasticsearch-certutil cert

$ elasticsearch-certutil cert [[-s|--silent]] --pem

$ elasticsearch-certutil http

$ elasticsearch-certutil transport [[-s|--silent]]

$ elasticsearch-certutil csr

$ elasticsearch-certutil password

$ elasticsearch-certutil password --pass [password]

bin/elasticsearch-certutil <command> [options]

command: ca
    Generates a new self-signed Certificate Authority (CA) certificate and its private key. This CA can then be used to sign other certificates for your cluster.

command: cert
    Generates a new certificate and its private key. This certificate can be self-signed or signed by an existing CA generated by certutil ca or an external CA. It's versatile for node, HTTP, or general-purpose certificates.

command: csr
    Generates a Certificate Signing Request (CSR) and a private key. The CSR can then be submitted to an external Certificate Authority for signing to obtain a trusted certificate.

command: http
    A specialized subcommand to generate certificates specifically for the HTTP layer, typically used for securing communication between clients (like Kibana or web browsers) and the Elasticsearch REST API. Internally, it uses the cert command with appropriate defaults.

command: node
    A specialized subcommand to generate certificates for secure inter-node communication within the Elasticsearch cluster. Internally, it uses the cert command with appropriate defaults.

--ca-cert <file>
    Specifies the path to the Certificate Authority (CA) certificate file to be used for signing the new certificate.

--ca-key <file>
    Specifies the path to the Certificate Authority (CA) private key file corresponding to the CA certificate, used for signing.

--days <N>
    Sets the validity period for the generated certificate in days. Certificates will expire after this duration.

--dns <name>
    Adds a DNS name as a Subject Alternative Name (SAN) to the certificate. This option can be specified multiple times for multiple DNS names. Essential for host verification.

--ip <address>
    Adds an IP address as a Subject Alternative Name (SAN) to the certificate. This option can be specified multiple times for multiple IP addresses. Essential for host verification.

--out <file>
    Specifies the full path and filename for the output file where the generated certificate and private key (typically in PKCS#12 or PEM format) will be saved.

--pass <password>
    Assigns a password to encrypt the private key within the output file. This is crucial for securing the private key.

--pem
    Outputs the generated certificate and private key in PEM format (.crt and .key files), rather than the default PKCS#12 format (.p12).

--multiple
    Triggers an interactive mode that allows generating multiple certificates in a single run, prompting for details for each.

--silent
    Executes the command in non-interactive mode, suppressing all prompts and using default or specified values.

--help
    Displays help information for the elasticsearch-certutil command or a specific subcommand.

--verbose
    Enables more detailed output during the certificate generation process, useful for debugging.

The elasticsearch-certutil command is a crucial utility provided by Elasticsearch for managing Transport Layer Security (TLS) certificates and keys. It simplifies the process of securing communication within an Elasticsearch cluster, covering both inter-node communication and HTTP client connections (e.g., Kibana, applications). It can generate self-signed Certificate Authorities (CAs), create node certificates, HTTP certificates, and Certificate Signing Requests (CSRs) for use with external CAs. This tool is essential for enabling encrypted communication and identity verification, ensuring the integrity and confidentiality of data flowing through the cluster.

Key Security: The private keys generated by elasticsearch-certutil are highly sensitive. They must be protected with strong passwords and strict file system permissions. Losing or compromising these keys can severely undermine your cluster's security.

Certificate Expiration: Certificates have a defined validity period (set with --days). Ensure you have a plan for regenerating and replacing certificates before they expire to avoid service interruptions.

Subject Alternative Names (SANs): It's critical to include all hostnames (DNS names) and IP addresses that clients will use to connect to your Elasticsearch nodes in the certificate's SANs using --dns and --ip. Failure to do so will result in certificate validation errors.

Cluster Restart: After replacing certificates on an Elasticsearch node, the node (and often the entire cluster, in a rolling fashion) must be restarted for the new certificates to take effect.

For production deployments, consider generating your CA and node/HTTP certificates using a robust external CA or following a strict internal CA policy. The generated private keys should be stored securely, ideally in a hardware security module (HSM) or a secure vault. Automate certificate rotation processes to minimize manual intervention and ensure continuous security.

When deploying, ensure that the generated certificate and key files have appropriate read-only permissions for the Elasticsearch user and are not world-readable. Misconfigured permissions are a common security vulnerability.

By default, elasticsearch-certutil outputs certificates and keys in PKCS#12 format (a single .p12 file containing both). This is often convenient for distribution. However, the --pem flag can be used to output separate .crt (certificate) and .key (private key) files in PEM format, which might be preferred by some applications or for easier inspection.

The elasticsearch-certutil command was introduced as part of Elasticsearch's X-Pack security features (later bundled into the free Basic license). Its development was driven by the increasing need for robust, built-in TLS/SSL capabilities to secure data in transit within and around Elasticsearch clusters. It provides a convenient, Elasticsearch-specific abstraction over general-purpose cryptographic tools, simplifying certificate management for administrators.

openssl(1), keytool(1), elasticsearch-setup-passwords(1)