Version: 5.3

Configuration clickhouse-server

ClickHouse Configuration Structure

Main Directories and Files

Recommended structure (using the standard ClickHouse package layout):

Element	Default Path	Purpose
Main server configuration file	`/etc/clickhouse-server/config.xml`	Basic settings, includes `config.d`
Additional server configuration file	`/etc/clickhouse-server/config.d/*.xml`	Overrides and additions to `config.xml`
User configuration file	`/etc/clickhouse-server/users.xml`	Base users, profiles, quotas
Additional user configuration file	`/etc/clickhouse-server/users.d/*.xml`	Additional users, profiles, quotas
ClickHouse Keeper configuration file	`/etc/clickhouse-keeper/keeper_config.xml`	Keeper process configuration
Additional Keeper configuration file (optional)	`/etc/clickhouse-keeper/keeper_config.d/*.xml`	Extends Keeper configuration

Key principle: Do not modify the base config.xml; instead, add your settings in separate files inside config.d/. The same applies to users.xml and users.d/.

Single-node `clickhouse-server` Configuration

This section describes the minimally required configuration for a single node, which serves as the foundation for building a cluster.

Network Ports and `listen_host`

File: /etc/clickhouse-server/config.d/network.xml (if SSL is not configured separately)

<clickhouse>
  <!-- HTTP interface (ClickHouse HTTP API) -->
  <http_port>8123</http_port>

  <!-- Native TCP port for clickhouse-client and drivers -->
  <tcp_port>9000</tcp_port>

  <!-- Inter-server HTTP port (replication, Distributed) -->
  <interserver_http_port>9009</interserver_http_port>

  <!-- Allow connections from all interfaces. 
       For production environments, it is recommended to restrict the list of addresses/networks. -->
  <listen_host>0.0.0.0</listen_host>
</clickhouse>

TLS configuration strategies:

keep unencrypted ports only within the internal network
fully transition to secure ports and remove http_port/tcp_port

Users and Profiles

The base user default is created automatically. For application access, it is recommended to create a separate user in users.d.

File: /etc/clickhouse-server/users.d/app_user.xml

<clickhouse>
  <users>
    <app_user>
      <!-- It is recommended to use SHA-256 hash instead of a plain password -->
      <!-- Example: password_sha256_hex>...</password_sha256_hex> -->
      <password>StrongAppUserPass</password>

      <!-- Profile (a default set of settings) -->
      <profile>default</profile>

      <!-- Network restrictions (example – access from any network) -->
      <networks>
        <ip>::/0</ip>
      </networks>

      <!-- Quota (optional, can be left as default) -->
      <quota>default</quota>
    </app_user>
  </users>
</clickhouse>

Detailed TLS/SSL Configuration

A separate configuration file, ssl.xml, is used to enable encryption for both client and inter-server connections.

File: /etc/clickhouse-server/config.d/ssl.xml

<clickhouse>
    <!-- Secure ports -->
    <tcp_port_secure>9440</tcp_port_secure>
    <!-- <http_port>8123</http_port> -->
    <https_port>8443</https_port>              <!-- HTTPS API -->
    <interserver_https_port>9010</interserver_https_port>
    <interserver_https_host>hostname-1</interserver_https_host>

    <!-- Disable insecure ports (if full restriction is needed) -->
    <http_port remove="1"/>
    <tcp_port remove="1"/>
    <interserver_http_port remove="1"/>

    <!-- Enable access from all IPs if external connections are needed -->
    <listen_host>::</listen_host>

    <!-- TLS/SSL settings -->
    <openSSL>
        <server>
            <!-- Server certificate -->
            <certificateFile>/etc/clickhouse-server/ssl/clickhouse-node-1.crt</certificateFile>

            <!-- Server private key -->
            <privateKeyFile>/etc/clickhouse-server/ssl/clickhouse-node-1.key</privateKeyFile>

            <!-- CA that signed the server certificate -->
            <caConfig>/etc/clickhouse-server/ssl/ca-cert.pem</caConfig>

            <!-- strict: client must have a trusted CA,
            relaxed - a "soft" mode for TLS certificate validation that does not require a client certificate,
            none: no client validation required -->
            <verificationMode>relaxed</verificationMode>

            <!-- Use TLS session cache (improves performance) -->
            <cacheSessions>true</cacheSessions>

            <!-- Support TLS 1.2 and above -->
            <disableProtocols>SSLv2,SSLv3,TLSv1,TLSv1.1</disableProtocols>
        </server>

        <client>
            <!-- Use the same CA for server validation if ClickHouse acts as a client -->
            <caConfig>/etc/clickhouse-server/ssl/ca-cert.pem</caConfig>

            <!-- Do not load system CAs -->
            <loadDefaultCAFile>false</loadDefaultCAFile>

            <!-- strict — verification required; none — no validation needed -->
            <verificationMode>none</verificationMode>
        </client>
    </openSSL>

    <!-- Inter-server communication settings -->
    <interserver_scheme>https</interserver_scheme>
