Configuring TLS

[Edit this page](https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/guides/sre/tls/configuring-tls.md)

Not supported in ClickHouse Cloud

Note

This page isn't applicable to [ClickHouse Cloud](https://clickhouse.com/cloud). The procedure documented here is automated in ClickHouse Cloud services.

This guide provides simple and minimal settings to configure ClickHouse to use OpenSSL certificates to validate connections. For this demonstration, a self-signed Certificate Authority (CA) certificate and key are created with node certificates to make the connections with appropriate settings.

Note

TLS implementation is complex and there are many options to consider to ensure a fully secure and robust deployment. This is a basic tutorial with basic TLS configuration examples. Consult with your PKI/security team to generate the correct certificates for your organization.

Review this [basic tutorial on certificate usage](https://ubuntu.com/server/docs/security-certificates) for an introductory overview.

Create a ClickHouse Deployment

## Create a ClickHouse Deployment[​](#1-create-a-clickhouse-deployment "Direct link to Create a ClickHouse Deployment")

This guide was written using Ubuntu 20.04 and ClickHouse installed on the following hosts using the DEB package (using apt). The domain is `marsnet.local`:

|  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- |
| Host IP Address|  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | | `chnode1` 192.168.1.221|  |  |  |  | | --- | --- | --- | --- | | `chnode2` 192.168.1.222|  |  | | --- | --- | | `chnode3` 192.168.1.223 | | | | | | | |

Note

View the [Quick Start](/docs/install) for more details on how to install ClickHouse.

Create TLS certificates

## Create TLS certificates[​](#2-create-tls-certificates "Direct link to Create TLS certificates")

Note

Using self-signed certificates are for demonstration purposes only and shouldn't used in production. Certificate requests should be created to be signed by the organization and validated using the CA chain that will be configured in the settings. However, these steps can be used to configure and test settings, then can be replaced by the actual certificates that will be used.

1. Generate a key that will be used for the new CA:

   ```
   openssl genrsa -out marsnet_ca.key 2048
   ```
2. Generate a new self-signed CA certificate. The following will create a new certificate that will be used to sign other certificates using the CA key:

   ```
   openssl req -x509 -subj "/CN=marsnet.local CA" -nodes -key marsnet_ca.key -days 1095 -out marsnet_ca.crt
   ```

   Note

   Backup the key and CA certificate in a secure location not in the cluster. After generating the node certificates, the key should be deleted from the cluster nodes.
3. Verify the contents of the new CA certificate:

   ```
   openssl x509 -in marsnet_ca.crt -text
   ```
4. Create a certificate request (CSR) and generate a key for each node:

   ```
   openssl req -newkey rsa:2048 -nodes -subj "/CN=chnode1" -addext "subjectAltName = DNS:chnode1.marsnet.local,IP:192.168.1.221" -keyout chnode1.key -out chnode1.csr
   openssl req -newkey rsa:2048 -nodes -subj "/CN=chnode2" -addext "subjectAltName = DNS:chnode2.marsnet.local,IP:192.168.1.222" -keyout chnode2.key -out chnode2.csr
   openssl req -newkey rsa:2048 -nodes -subj "/CN=chnode3" -addext "subjectAltName = DNS:chnode3.marsnet.local,IP:192.168.1.223" -keyout chnode3.key -out chnode3.csr
   ```
5. Using the CSR and CA, create new certificate and key pairs:

   ```
   openssl x509 -req -in chnode1.csr -out chnode1.crt -CA marsnet_ca.crt -CAkey marsnet_ca.key -days 365 -copy_extensions copy
   openssl x509 -req -in chnode2.csr -out chnode2.crt -CA marsnet_ca.crt -CAkey marsnet_ca.key -days 365 -copy_extensions copy
   openssl x509 -req -in chnode3.csr -out chnode3.crt -CA marsnet_ca.crt -CAkey marsnet_ca.key -days 365 -copy_extensions copy
   ```
6. Verify the certs for subject and issuer:

   ```
   openssl x509 -in chnode1.crt -text -noout
   ```
7. Check that the new certificates verify against the CA cert:

   ```
   openssl verify -CAfile marsnet_ca.crt chnode1.crt
   chnode1.crt: OK
   ```

Create and Configure a directory to store certificates and keys.

## Create and Configure a directory to store certificates and keys.[​](#3-create-and-configure-a-directory-to-store-certificates-and-keys "Direct link to Create and Configure a directory to store certificates and keys.")

Note

This must be done on each node. Use appropriate certificates and keys on each host.

1. Create a folder in a directory accessible by ClickHouse in each node. We recommend the default configuration directory (e.g. `/etc/clickhouse-server`):

   ```
   mkdir /etc/clickhouse-server/certs
   ```
2. Copy the CA certificate, node certificate and key corresponding to each node to the new certs directory.
3. Update owner and permissions to allow ClickHouse to read the certificates:

   ```
   chown clickhouse:clickhouse -R /etc/clickhouse-server/certs
   chmod 600 /etc/clickhouse-server/certs/*
   chmod 755 /etc/clickhouse-server/certs
   ll /etc/clickhouse-server/certs
   ```

   ```
   total 20
   drw-r--r-- 2 clickhouse clickhouse 4096 Apr 12 20:23 ./
   drwx------ 5 clickhouse clickhouse 4096 Apr 12 20:23 ../
   -rw------- 1 clickhouse clickhouse  997 Apr 12 20:22 chnode1.crt
   -rw------- 1 clickhouse clickhouse 1708 Apr 12 20:22 chnode1.key
   -rw------- 1 clickhouse clickhouse 1131 Apr 12 20:23 marsnet_ca.crt
   ```

Configure the environment with basic clusters using ClickHouse Keeper

## Configure the environment with basic clusters using ClickHouse Keeper[​](#4-configure-the-environment-with-basic-clusters-using-clickhouse-keeper "Direct link to Configure the environment with basic clusters using ClickHouse Keeper")

For this deployment environment, the following ClickHouse Keeper settings are used in each node. Each server will have its own `<server_id>`. (For example, `<server_id>1</server_id>` for node `chnode1`, and so on.)

Note

Recommended port is `9281` for ClickHouse Keeper. However, the port is configurable and can be set if this port is in use already by another application in the environment.

For a full explanation of all options, visit <https://clickhouse.com/docs/operations/clickhouse-keeper/>

1. Add the following inside the `<clickhouse>` tag in ClickHouse server `config.xml`

   Note

   For production environments, it is recommended to use a separate `.xml` config file in the `config.d` directory.
   For more information, visit <https://clickhouse.com/docs/operations/configuration-files/>

   ```
   <keeper_server>
       <tcp_port_secure>9281</tcp_port_secure>
       <server_id>1</server_id>
       <log_storage_path>/var/lib/clickhouse/coordination/log</log_storage_path>
       <snapshot_storage_path>/var/lib/clickhouse/coordination/snapshots</snapshot_storage_path>

       <coordination_settings>
           <operation_timeout_ms>10000</operation_timeout_ms>
           <session_timeout_ms>30000</session_timeout_ms>
           <raft_logs_level>trace</raft_logs_level>
       </coordination_settings>

       <raft_configuration>
           <secure>true</secure>
           <server>
               <id>1</id>
               <hostname>chnode1.marsnet.local</hostname>
               <port>9444</port>
           </server>
           <server>
               <id>2</id>
               <hostname>chnode2.marsnet.local</hostname>
               <port>9444</port>
           </server>
           <server>
               <id>3</id>
               <hostname>chnode3.marsnet.local</hostname>
               <port>9444</port>
           </server>
       </raft_configuration>
   </keeper_server>
   ```

   Note