Version: Early Access

Configure secure communication with workers and satellites

This topic explains how to configure secure communication between Deploy master, workers, and satellite servers using TLS/SSL technology.

The Deploy master communicates with workers and satellite servers over a secure communication channel using TLS/SSL technology to encrypt data. This algorithm relies on certificate checking and data encryption using asymmetric keys.

TLS in a nutshell

TLS is based on the notion of public and private keys. The server contains a private key and a public certificate. In the Java world, they are stored in a keystore. The private key must be hidden and can be protected with a passphrase. This key must not be given out or communicated.

When a client tries to reach a server, it authenticates the destination. The server must prove its identity. To achieve this, the client gets a list of trusted certificates. This is the truststore. It contains public certificates that are verified by a trusted authority.

When a client tries to reach a server, there is a negotiation phase. During this phase, the client challenges the server to authenticate it. Once identified, every bit of data transferred between each side of the communication is encrypted.

With this technology, an external process that you do not manage cannot pretend to be a satellite of yours, and external processes cannot listen to the secure communication.

important

We currently support TLS version 1.2 and strongly recommend using this version to avoid any errors arising due to TLS discrepancy. For example, you may get an error such as Java.io.EOFException: SSL peer shut down incorrectly.

Configure secure communication

To configure secure communication between Deploy master, workers, and satellites:

Generate a key and certificate for the master, each worker, and each satellite server.
Add all certificates to a truststore.
Configure each component to use their own key and the truststore containing all the other certificates.

To ensure that communication is fully secure, each key should be unique.

Sample keystore and truststore creation

This example shows how to create keys and self-signed certificates using the keytool utility.

Configure the truststore with generated keys for all master, worker, and satellite components:

Generate a key for a master, worker, or satellite:

keytool -genkey -alias component_name -keyalg RSA -keypass k3yp@ss -storepass st0r3p@ss -keystore component_name.p12 -storetype pkcs12 -validity 360 -keysize 1024

Export the public certificate from the keystore file and import the certificate into the truststore:

keytool -export -keystore component_name.p12 -storepass st0r3p@ss -alias component_name | keytool -import -noprompt -alias component_name -storepass st0r3p@ss -keystore xld-truststore.p12 -storetype pkcs12

Repeat this procedure for each worker and each satellite.

Configuration example

This is an example of a configuration script for two master nodes in active/hot-standby, four workers, and three satellites.

keytool -genkey -alias master-1 -keyalg RSA -storepass st0r3p@ss -keystore master-1.p12 -storetype pkcs12 -validity 360 -keysize 1024
keytool -genkey -alias master-2 -keyalg RSA -storepass st0r3p@ss -keystore master-2.p12 -storetype pkcs12 -validity 360 -keysize 1024

keytool -genkey -alias worker-1 -keyalg RSA -storepass st0r3p@ss -keystore worker-1.p12 -storetype pkcs12 -validity 360 -keysize 1024
keytool -genkey -alias worker-2 -keyalg RSA -storepass st0r3p@ss -keystore worker-2.p12 -storetype pkcs12 -validity 360 -keysize 1024
keytool -genkey -alias worker-3 -keyalg RSA -storepass st0r3p@ss -keystore worker-3.p12 -storetype pkcs12 -validity 360 -keysize 1024
keytool -genkey -alias worker-4 -keyalg RSA -storepass st0r3p@ss -keystore worker-4.p12 -storetype pkcs12 -validity 360 -keysize 1024

keytool -genkey -alias satellite-1 -keyalg RSA -storepass st0r3p@ss -keystore satellite-1.p12 -storetype pkcs12 -validity 360 -keysize 1024
keytool -genkey -alias satellite-2 -keyalg RSA -storepass st0r3p@ss -keystore satellite-2.p12 -storetype pkcs12 -validity 360 -keysize 1024
keytool -genkey -alias satellite-3 -keyalg RSA -storepass st0r3p@ss -keystore satellite-3.p12 -storetype pkcs12 -validity 360 -keysize 1024