</clickhouse>

Ports and interserver HTTPS Scheme

To make ports available to external clients, use the following commands:

for Debian-based systems using ufw:

sudo ufw allow 9000/tcp  # Open port for ClickHouse TCP connections
sudo ufw allow 8123/tcp  # Open port for ClickHouse HTTP interface
sudo ufw reload          # Apply changes

for RHEL-based systems using firewalld:

sudo firewall-cmd --zone=public --add-port=9000/tcp --permanent  # Open port for ClickHouse TCP connections
sudo firewall-cmd --zone=public --add-port=8123/tcp --permanent  # Open port for ClickHouse HTTP interface
sudo firewall-cmd --reload  # Apply changes

Full list of ports used by ClickHouse:

Port	Description
8123	Standard HTTP port.
8443	Standard HTTP SSL/TLS port.
9000	Native protocol port (also known as ClickHouse TCP protocol). Used by applications and ClickHouse processes such as `clickhouse-server`, `clickhouse-client` and native ClickHouse tools. Used for inter-server communication in distributed queries.
9004	MySQL emulation port.
9005	PostgreSQL emulation port (also used for secure connections if SSL is enabled for ClickHouse).
9009	Inter-server communication port for low-level data access. Used for data exchange, replication, and inter-server communication.
9010	SSL/TLS port for inter-server communication.
9011	Native PROXYv1 protocol port.
9019	JDBC bridge port.
9100	gRPC port.
9181	Recommended ClickHouse Keeper port.
9234	Recommended ClickHouse Keeper Raft port (also used for secure communication if `<secure>1</secure>` is enabled).
9363	Standard port for Prometheus metrics.
9281	Recommended secure SSL port for ClickHouse Keeper.
9440	SSL/TLS port for the native protocol.
42000	Standard port for Graphite.

<tcp_port_secure>9440</tcp_port_secure> — Secure TCP port for the ClickHouse native protocol (analogous to tcp_port, but over TLS). clickhouse-client with the --secure flag and drivers using TLS connect to this port
<https_port>8443</https_port> — HTTPS variant of the HTTP API. All REST requests and external integrations using HTTPS should use this port
<interserver_https_port>9010</interserver_https_port> — Port for inter-server HTTPS (replication, internal HTTP protocol between nodes). This is the TLS counterpart of interserver_http_port
<interserver_https_host>hostname-1</interserver_https_host> — The hostname by which other nodes access this server. It must:
- resolve correctly to this server's IP address
- be included in the SubjectAltName (SAN) field of the server certificate clickhouse-node-1.crt (it is recommended that the CN match/be consistent)
blocks with remove="1" disable unencrypted ports:
- <http_port remove="1"/> — Disables HTTP on port 8123
- <tcp_port remove="1"/> — Disables unencrypted TCP (usually 9000)
- <interserver_http_port remove="1"/> — Disables unencrypted inter-server HTTP (usually 9009)
As a result, the server only accepts TLS connections — both from clients and from other cluster nodes.
<listen_host>::</listen_host> — Listens on all network interfaces (IPv6 any + IPv4). Be sure to restrict network access to ClickHouse using firewall/ACL. The server should only be accessible from trusted networks
<interserver_scheme>https</interserver_scheme> — Instructs ClickHouse to use the HTTPS scheme for inter-server requests and replication, ensuring consistent operation with the port specified in interserver_https_port

Server SSL Settings

The <server> section describes which certificates and parameters are used when ClickHouse acts as a TLS server (accepting connections):

<certificateFile> — Path to the server's X.509 certificate in PEM format:
- contains the public key
- signed by an internal CA (ca-cert.pem)
- must contain correct SANs (DNS names) and/or a CN for the host
<privateKeyFile> — Path to the server's private key:
- unique for each node
- must not be copied to other machines
- file permissions should restrict read access to only the user running clickhouse-server
<caConfig> — Certificate (or certificate chain) of the Certificate Authority (CA) that signed the server certificate:
- used to verify client certificates when verificationMode=relaxed
- can be used for client connections (if the same CA is specified in <client>)
<verificationMode>relaxed</verificationMode> — The server does not verify the client's certificate. This means:
- the connection is encrypted
- however, TLS is not used for client authentication (the client is identified solely by login/password, user settings, and networks)
<cacheSessions>true</cacheSessions> — Enables TLS session caching, which reduces overhead when establishing a large number of short-lived connections
<disableProtocols>SSLv2,SSLv3,TLSv1,TLSv1.1</disableProtocols> — Disables outdated and insecure protocols, leaving only TLSv1.2+

TLS Verification Modes in ClickHouse (verificationMode)

Supported modes:

none — Certificates are not verified. The connection is encrypted, but self-signed, expired, or name-mismatched certificates are allowed
relaxed — Certificate verification is performed, but a client certificate is not mandatory. If a party provides a certificate, it is verified against the CA and validity period; if no certificate is provided, the connection is allowed
strict — Strict verification. A valid certificate is mandatory (for the party that must present it). In the context of mTLS: the client must provide a valid certificate, otherwise the connection will not be established

Client SSL Settings

The <client> section describes parameters that ClickHouse uses when it initiates outgoing TLS connections (for example, to other cluster nodes via secure ports or to external HTTPS resources):

<caConfig>/etc/clickhouse-server/ssl/ca-cert.pem</caConfig> — The same CA that signed the certificates of all cluster nodes. This allows ClickHouse to:
- verify the authenticity of other nodes' certificates
- ensure the connection is established with the trusted server
<loadDefaultCAFile>false</loadDefaultCAFile> — Prevents the use of the system's trusted CA bundle. This enhances security by trusting only internal certificates
<verificationMode>none</verificationMode> — ClickHouse does not verify the validity of remote server certificates. Again: encryption is present, but the remote server's authenticity is not confirmed. It is recommended to switch to relaxed and verify CN/SAN compliance in all certificates

Set of Certificates and Keys on Each Node

For this configuration to work correctly, the following must be present on each cluster node:

CA Certificate (/etc/clickhouse-server/ssl/ca-cert.pem):

the same for all nodes
the public part of an internal Certificate Authority
used for both verifying server certificates and (optionally) client certificates

Node Certificate (clickhouse-node-1.crt, clickhouse-node-2.crt, etc.):

unique for each server
signed by the aforementioned CA

Node Private Key (clickhouse-node-1.key, clickhouse-node-2.key, etc.):

unique for each server
must not be copied to other servers
must not be stored in version control systems

A typical generation scenario:

a private CA key is created
a self-signed CA certificate (ca-cert.pem) is generated
for each node:
- a unique node private key is created
- a Certificate Signing Request (CSR) is generated, specifying CN and SAN
- the CSR is signed with the CA's private key, resulting in the node certificate

Transitioning to Cluster Mode

Connecting `clickhouse-server` to Keeper

On each ClickHouse server, the connection to Keeper must be described in the <zookeeper> section. The file can be named, for example, /etc/clickhouse-server/config.d/keeper.xml.

