[role="xpack"]
[[certgen]]
== certgen

The `certgen` command simplifies the creation of certificate authorities (CA),
certificate signing requests (CSR), and signed certificates for use with the
Elastic Stack.

[float]
=== Synopsis

[source,shell]
--------------------------------------------------
bin/x-pack/certgen
(([--cert <cert_file>] [--days <n>] [--dn <name>] [--key <key_file>]
[--keysize <bits>] [--pass <password>] [--p12 <password>])
| [--csr])
[-E <KeyValuePair>] [-h, --help] [--in <input_file>] [--out <output_file>]
([-s, --silent] | [-v, --verbose])
--------------------------------------------------

[float]
=== Description

By default, the command runs in interactive mode and you are prompted for
information about each instance. An instance is any piece of the Elastic Stack
that requires a Transport Layer Security (TLS) or SSL certificate. Depending on
your configuration, {es}, Logstash, {kib}, and Beats might all require a
certificate and private key.

The minimum required value for each instance is a name. This can simply be the
hostname, which is used as the Common Name of the certificate. You can also use
a full distinguished name. IP addresses and DNS names are optional. Multiple
values can be specified as a comma separated string. If no IP addresses or DNS
names are provided, you might disable hostname verification in your TLS or SSL
configuration.

Depending on the parameters that you specify, you are also prompted for
necessary information such as the path for the output file and the CA private
key password.

The `certgen` command also supports a silent mode of operation to enable easier
batch operations. For more information, see <<certgen-silent>>.

The output file is a zip file that contains the signed certificates and private
keys for each instance. If you chose to generate a CA, which is the default
behavior, the certificate and private key are included in the output file. If
you chose to generate CSRs, you should provide them to your commercial or
organization-specific certificate authority to obtain signed certificates. The
signed certificates must be in PEM format to work with {security}.

[float]
=== Parameters

`--cert <cert_file>`:: Specifies to generate new instance certificates and keys
using an existing CA certificate, which is provided in the `<cert_file>` argument.
This parameter cannot be used with the `-csr` parameter.

`--csr`:: Specifies to operation in certificate signing request mode.

`--days <n>`::
Specifies an integer value that represents the number of days the generated keys
are valid. The default value is `1095`. This parameter cannot be used with the
`-csr` parameter.

`--dn <name>`::
Defines the _Distinguished Name_ that is used for the generated CA certificate.
The default value is `CN=Elastic Certificate Tool Autogenerated CA`.
This parameter cannot be used with the `-csr` parameter.

`-E <KeyValuePair>`:: Configures a setting.

`-h, --help`:: Returns all of the command parameters.

`--in <input_file>`:: Specifies the file that is used to run in silent mode. The
input file must be a YAML file, as described in <<certgen-silent>>.

`--key <key_file>`:: Specifies the _private-key_ file for the CA certificate.
This parameter is required whenever the `-cert` parameter is used.

`--keysize <bits>`::
Defines the number of bits that are used in generated RSA keys. The default
value is `2048`.

`--out <output_file>`:: Specifies a path for the output file.

`--pass <password>`:: Specifies the password for the CA private key.
If the `-key` parameter is provided, then this is the password for the existing
private key file. Otherwise, it is the password that should be applied to the
generated CA key. This parameter cannot be used with the `-csr` parameter.

`--p12 <password>`::
Generate a PKCS#12 (`.p12` or `.pfx`) container file for each of the instance
certificates and keys. The generated file is protected by the supplied password,
which can be blank. This parameter cannot be used with the `-csr` parameter.

`-s, --silent`:: Shows minimal output.

`-v, --verbose`:: Shows verbose output.

[float]
=== Examples

////
The tool can be used interactively:

[source,shell]
--------------------------------------------------
bin/x-pack/certgen
--------------------------------------------------
This tool assists you in the generation of X.509 certificates and certificate
signing requests for use with SSL in the Elastic stack. Depending on the command
line option specified, you may be prompted for the following:

* The path to the output file
    * The output file is a zip file containing the signed certificates and
      private keys for each instance. If a Certificate Authority was generated,
      the certificate and private key will also be included in the output file.
* Information about each instance
    * An instance is any piece of the Elastic Stack that requires a SSL certificate.
      Depending on your configuration, Elasticsearch, Logstash, Kibana, and Beats
      may all require a certificate and private key.
    * The minimum required value for each instance is a name. This can simply be the
      hostname, which will be used as the Common Name of the certificate. A full
      distinguished name may also be used.
    * IP addresses and DNS names are optional. Multiple values can be specified as a
      comma separated string. If no IP addresses or DNS names are provided, you may
      disable hostname verification in your SSL configuration.
* Certificate Authority private key password
    * The password may be left empty if desired.

Let's get started...

Please enter the desired output file [/home/es/config/x-pack/certificate-bundle.zip]:
Enter instance name: node01
Enter name for directories and files [node01]:
Enter IP Addresses for instance (comma-separated if more than one) []: 10.10.0.1
Enter DNS names for instance (comma-separated if more than one) []: node01.mydomain.com,node01
Would you like to specify another instance? Press 'y' to continue entering instance information: y
Enter instance name: node02
Enter name for directories and files [node02]:
Enter IP Addresses for instance (comma-separated if more than one) []: 10.10.0.2
Enter DNS names for instance (comma-separated if more than one) []: node02.mydomain.com
Would you like to specify another instance? Press 'y' to continue entering instance information:
Certificates written to /home/es/config/x-pack/certificate-bundle.zip

This file should be properly secured as it contains the private keys for all
instances and the certificate authority.

After unzipping the file, there will be a directory for each instance containing
the certificate and private key. Copy the certificate, key, and CA certificate
to the configuration directory of the Elastic product that they will be used for
and follow the SSL configuration instructions in the product guide.

For client applications, you may only need to copy the CA certificate and
configure the client to trust this certificate.
....
--------------------------------------------------

In this example, the command generates a zip file with the CA certificate,
private key, two signed certificates and keys in PEM format for `node01` and
`node02`.
////
////
When using a commercial or organization specific CA, the `certgen` tool can be
used to generate certificate signing requests (CSR) for the nodes in your
cluster:

[source,shell]
--------------------------------------------------
....
bin/x-pack/certgen -csr
This tool assists you in the generation of X.509 certificates and certificate
signing requests for use with SSL in the Elastic stack. Depending on the command
line option specified, you may be prompted for the following:

* The path to the output file
    * The output file is a zip file containing the certificate signing requests
      and private keys for each instance.
* Information about each instance
    * An instance is any piece of the Elastic Stack that requires a SSL certificate.
      Depending on your configuration, Elasticsearch, Logstash, Kibana, and Beats
      may all require a certificate and private key.
    * The minimum required value for each instance is a name. This can simply be the
      hostname, which will be used as the Common Name of the certificate. A full
      distinguished name may also be used.
    * IP addresses and DNS names are optional. Multiple values can be specified as a
      comma separated string. If no IP addresses or DNS names are provided, you may
      disable hostname verification in your SSL configuration.

Let's get started...

Please enter the desired output file [/home/es/config/x-pack/csr-bundle.zip]:
Enter instance name: node01
Enter name for directories and files [node01]:
Enter IP Addresses for instance (comma-separated if more than one) []: 10.10.0.1
Enter DNS names for instance (comma-separated if more than one) []: node01.mydomain.com,node01
Would you like to specify another instance? Press 'y' to continue entering instance information: y
Enter instance name: node02
Enter name for directories and files [node02]:
Enter IP Addresses for instance (comma-separated if more than one) []: 10.10.0.2
Enter DNS names for instance (comma-separated if more than one) []: node02.mydomain.com
Would you like to specify another instance? Press 'y' to continue entering instance information:
Certificate signing requests written to /Users/jmodi/dev/tmp/elasticsearch-5.0.0-alpha5-SNAPSHOT/config/x-pack/csr-bundle.zip

This file should be properly secured as it contains the private keys for all
instances.

After unzipping the file, there will be a directory for each instance containing
the certificate signing request and the private key. Provide the certificate
signing requests to your certificate authority. Once you have received the
signed certificate, copy the signed certificate, key, and CA certificate to the
configuration directory of the Elastic product that they will be used for and
follow the SSL configuration instructions in the product guide.
....
--------------------------------------------------

In this case, the command generates a zip file with two CSRs and private
keys. The CSRs should be provided to the CA in order to obtain the signed
certificates. The signed certificates will need to be in PEM format in order to
be used.
////
[float]
[[certgen-silent]]
==== Using `certgen` in Silent Mode

To use the silent mode of operation, you must create a YAML file that contains
information about the instances. It must match the following format:

[source, yaml]
--------------------------------------------------
instances:
  - name: "node1" <1>
    ip: <2>
      - "192.0.2.1"
    dns: <3>
      - "node1.mydomain.com"
  - name: "node2"
    ip:
      - "192.0.2.2"
      - "198.51.100.1"
  - name: "node3"
  - name: "node4"
    dns:
      - "node4.mydomain.com"
      - "node4.internal"
  - name: "CN=node5,OU=IT,DC=mydomain,DC=com"
    filename: "node5" <4>
--------------------------------------------------
<1> The name of the instance. This can be a simple string value or can be a
Distinguished Name (DN). This is the only required field.
<2> An optional array of strings that represent IP Addresses for this instance.
Both IPv4 and IPv6 values are allowed. The values are added as Subject
Alternative Names.
<3> An optional array of strings that represent DNS names for this instance.
The values are added as Subject Alternative Names.
<4> The filename to use for this instance. This name is used as the name of the
directory that contains the instance's files in the output. It is also used in
the names of the files within the directory. This filename should not have an
extension. Note: If the `name` provided for the instance does not represent a
valid filename, then the `filename` field must be present.

When your YAML file is ready, you can use the `certgen` command to generate
certificates or certificate signing requests. Simply use the `-in` parameter to
specify the location of the file. For example:

[source, sh]
--------------------------------------------------
bin/x-pack/certgen -in instances.yml
--------------------------------------------------

This command generates a CA certificate and private key as well as certificates
and private keys for the instances that are listed in the YAML file.
