[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.
|
||||
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
|
||||
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
|
||||
this tool.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
[[ssl-tls]]
|
||||
=== 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
|
||||
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
|
||||
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
|
||||
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
|
||||
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.
|
||||
|
||||
[[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]]
|
||||
==== 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`.
|
||||
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
|
||||
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.
|
||||
IP addresses are only used for hostname verification if they are specified as a `SubjectAlternativeName` during
|
||||
<<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.
|
||||
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
|
||||
will need to be regenerated with the appropriate IP address. See <<ssl-tls>>.
|
||||
--
|
||||
|
||||
`javax.net.ssl.SSLHandshakeException: null cert chain` and `javax.net.ssl.SSLException: Received fatal alert: bad_certificate`::
|
||||
|
|
|
|||
Loading…
Reference in New Issue