keytool -export -keystore master-1.p12 -storepass st0r3p@ss -alias master-1 | keytool -import -noprompt -alias master-1 -storepass st0r3p@ss -keystore xld-truststore.p12 -storetype pkcs12
keytool -export -keystore master-2.p12 -storepass st0r3p@ss -alias master-2 | keytool -import -noprompt  -alias master-2 -storepass st0r3p@ss -keystore xld-truststore.p12 -storetype pkcs12
keytool -export -keystore worker-1.p12 -storepass st0r3p@ss -alias worker-1 | keytool -import -noprompt -alias worker-1 -storepass st0r3p@ss -keystore xld-truststore.p12 -storetype pkcs12
keytool -export -keystore worker-2.p12 -storepass st0r3p@ss -alias worker-2 | keytool -import -noprompt -alias worker-2 -storepass st0r3p@ss -keystore xld-truststore.p12 -storetype pkcs12
keytool -export -keystore worker-3.p12 -storepass st0r3p@ss -alias worker-3 | keytool -import -noprompt -alias worker-3 -storepass st0r3p@ss -keystore xld-truststore.p12 -storetype pkcs12
keytool -export -keystore worker-4.p12 -storepass st0r3p@ss -alias worker-4 | keytool -import -noprompt -alias worker-4 -storepass st0r3p@ss -keystore xld-truststore.p12 -storetype pkcs12
keytool -export -keystore satellite-1.p12 -storepass st0r3p@ss -alias satellite-1 | keytool -import -noprompt -alias satellite-1 -storepass st0r3p@ss -keystore xld-truststore.p12 -storetype pkcs12
keytool -export -keystore satellite-2.p12 -storepass st0r3p@ss -alias satellite-2 | keytool -import -noprompt -alias satellite-2 -storepass st0r3p@ss -keystore xld-truststore.p12 -storetype pkcs12
keytool -export -keystore satellite-3.p12 -storepass st0r3p@ss -alias satellite-3 | keytool -import -noprompt -alias satellite-3 -storepass st0r3p@ss -keystore xld-truststore.p12 -storetype pkcs12

important

When configuring secure communication for your custom scenario, make sure you use strong and unique passwords.

Configure satellites

After you have configured the truststore on a satellite, update the deploy-satellite.yaml, deploy-server.yaml, and deploy-jmx.yaml configuration files in centralConfiguration directory to enable SSL. For more information, see Deploy Properties.

Configure Deploy

This is a sample ssl section of a XL_DEPLOY_SERVER_HOME/centralConfiguration/deploy-server.yaml file (see Deploy Properties):

deploy.server:
  ssl:
    enabled: false
    # For the worker ssl-enabled setup use this one to set up keystore settings
    key-store: "keystore"
    key-password: "changeme"
    key-store-password: "changeme"
    trust-store: "truststore"
    trust-store-password: "changeme"
    protocol: "TLSv1.2"
    enabled-algorithms: ["TLS_RSA_WITH_AES_128_CBC_SHA"]
    random-number-generator: ""

For more information, Advanced application dependencies example.

note

The HTTPS proxy server protocol only supports TLSv1.2.

Enable logging for satellites

To enable logging of secure communications on a satellite, set the SATELLITE_OPTS environment variable before starting the satellite:

export SATELLITE_OPTS="$SATELLITE_OPTS -Djavax.net.debug=all"

To enable logging on Deploy, set the DEPLOYIT_SERVER_OPTS variable:

export DEPLOYIT_SERVER_OPTS="$DEPLOYIT_SERVER_OPTS -Djavax.net.debug=all"

Configure satellite for step logs monitoring

You can use two different configurations to setup monitoring of step logs with Elastic Stack while using a satellite.

By streaming of step logs from the satellite:
To achieve streaming of step logs from the satellite, you must include the deploy.satellite.steplog.type = external parameter in centralConfiguration/deploy-satellite.yaml. The default value of deploy.satellite.steplog.type is internal. Additionally, you may setup these values to customize initialization-time and steplog queue size respectively:
```
xl.satellite.steplog.initialization-time=10 seconds
xl.satellite.steplog.queue-size=10000
```

This ensures that the step logs are immediately streamed to an Deploy worker and consequently stored in the Elastic Stack. 2. Without streaming step logs from the satellite:
You can have a different configuration than the one specified above, by choosing not to stream the step log as it is executed.

note

However, this is not recommended as in this case Deploy will store the step log in memory and send the logs to the Deploy server only when the block of steps completes. The value of of xl.satellite.steplog.type should be set to internal. As a result, unlike monitoring the step log using GUI, you will not be able to view the step log information during execution.

Troubleshooting

Worker fails to connect to the Master

The Worker fails to connect to the Master when deploy.server.ssl.enabled is set to true. To resolve this issue, configure the following command line argument for a worker startup:

 -keyPassword KEY_PASSWORD                : Password for the key (default: changeme)
 -keyStore KEY_STORE_PATH                 : Path to the key store  (default: keystore)
 -keyStorePassword KEY_STORE_PASSWORD     : Password for the key store (default: changeme)
 -trustStore TRUST_STORE_PATH             : Path to a trust store (default: truststore)
 -trustStorePassword TRUST_STORE_PASSWORD : Password for a trust store (default: changeme)

TLS in a nutshell​

Configure secure communication​

Sample keystore and truststore creation​

Configuration example​

Configure satellites​

Configure Deploy​

Enable logging for satellites​

Configure satellite for step logs monitoring​

Troubleshooting​

Worker fails to connect to the Master​