File: /etc/clickhouse-server/config.d/keeper.xml

<clickhouse>
  <zookeeper>
    <!-- In a dev environment, connect to a single Keeper node -->
    <node>
      <host>hostname-1</host>
      <port>9181</port> <!-- Keeper client port -->
    </node>

    <session_timeout_ms>30000</session_timeout_ms>
    <operation_timeout_ms>10000</operation_timeout_ms>
  </zookeeper>
</clickhouse>

When adding new Keeper nodes, additional <node> blocks are added:

<zookeeper>
  <node>
    <host>keeper1.local</host>
    <port>9181</port>
  </node>
  <node>
    <host>keeper2.local</host>
    <port>9181</port>
  </node>
  <node>
    <host>keeper3.local</host>
    <port>9181</port>
  </node>
</zookeeper>

Cluster Configuration

A basic remote_servers configuration for a cluster with one shard and two replicas.

File: /etc/clickhouse-server/config.d/cluster.xml

<clickhouse>
  <remote_servers>
    <cluster_name>
      <!-- The secret must be identical on all cluster nodes -->
      <secret>cluster_name_shared_secret</secret>

      <shard>
        <replica>
          <host>hostname-1</host>
          <port>9440</port>
          <secure>1</secure>
        </replica>
        <replica>
          <host>hostname-2</host>
          <port>9440</port>
          <secure>1</secure>
        </replica>
      </shard>
    </cluster_name>
  </remote_servers>
</clickhouse>

subqueries to shards are executed on behalf of the same user who initiated the original query on the entry node
query legitimacy is confirmed using a shared cryptographic secret, not user passwords
there is no need to store user passwords in the cluster.xml configuration file

Cluster Macros (`macros.xml`)

Macros allow the use of {cluster}, {shard}, and {replica} in table definitions and queries. The settings should differ between nodes only in the value of replica.

Configuration Example

File: /etc/clickhouse-server/config.d/macros.xml

<clickhouse>
  <macros>
    <cluster>cluster_name</cluster>
    <shard>1</shard>
    <replica>hostname-1</replica>
  </macros>
</clickhouse>

Inter-Server Credentials

To ensure secure data exchange between replicas (Replicated*), it is recommended to configure interserver_http_credentials. The configuration must be identical on all cluster nodes.

File: /etc/clickhouse-server/config.d/interserver.xml

<clickhouse>
  <interserver_http_credentials>
    <user>interserver</user>
    <password>InterServerStrongPass</password>
    <!-- It is recommended to disable empty passwords -->
    <allow_empty>false</allow_empty>
  </interserver_http_credentials>
</clickhouse>

The credentials are used for authentication in the following scenarios:

inter-server replication — Securing HTTP connections between replicas
internal operations — Authenticating service HTTP requests between cluster nodes

Advantages of the rights separation scheme:

regular users (default, app_user) do not require and are not granted rights to perform system replication operations
the interserver password is not for client connections and must not be present in client configurations

Verifying Cluster Functionality

After configuring all files:

Restart Keeper and ClickHouse on all nodes using the following commands:

systemctl restart clickhouse-keeper
systemctl restart clickhouse-server

Verify that the cluster is visible:

SELECT *
FROM system.clusters
WHERE cluster = 'cluster_name';

Check the connection to Keeper:

SELECT *
FROM system.zookeeper
LIMIT 10;

Successful execution of the query, returning data or a list of directories, indicates a functional connection to Keeper.

ClickHouse Configuration Structure​

Main Directories and Files​

Single-node clickhouse-server Configuration​

Network Ports and listen_host​

Users and Profiles​

Detailed TLS/SSL Configuration​

Ports and interserver HTTPS Scheme​

Server SSL Settings​

Client SSL Settings​

Set of Certificates and Keys on Each Node​

Transitioning to Cluster Mode​

Connecting clickhouse-server to Keeper​

Cluster Configuration​

Cluster Macros (macros.xml)​

Configuration Example​

Inter-Server Credentials​

Verifying Cluster Functionality​