diff --git a/README.md b/README.md index 3aa380e..7f6debf 100644 --- a/README.md +++ b/README.md @@ -370,79 +370,8 @@ These can either be set to a user declared in the file based realm, with admin p #### X-Pack Security SSL/TLS -The role allows configuring HTTP and transport layer SSL/TLS for the cluster. You will need to generate and provide your own PKCS12 or PEM encoded certificates as described in [Encrypting communications in Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/7.4/configuring-tls.html#configuring-tls). +* To configure your cluster with SSL/TLS for HTTP and/or transport communications follow the [SSL/TLS setup procedure](./docs/ssl-tls-setup.md) -The following should be configured to ensure a security-enabled cluster successfully forms: - -* `es_enable_http_ssl` Default `false`. Setting this to `true` will enable HTTP client SSL/TLS -* `es_enable_transport_ssl` - Default `false`. Setting this to `true` will enable transport layer SSL/TLS - -When using a [PKCS12](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html#security-http-pkcs12-files) keystore and truststore: - -* `es_ssl_keystore` path to your PKCS12 keystore (can be the same as `es_ssl_truststore`) -* `es_ssl_keystore_password` set this if your keystore is protected with a password -* `es_ssl_truststore` path to your PKCS12 keystore (can be the same as `es_ssl_keystore`) -* `es_ssl_truststore_password` set this if your truststore is protected with a password - -When using [PEM encoded](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html#_pem_encoded_files_3) certificates: - -* `es_ssl_key` path to your SSL key -* `es_ssl_key_password` set this if your SSL key is protected with a password -* `es_ssl_certificate` the path to your SSL certificate - -##### Generating an SSL keystore - -With a password: - -```shell -$ bin/elasticsearch-certutil ca --out ./my-ca.p12 --pass "ca_password" -$ bin/elasticsearch-certutil cert --ca ./my-ca.p12 --ca-pass "ca_password" --out ./my-keystore.p12 --pass "keystore_password" -``` - -Without a password: - -```shell -$ bin/elasticsearch-certutil ca --out ./my-ca.p12 --pass "" -$ bin/elasticsearch-certutil cert --ca ./my-ca.p12 --out ./my-keystore.p12 --pass "" -``` - -##### Additional optional SSL/TLS configuration - -* `es_ssl_certificate_path` Default `{{ es_conf_dir }}/certs`. The location where certificates should be stored on the ES node. -* `es_ssl_verification_mode` Default `certificate`. See [SSL verification_mode](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html#ssl-tls-settings) for options. -* `es_ssl_certificate_authority` PEM encoded certificate file that should be trusted. -* `es_validate_certs` Default `yes`. Determines if ansible should validate SSL certificates when performing actions over HTTPS. e.g. installing templates and managing native users. - -##### Example SSL/TLS configuration - -```yaml -- name: Elasticsearch with SSL/TLS enabled - hosts: localhost - roles: - - role: elastic.elasticsearch - vars: - es_config: - node.name: "node1" - cluster.name: "custom-cluster" - discovery.seed_hosts: "localhost:9301" - http.port: 9201 - transport.port: 9301 - node.data: false - node.master: true - bootstrap.memory_lock: true - xpack.security.authc.realms.file.file1.order: 0 - xpack.security.authc.realms.native.native1.order: 1 - es_heap_size: 1g - es_api_basic_auth_username: elastic - es_api_basic_auth_password: changeme - es_enable_http_ssl: true - es_enable_transport_ssl: true - es_ssl_keystore: "files/certs/my-keystore.p12" - es_ssl_truststore: "files/certs/my-truststore.p12" - es_ssl_keystore_password: "keystore_password" - es_ssl_truststore_password: "truststore_password" - es_validate_certs: no -``` ### Additional Configuration diff --git a/docs/ssl-tls-setup.md b/docs/ssl-tls-setup.md new file mode 100644 index 0000000..3e24a0c --- /dev/null +++ b/docs/ssl-tls-setup.md @@ -0,0 +1,75 @@ +# X-Pack Security SSL/TLS + +The role allows configuring HTTP and transport layer SSL/TLS for the cluster. You will need to generate and provide your own PKCS12 or PEM encoded certificates as described in [Encrypting communications in Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/7.4/configuring-tls.html#configuring-tls). + +The following should be configured to ensure a security-enabled cluster successfully forms: + +* `es_enable_http_ssl` Default `false`. Setting this to `true` will enable HTTP client SSL/TLS +* `es_enable_transport_ssl` - Default `false`. Setting this to `true` will enable transport layer SSL/TLS + +When using a [PKCS12](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html#security-http-pkcs12-files) keystore and truststore: + +* `es_ssl_keystore` path to your PKCS12 keystore (can be the same as `es_ssl_truststore`) +* `es_ssl_keystore_password` set this if your keystore is protected with a password +* `es_ssl_truststore` path to your PKCS12 keystore (can be the same as `es_ssl_keystore`) +* `es_ssl_truststore_password` set this if your truststore is protected with a password + +When using [PEM encoded](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html#_pem_encoded_files_3) certificates: + +* `es_ssl_key` path to your SSL key +* `es_ssl_key_password` set this if your SSL key is protected with a password +* `es_ssl_certificate` the path to your SSL certificate + +## Generating an SSL keystore + +With a password: + +```shell +$ bin/elasticsearch-certutil ca --out ./my-ca.p12 --pass "ca_password" +$ bin/elasticsearch-certutil cert --ca ./my-ca.p12 --ca-pass "ca_password" --out ./my-keystore.p12 --pass "keystore_password" +``` + +Without a password: + +```shell +$ bin/elasticsearch-certutil ca --out ./my-ca.p12 --pass "" +$ bin/elasticsearch-certutil cert --ca ./my-ca.p12 --out ./my-keystore.p12 --pass "" +``` + +## Additional optional SSL/TLS configuration + +* `es_ssl_certificate_path` Default `{{ es_conf_dir }}/certs`. The location where certificates should be stored on the ES node. +* `es_ssl_verification_mode` Default `certificate`. See [SSL verification_mode](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html#ssl-tls-settings) for options. +* `es_ssl_certificate_authority` PEM encoded certificate file that should be trusted. +* `es_validate_certs` Default `yes`. Determines if ansible should validate SSL certificates when performing actions over HTTPS. e.g. installing templates and managing native users. + +## Example SSL/TLS configuration + +```yaml +- name: Elasticsearch with SSL/TLS enabled + hosts: localhost + roles: + - role: elastic.elasticsearch + vars: + es_config: + node.name: "node1" + cluster.name: "custom-cluster" + discovery.seed_hosts: "localhost:9301" + http.port: 9201 + transport.port: 9301 + node.data: false + node.master: true + bootstrap.memory_lock: true + xpack.security.authc.realms.file.file1.order: 0 + xpack.security.authc.realms.native.native1.order: 1 + es_heap_size: 1g + es_api_basic_auth_username: elastic + es_api_basic_auth_password: changeme + es_enable_http_ssl: true + es_enable_transport_ssl: true + es_ssl_keystore: "files/certs/my-keystore.p12" + es_ssl_truststore: "files/certs/my-truststore.p12" + es_ssl_keystore_password: "keystore_password" + es_ssl_truststore_password: "truststore_password" + es_validate_certs: no +```