[DOCS] Create certgen command reference (elastic/x-pack-elasticsearch#2456)
* [DOCS] Create certgen command reference * [DOCS] Added missing certgen parameters * [DOCS] Finalized certgen command reference Original commit: elastic/x-pack-elasticsearch@6d0b795eb4
This commit is contained in:
Lisa Cawley
GitHub
parent
9b25d0edf7
commit
371953488b
|
|
@ -0,0 +1,273 @@
|
|||
[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.
|
||||
|
|
@ -7,10 +7,11 @@
|
|||
|
||||
{xpack} includes commands that help you configure security:
|
||||
|
||||
//* <<certgen>>
|
||||
* <<certgen>>
|
||||
//* <<setup-passwords>>
|
||||
* <<users-command>>
|
||||
|
||||
--
|
||||
|
||||
include::certgen.asciidoc[]
|
||||
include::users-command.asciidoc[]
|
||||
|
|
|
|||
Loading…
Reference in New Issue