ClickHouse Installation & Configuration

1. Install ClickHouse on additional nodes #

Install NFA normally on the primary node. On additional nodes, install the same ClickHouse 26.3.x version as the NFA node. Example for Ubuntu/Debian:

cat >/etc/apt/preferences.d/nfa-clickhouse <<'EOF'
Package: clickhouse-*
Pin: version 26.3.*
Pin-Priority: 1001
EOF
apt-get update
apt-get install clickhouse-server clickhouse-client clickhouse-common

Important: Do not install NFA or nfaadm on additional ClickHouse nodes. Keep a newly installed ClickHouse Server stopped until all configuration files are ready, if possible.

2. Configure name resolution #

All nodes must resolve all cluster hostnames. Use DNS or add the following entries to /etc/hosts on every node:

192.0.2.10  shard1-node.example.com
192.0.2.11  shard2-node.example.com

Replace the example addresses with the actual reachable IP addresses. Verify connectivity to ClickHouse port 9000 on existing running nodes and Keeper port 9181 on the NFA node before applying changes. Newly installed nodes can be checked after startup.

3. Configure ClickHouse on every node #

Create or update the following files on every ClickHouse node. Existing NFA-provided configuration files may already exist; update them rather than creating conflicting copies.

3.1. Listen interface
/etc/clickhouse-server/config.d/listen.xml

<?xml version="1.0"?>
<clickhouse>
    <listen_host>0.0.0.0</listen_host>
</clickhouse>

3.2. Keeper connection
/etc/clickhouse-server/config.d/keeper.xml – identical on all nodes:

<?xml version="1.0"?>
<clickhouse>
    <zookeeper>
        <node>
            <host>://example.com</host>
            <port>9181</port>
        </node>
    </zookeeper>
</clickhouse>

3.3 Shard and replica identifiers
/etc/clickhouse-server/config.d/macros.xml – unique to each node. Example for Shard 01 / Replica 01:

<?xml version="1.0"?>
<clickhouse>
    <macros>
        <shard>01</shard>
        <replica>01</replica>
    </macros>
</clickhouse>

On shard2-node.example.com, set shard=02 and replica=01. Replicas within one shard share a shard ID but must have distinct replica IDs.

3.4. Cluster topology
/etc/clickhouse-server/config.d/cluster.xml – identical on all nodes:

<?xml version="1.0"?>
<clickhouse>
    <remote_servers>
        <nfa>
            <shard>
                <internal_replication>true</internal_replication>
                <replica>
                    <host>shard1-node.example.com</host>
                    <port>9000</port>
                </replica>
            </shard>
            <shard>
                <internal_replication>true</internal_replication>
                <replica>
                    <host>shard2-node.example.com</host>
                    <port>9000</port>
                </replica>
            </shard>
        </nfa>
    </remote_servers>
</clickhouse>

3.5. Distributed query setting (multi-shard installations)
/etc/clickhouse-server/users.d/n_distributed_product_mode.xml

<?xml version="1.0"?>
<clickhouse>
    <profiles>
        <default>
            <distributed_product_mode>global</distributed_product_mode>
        </default>
    </profiles>
</clickhouse>

3.6. Inter-node access
/etc/clickhouse-server/users.d/n_cluster_networks.xml – specify the actual trusted IP addresses of every ClickHouse node:

<?xml version="1.0"?>
<clickhouse>
    <users>
        <default>
            <networks>
                <ip>127.0.0.1</ip>
                <ip>::1</ip>
                <ip>192.0.2.10</ip>
                <ip>192.0.2.11</ip>
            </networks>
        </default>
    </users>
</clickhouse>

Important: NFA uses /etc/noction/clickhouse/users.xml as the primary user configuration. Do not edit it for this procedure. Preserve any additional existing network permissions needed by the installation. The default account shown here has no password: allow only trusted addresses.

4. Configure Keeper on the NFA node #

n /etc/clickhouse-keeper/keeper_config.xml, ensure Keeper listens on an address reachable by the other nodes:

<listen_host>0.0.0.0</listen_host>

If a change was needed, apply it once:

systemctl restart clickhouse-keeper

From each additional node, confirm Keeper connectivity:

nc -vz shard1-node.example.com 9181

If Keeper already accepts remote connections, do not restart it.