diff --git a/docs/en/commands/certgen.asciidoc b/docs/en/commands/certgen.asciidoc new file mode 100644 index 00000000000..5d2fd8f2ef3 --- /dev/null +++ b/docs/en/commands/certgen.asciidoc @@ -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 ] [--days ] [--dn ] [--key ] +[--keysize ] [--pass ] [--p12 ]) +| [--csr]) +[-E ] [-h, --help] [--in ] [--out ] +([-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 <>. + +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 `:: Specifies to generate new instance certificates and keys +using an existing CA certificate, which is provided in the `` argument. +This parameter cannot be used with the `-csr` parameter. + +`--csr`:: Specifies to operation in certificate signing request mode. + +`--days `:: +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 `:: +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 `:: Configures a setting. + +`-h, --help`:: Returns all of the command parameters. + +`--in `:: Specifies the file that is used to run in silent mode. The +input file must be a YAML file, as described in <>. + +`--key `:: Specifies the _private-key_ file for the CA certificate. +This parameter is required whenever the `-cert` parameter is used. + +`--keysize `:: +Defines the number of bits that are used in generated RSA keys. The default +value is `2048`. + +`--out `:: Specifies a path for the output file. + +`--pass `:: 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 `:: +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. diff --git a/docs/en/commands/index.asciidoc b/docs/en/commands/index.asciidoc index c1a063bc13d..12792f74ec7 100644 --- a/docs/en/commands/index.asciidoc +++ b/docs/en/commands/index.asciidoc @@ -7,10 +7,11 @@ {xpack} includes commands that help you configure security: -//* <> +* <> //* <> * <> -- +include::certgen.asciidoc[] include::users-command.asciidoc[]