[DOCS] Remove redundant certgen info (elastic/x-pack-elasticsearch#2542)
Original commit: elastic/x-pack-elasticsearch@6147e32fd1
This commit is contained in:
Lisa Cawley
GitHub
parent
679ef6a744
commit
4ffaec5173
|
|
@ -163,7 +163,7 @@ This command generates a zip file with the CA certificate, private key, and
|
||||||
signed certificates and keys in the PEM format for each node that you specify.
|
signed certificates and keys in the PEM format for each node that you specify.
|
||||||
If you want to use a commercial or organization-specific CA, you can use the
|
If you want to use a commercial or organization-specific CA, you can use the
|
||||||
`-csr` parameter to generate certificate signing requests (CSR) for the nodes
|
`-csr` parameter to generate certificate signing requests (CSR) for the nodes
|
||||||
in your cluster.
|
in your cluster. For more information, see <<certgen>>.
|
||||||
|
|
||||||
TIP: For easier setup, use the node name as the instance name when you run
|
TIP: For easier setup, use the node name as the instance name when you run
|
||||||
this tool.
|
this tool.
|
||||||
|
|
|
||||||
|
|
@ -1,7 +1,7 @@
|
||||||
[[ssl-tls]]
|
[[ssl-tls]]
|
||||||
=== Setting Up SSL/TLS on a Cluster
|
=== Setting Up SSL/TLS on a Cluster
|
||||||
|
|
||||||
{security} enables you to encrypt traffic to, from and within your Elasticsearch
|
{security} enables you to encrypt traffic to, from, and within your Elasticsearch
|
||||||
cluster. Connections are secured using Transport Layer Security (TLS), which is
|
cluster. Connections are secured using Transport Layer Security (TLS), which is
|
||||||
commonly referred to as "SSL".
|
commonly referred to as "SSL".
|
||||||
|
|
||||||
|
|
@ -37,228 +37,13 @@ line tool, `certgen` has been included with {xpack}. This tool takes care of the
|
||||||
a CA and signing certificates with the CA. `certgen` can be used interactively or in a silent
|
a CA and signing certificates with the CA. `certgen` can be used interactively or in a silent
|
||||||
mode through the use of an input file. The `certgen` tool also supports generation of certificate
|
mode through the use of an input file. The `certgen` tool also supports generation of certificate
|
||||||
signing requests (CSR), so that a commercial or organization specific CA may be used to sign
|
signing requests (CSR), so that a commercial or organization specific CA may be used to sign
|
||||||
the certificates.
|
the certificates. For more information, see {ref}/certgen.html[certgen].
|
||||||
|
|
||||||
NOTE: If you choose not to use the `certgen`, the certificates that you obtain must allow for both
|
NOTE: If you choose not to use `certgen`, the certificates that you obtain must allow for both
|
||||||
`clientAuth` and `serverAuth` if the extended key usage extension is present. The certificates
|
`clientAuth` and `serverAuth` if the extended key usage extension is present. The certificates
|
||||||
need to be in PEM format. Although not required, it is highly recommended that the certificate contain
|
need to be in PEM format. Although not required, it is highly recommended that the certificate contain
|
||||||
the dns name(s) and/or ip address(es) of the node so that hostname verification may be used.
|
the dns name(s) and/or ip address(es) of the node so that hostname verification may be used.
|
||||||
|
|
||||||
[[generating-signed-certificates]]
|
|
||||||
===== Generating Certificates with `certgen`
|
|
||||||
|
|
||||||
The `certgen` tool can be used to generate a CA and signed certificates for your nodes. The tool
|
|
||||||
can be used interactively:
|
|
||||||
|
|
||||||
[listing]
|
|
||||||
....
|
|
||||||
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.
|
|
||||||
....
|
|
||||||
|
|
||||||
The usage of `certgen` above generates a zip file with the CA certificate, private key, two signed certificates and keys
|
|
||||||
in PEM format for `node01` and `node02`.
|
|
||||||
|
|
||||||
[[generating-csr]]
|
|
||||||
===== Generating Certificate Signing Requests with `certgen`
|
|
||||||
|
|
||||||
When using a commercial or organization specific CA, the `certgen` tool may be used to generate
|
|
||||||
certificate signing requests (CSR) for the nodes in your cluster:
|
|
||||||
|
|
||||||
[listing]
|
|
||||||
....
|
|
||||||
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.
|
|
||||||
....
|
|
||||||
|
|
||||||
The usage of `certgen` above 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.
|
|
||||||
|
|
||||||
[[certgen-silent]]
|
|
||||||
===== Using `certgen` in Silent Mode
|
|
||||||
|
|
||||||
`certgen` supports a silent mode of operation to enable easier batch operations. In order
|
|
||||||
to use this mode, a YAML file containing the information about the instances needs to be
|
|
||||||
created matching the format shown below:
|
|
||||||
|
|
||||||
[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 will
|
|
||||||
be added as Subject Alternative Names.
|
|
||||||
<3> An optional array of strings that represent DNS names for this instance. The values will be added as Subject Alternative Names.
|
|
||||||
<4> The filename to use for this instance. This name will be the name of the directory in the zip file that this instance's files will
|
|
||||||
stored in and it will used be used in the naming 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.
|
|
||||||
|
|
||||||
With the YAML file ready, the `certgen` tool can be used to generate certificates or certificate signing requests. Simply pass the file's
|
|
||||||
path to `certgen` using the `-in` option. For example:
|
|
||||||
|
|
||||||
[source, sh]
|
|
||||||
--------------------------------------------------
|
|
||||||
bin/x-pack/certgen -in instances.yml <1>
|
|
||||||
--------------------------------------------------
|
|
||||||
<1> Generates a CA certificate and private key in addition to certificates and private keys for the instances
|
|
||||||
contained in the YAML file. The other options to the tool can be specified in addition to the `-in` option. For all of the available
|
|
||||||
options, run `bin/x-pack/certgen -h`.
|
|
||||||
|
|
||||||
[[certgen-options]]
|
|
||||||
===== Command Line Options for `certgen`
|
|
||||||
|
|
||||||
`-out <file>`::
|
|
||||||
The path to the output file (`.zip`) that should be generated.
|
|
||||||
|
|
||||||
`-in <file>`::
|
|
||||||
Input file for running in <<certgen-silent, silent mode>>.
|
|
||||||
|
|
||||||
`-csr`::
|
|
||||||
Operate in <<generating-csr, Certificate Signing Request>> mode.
|
|
||||||
|
|
||||||
`-cert <file>`::
|
|
||||||
This option causes `certgen` to generate new instances certificates and keys
|
|
||||||
using an existing CA certificate (provided in the `file` argument).
|
|
||||||
+
|
|
||||||
_Not available in `-csr` mode._
|
|
||||||
|
|
||||||
`-key <file>`::
|
|
||||||
Provides the _private-key_ file for the CA certificate.
|
|
||||||
+
|
|
||||||
_Required whenever the `-cert` option is used._
|
|
||||||
|
|
||||||
`-pass <password>`::
|
|
||||||
Specifies the password for the CA private key.
|
|
||||||
If the `-key` option 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.
|
|
||||||
+
|
|
||||||
_Not available in `-csr` mode._
|
|
||||||
|
|
||||||
`-p12 <password>`::
|
|
||||||
Generate a PKCS#12 (`.p12` or `.pfx`) container file for each of the instance
|
|
||||||
certificates and keys.
|
|
||||||
The generate file is protected by the supplied password (which may be blank).
|
|
||||||
+
|
|
||||||
_Not available in `-csr` mode._
|
|
||||||
|
|
||||||
`-dn <name>`::
|
|
||||||
The _Distinguished Name_ that should be used for the generated CA certificate.
|
|
||||||
+
|
|
||||||
_Not available in `-csr` mode, or with `-cert`._
|
|
||||||
|
|
||||||
`-keysize <bits>`::
|
|
||||||
The number of bits to be used in generates RSA keys (default `2048`).
|
|
||||||
|
|
||||||
`-days <n>`::
|
|
||||||
The number of days for which generated keys should be valid (default `1095`).
|
|
||||||
+
|
|
||||||
_Not available in `-csr` mode._
|
|
||||||
|
|
||||||
[[enable-ssl]]
|
[[enable-ssl]]
|
||||||
==== Enabling SSL in the Node Configuration
|
==== Enabling SSL in the Node Configuration
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -136,7 +136,7 @@ common exceptions are shown below with tips on how to resolve these issues.
|
||||||
+
|
+
|
||||||
--
|
--
|
||||||
Indicates that a client connection was made to `node01.example.com` but the certificate returned did not contain the name `node01.example.com`.
|
Indicates that a client connection was made to `node01.example.com` but the certificate returned did not contain the name `node01.example.com`.
|
||||||
In most cases, the issue can be resolved by ensuring the name is specified during <<generating-signed-certificates, certificate creation>>.
|
In most cases, the issue can be resolved by ensuring the name is specified during certificate creation. For more information, see <<ssl-tls>>.
|
||||||
Another scenario is when the environment does not wish to use DNS names in certificates at all. In this scenario, all settings
|
Another scenario is when the environment does not wish to use DNS names in certificates at all. In this scenario, all settings
|
||||||
in `elasticsearch.yml` should only use IP addresses including the `network.publish_host` setting.
|
in `elasticsearch.yml` should only use IP addresses including the `network.publish_host` setting.
|
||||||
--
|
--
|
||||||
|
|
@ -145,9 +145,8 @@ in `elasticsearch.yml` should only use IP addresses including the `network.publi
|
||||||
+
|
+
|
||||||
--
|
--
|
||||||
Indicates that a client connection was made to an IP address but the returned certificate did not contain any `SubjectAlternativeName` entries.
|
Indicates that a client connection was made to an IP address but the returned certificate did not contain any `SubjectAlternativeName` entries.
|
||||||
IP addresses are only used for hostname verification if they are specified as a `SubjectAlternativeName` during
|
IP addresses are only used for hostname verification if they are specified as a `SubjectAlternativeName` during certificate creation. If the intent was to use IP addresses for hostname verification, then the certificate
|
||||||
<<generating-signed-certificates, certificate creation>>. If the intent was to use IP addresses for hostname verification, then the certificate
|
will need to be regenerated with the appropriate IP address. See <<ssl-tls>>.
|
||||||
will need to be regenerated with the appropriate IP address.
|
|
||||||
--
|
--
|
||||||
|
|
||||||
`javax.net.ssl.SSLHandshakeException: null cert chain` and `javax.net.ssl.SSLException: Received fatal alert: bad_certificate`::
|
`javax.net.ssl.SSLHandshakeException: null cert chain` and `javax.net.ssl.SSLException: Received fatal alert: bad_certificate`::
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue