274 lines
12 KiB
Plaintext
274 lines
12 KiB
Plaintext
[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.
|