Skip to main content
This page isn’t applicable to ClickHouse 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.
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 for an introductory overview.
1

​
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:
View the Quick Start for more details on how to install ClickHouse.
2

​
Create TLS certificates

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:
  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:
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.
  1. Verify the contents of the new CA certificate:
  2. Create a certificate request (CSR) and generate a key for each node:
  3. Using the CSR and CA, create new certificate and key pairs:
  4. Verify the certs for subject and issuer:
  5. Check that the new certificates verify against the CA cert:
3

​
Create and Configure a directory to store certificates and keys.

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):
  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:
4

​
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.)
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
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/
When ClickHouse Keeper is embedded in ClickHouse server (as shown above), Keeper uses the server’s OpenSSL configuration defined in the OpenSSL section of Configure TLS interfaces on ClickHouse nodes. If you run ClickHouse Keeper as a standalone process, you must add an <openSSL> section to the Keeper configuration file with the same CA certificate and node certificate/key settings. See Configure OpenSSL for standalone ClickHouse Keeper below for details.
  1. Uncomment and update the keeper settings on all nodes and set the <secure> flag to 1:
  2. Update and add the following cluster settings to chnode1 and chnode2. chnode3 will be used for the ClickHouse Keeper quorum.
For this configuration, only one example cluster is configured. The test sample clusters must be either removed, commented out or if an existing cluster exists that is being tested, then the port must be updated and the <secure> option must be added. The <user and <password> must be set if the default user was initially configured to have a password in the installation or in the users.xml file.
The following creates a cluster with one shard replica on two servers (one on each node).
  1. Define macros values to be able to create a ReplicatedMergeTree table for testing. On chnode1:
    On chnode2:
5

​
Configure TLS interfaces on ClickHouse nodes

The settings below are configured in the ClickHouse server config.xml
  1. Set the display name for the deployment (optional):
  2. Set ClickHouse to listen on external ports:
  3. Configure the https port and disable the http port on each node:
  4. Configure the ClickHouse Native secure TCP port and disable the default non-secure port on each node:
  5. Configure the interserver https port and disable the default non-secure port on each node:
  6. Configure OpenSSL with certificates and paths
Each filename and path must be updated to match the node that it is being configured on. For example, update the <certificateFile> entry to be chnode2.crt when configuring in chnode2 host.
For more information, visit this page
  1. Configure TLS for gRPC on every node:
    For more information, visit https://clickhouse.com/docs/interfaces/grpc/
  2. Configure ClickHouse client on at least one of the nodes to use TLS for connections in its own config.xml file (by default in /etc/clickhouse-client/):
  3. Disable default emulation ports for MySQL and PostgreSQL:
6

​
Testing

  1. Start all nodes, one at a time:
  2. Verify secure ports are up and listening, should look similar to this example on each node:
  3. Verify ClickHouse Keeper health The typical 4 letter word (4lW) commands won’t work using echo without TLS, here is how to use the commands with openssl.
    • Start an interactive session with openssl
  • Send the 4LW commands in the OpenSSL session
  1. Start the ClickHouse client using --secure flag and TLS port:
  2. Log into the Play UI using the https interface at https://chnode1.marsnet.local:8443/play.
the browser will show an untrusted certificate since it is being reached from a workstation and the certificates aren’t in the root CA stores on the client machine. When using certificates issued from a public authority or enterprise CA, it should show trusted.
  1. Create a replicated table:
  2. Add a couple rows on chnode1:
  3. Verify the replication by viewing the rows on chnode2:

​
Configure OpenSSL for standalone ClickHouse Keeper

When running ClickHouse Keeper as a standalone process (rather than embedded within ClickHouse server), the OpenSSL certificates and settings must be configured separately in the Keeper configuration file. Without this, Keeper will not be able to establish secure connections for client communication (tcp_port_secure) or Raft replication between Keeper nodes. Add the following <openSSL> section to the standalone ClickHouse Keeper configuration file on each node:
Each filename must be updated to match the node that it is being configured on. For example, update the <certificateFile> entry to be chnode2.crt when configuring on the chnode2 host.
The <server> section is used for incoming client connections on the secure Keeper port (tcp_port_secure). The <client> section is used for outgoing connections between Keeper nodes during Raft replication.
The certificate paths above use /etc/clickhouse-keeper/certs/ which is the typical path for standalone Keeper installations. If you installed Keeper using a different path, adjust accordingly. The certificates themselves are the same ones created in step 2.

​
OpenSSL verification modes and certificate handlers

The <openSSL> configuration supports several options for <verificationMode> and <invalidCertificateHandler> that control how ClickHouse validates TLS certificates. These settings apply to clickhouse-server, clickhouse-client, and standalone ClickHouse Keeper.

​
Verification modes

Set <verificationMode> inside the <server> or <client> section of <openSSL>:

​
Invalid certificate handlers

Set <invalidCertificateHandler> inside the <server> or <client> section of <openSSL>. This handler determines what happens when certificate verification fails. On the server side, it controls the response to invalid client certificates. On the client side, it controls the response to invalid server certificates.

​
Example: disabling certificate verification

Disabling certificate verification removes TLS identity checks and exposes connections to man-in-the-middle attacks. Only use this configuration in isolated development or testing environments.
To skip certificate verification entirely (for example, when using self-signed certificates in a test environment), set verificationMode to none and use AcceptCertificateHandler. For clickhouse-client, you can also use the --accept-invalid-certificate CLI flag, which applies both settings automatically. clickhouse-client (/etc/clickhouse-client/config.xml):
clickhouse-server (config.xml or a file in config.d/). The <server> section still requires certificate and key paths because the server must present its own certificate to clients, even when it isn’t verifying theirs:
Standalone ClickHouse Keeper (Keeper configuration file):

​
Summary

This article focused on getting a ClickHouse environment configured with TLS. The settings will differ for different requirements in production environments; for example, certificate verification levels, protocols, ciphers, etc. But you should now have a good understanding of the steps involved in configuring and implementing secure connections.
Last modified on July 2, 2026