diff --git a/docs/en/installing-xes.asciidoc b/docs/en/installing-xes.asciidoc index e59f322d81d..0107c2896c3 100644 --- a/docs/en/installing-xes.asciidoc +++ b/docs/en/installing-xes.asciidoc @@ -145,7 +145,7 @@ configure SSL/TLS for internode-communication. -- NOTE: This requirement applies to clusters with more than one node and to clusters with a single node that listens on an external interface. Single-node -clusters that use a loopback interface do not have this requirement. For more +clusters that use a loopback interface do not have this requirement. For more information, see {xpack-ref}/encrypting-communications.html[Encrypting Communications]. @@ -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 <>. TIP: For easier setup, use the node name as the instance name when you run this tool. diff --git a/docs/en/security/securing-communications/setting-up-ssl.asciidoc b/docs/en/security/securing-communications/setting-up-ssl.asciidoc index 4c55ada41ca..e10cf84e15b 100644 --- a/docs/en/security/securing-communications/setting-up-ssl.asciidoc +++ b/docs/en/security/securing-communications/setting-up-ssl.asciidoc @@ -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 `:: -The path to the output file (`.zip`) that should be generated. - -`-in `:: -Input file for running in <>. - -`-csr`:: -Operate in <> mode. - -`-cert `:: -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 `:: -Provides the _private-key_ file for the CA certificate. -+ -_Required whenever the `-cert` option is used._ - -`-pass `:: -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 `:: -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 `:: -The _Distinguished Name_ that should be used for the generated CA certificate. -+ -_Not available in `-csr` mode, or with `-cert`._ - -`-keysize `:: -The number of bits to be used in generates RSA keys (default `2048`). - -`-days `:: -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 diff --git a/docs/en/security/troubleshooting.asciidoc b/docs/en/security/troubleshooting.asciidoc index e399092c9f7..8318aa6a3f2 100644 --- a/docs/en/security/troubleshooting.asciidoc +++ b/docs/en/security/troubleshooting.asciidoc @@ -7,7 +7,7 @@ Some settings are not returned via the nodes settings API:: + -- -This is intentional. Some of the settings are considered to be highly +This is intentional. Some of the settings are considered to be highly sensitive: all `ssl` settings, ldap `bind_dn`, `bind_password`). For this reason, we filter these settings and do not expose them via the nodes info API rest endpoint. You can also define additional @@ -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 <>. +In most cases, the issue can be resolved by ensuring the name is specified during certificate creation. For more information, see <>. 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 -<>. 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 <>. -- `javax.net.ssl.SSLHandshakeException: null cert chain` and `javax.net.ssl.SSLException: Received fatal alert: bad_certificate`:: @@ -224,6 +223,6 @@ when running on an Oracle JDK. In this case, you will need to install the <