メインコンテンツへスキップ
メインコンテンツへスキップ

TLS の設定

Not supported in ClickHouse Cloud
注記

このページは ClickHouse Cloud には適用されません。ここで説明している手順は、ClickHouse Cloud サービスでは自動化されています。

このガイドでは、ClickHouse が接続を検証するために OpenSSL 証明書を使用するよう構成するための、シンプルで最小限の設定方法を説明します。このデモンストレーションでは、自己署名の認証局 (CA) 証明書と秘密鍵を作成し、ノード証明書とともに使用して、適切な設定で接続を確立します。

注記

TLS の実装は複雑であり、完全に安全で堅牢なデプロイメントを実現するには、多くのオプションを検討する必要があります。ここでは、基本的な TLS 構成例のみを扱う入門的なチュートリアルです。組織に適した証明書を生成するには、PKI / セキュリティチームに相談してください。

概要レベルの導入として、この 証明書の利用に関する基本チュートリアル を参照してください。

ClickHouse デプロイメントを作成する​

このガイドは、Ubuntu 20.04 と、DEB パッケージ（apt を使用）で以下のホストにインストールされた ClickHouse を使用して作成されています。ドメインは marsnet.local です:

HostIP Address
chnode1192.168.1.221
chnode2192.168.1.222
chnode3192.168.1.223
注記

ClickHouse のインストール方法の詳細については、クイックスタートを参照してください。

TLS 証明書を作成する​

注記

自己署名証明書の使用はデモ目的に限られ、本番環境では使用すべきではありません。証明書要求は組織によって署名されるように作成し、設定で構成される CA チェーンを使用して検証する必要があります。ただし、これらの手順は設定の構成とテストに使用でき、その後、実際に使用する証明書に置き換えることができます。

  1. 新しい CA に使用する鍵を生成します:

    openssl genrsa -out marsnet_ca.key 2048

  2. 新しい自己署名 CA 証明書を生成します。以下のコマンドは、CA 鍵を使用して他の証明書に署名するための新しい証明書を作成します:

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

    鍵と CA 証明書は、クラスタの外部にある安全な場所にバックアップしてください。ノード証明書の生成後、この鍵はクラスタノードから削除する必要があります。

  3. 新しい CA 証明書の内容を確認します:

    openssl x509 -in marsnet_ca.crt -text

  4. 各ノードについて、証明書要求（CSR）を作成し、鍵を生成します:

    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. CSR と CA を使用して、新しい証明書と鍵のペアを作成します:

    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. 証明書のサブジェクトと発行者を確認します:

    openssl x509 -in chnode1.crt -text -noout

  7. 新しい証明書が CA 証明書に対して検証されることを確認します:

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

証明書と鍵を保存するディレクトリを作成して設定する。​

注記

これは各ノードで実行する必要があります。各ホストでは適切な証明書と鍵を使用してください。

  1. 各ノードで、ClickHouse からアクセス可能なディレクトリにフォルダを作成します。デフォルトの設定ディレクトリ（例: /etc/clickhouse-server）を使用することを推奨します:

    mkdir /etc/clickhouse-server/certs

  2. CA 証明書と、各ノードに対応するノード証明書および鍵を、新しい certs ディレクトリにコピーします。

  3. ClickHouse が証明書を読み取れるように、所有者とパーミッションを更新します:

    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

ClickHouse Keeper を使用して基本クラスタで環境を構成する​

このデプロイ環境では、各ノードで以下の ClickHouse Keeper 設定を使用します。各サーバーはそれぞれ独自の <server_id> を持ちます。（たとえば、ノード chnode1 では <server_id>1</server_id> です。以下同様です。）

注記

ClickHouse Keeper の推奨ポートは 9281 です。ただし、このポートは構成可能であり、環境内で別のアプリケーションがすでに使用している場合は変更できます。

すべてのオプションの完全な説明については、https://clickhouse.com/docs/operations/clickhouse-keeper/ を参照してください。

  1. ClickHouse サーバーの config.xml の <clickhouse> タグ内に以下を追加します

    注記

    本番環境では、config.d ディレクトリ内の個別の .xml 設定ファイルを使用することを推奨します。 詳細については、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>
    注記

    ClickHouse Keeper が ClickHouse サーバーに埋め込まれている場合（上記のとおり）、Keeper は ClickHouse ノードで TLS インターフェースを設定する の OpenSSL セクションで定義されたサーバーの OpenSSL 設定を使用します。ClickHouse Keeper をスタンドアロンプロセスとして実行する場合は、同じ CA 証明書とノード証明書/鍵の設定を含む <openSSL> セクションを Keeper 設定ファイルに追加する必要があります。詳細については、以下の スタンドアロンの ClickHouse Keeper 向けに OpenSSL を設定する を参照してください。

  2. すべてのノードで keeper 設定のコメントを解除して更新し、<secure> フラグを 1 に設定します:

    <zookeeper>
    <node>
        <host>chnode1.marsnet.local</host>
        <port>9281</port>
        <secure>1</secure>
    </node>
    <node>
        <host>chnode2.marsnet.local</host>
        <port>9281</port>
        <secure>1</secure>
    </node>
    <node>
        <host>chnode3.marsnet.local</host>
        <port>9281</port>
        <secure>1</secure>
    </node>
</zookeeper>

  3. chnode1 と chnode2 に、以下のクラスタ設定を更新して追加します。chnode3 は ClickHouse Keeper クォーラムに使用されます。

    注記

    この構成では、1 つのサンプルクラスタのみを構成します。テスト用サンプルクラスタは削除するか、コメントアウトする必要があります。あるいは、テスト対象の既存クラスタがある場合は、ポートを更新し、<secure> オプションを追加する必要があります。インストール時または users.xml ファイルで default ユーザーに最初からパスワードが設定されていた場合は、<user と <password> を設定する必要があります。

    以下により、2 台のサーバー（各ノードに 1 台ずつ）上に、1 シャード 2 レプリカのクラスタが作成されます。

    <remote_servers>
    <cluster_1S_2R>
        <shard>
            <replica>
                <host>chnode1.marsnet.local</host>
                <port>9440</port>
                <user>default</user>
                <password>ClickHouse123!</password>
                <secure>1</secure>
            </replica>
            <replica>
                <host>chnode2.marsnet.local</host>
                <port>9440</port>
                <user>default</user>
                <password>ClickHouse123!</password>
                <secure>1</secure>
            </replica>
        </shard>
    </cluster_1S_2R>
</remote_servers>

  4. テスト用の ReplicatedMergeTree テーブルを作成できるように、macros の値を定義します。chnode1 では:

    <macros>
    <shard>1</shard>
    <replica>replica_1</replica>
</macros>

    chnode2 では:

    <macros>
    <shard>1</shard>
    <replica>replica_2</replica>
</macros>

ClickHouse ノードで TLS インターフェースを設定する​

以下の設定は ClickHouse サーバーの config.xml で構成します

  1. デプロイメントの表示名を設定します（任意）:

    <display_name>clickhouse</display_name>

  2. ClickHouse が外部ポートで待ち受けるように設定します:

    <listen_host>0.0.0.0</listen_host>

  3. 各ノードで https ポートを構成し、http ポートを無効にします:

    <https_port>8443</https_port>
<!--<http_port>8123</http_port>-->

  4. 各ノードで ClickHouse Native のセキュアな TCP ポートを構成し、デフォルトの非セキュアポートを無効にします:

    <tcp_port_secure>9440</tcp_port_secure>
<!--<tcp_port>9000</tcp_port>-->

  5. 各ノードで interserver https ポートを構成し、デフォルトの非セキュアポートを無効にします:

    <interserver_https_port>9010</interserver_https_port>
<!--<interserver_http_port>9009</interserver_http_port>-->

  6. 証明書とパスを指定して OpenSSL を構成します

    注記

    各ファイル名とパスは、設定対象のノードに合わせて更新する必要があります。 たとえば、chnode2 ホストで設定する場合は、<certificateFile> エントリを chnode2.crt に更新します。

    <openSSL>
    <server>
        <certificateFile>/etc/clickhouse-server/certs/chnode1.crt</certificateFile>
        <privateKeyFile>/etc/clickhouse-server/certs/chnode1.key</privateKeyFile>
        <verificationMode>relaxed</verificationMode>
        <caConfig>/etc/clickhouse-server/certs/marsnet_ca.crt</caConfig>
        <cacheSessions>true</cacheSessions>
        <disableProtocols>sslv2,sslv3</disableProtocols>
        <preferServerCiphers>true</preferServerCiphers>
    </server>
    <client>
        <loadDefaultCAFile>false</loadDefaultCAFile>
        <caConfig>/etc/clickhouse-server/certs/marsnet_ca.crt</caConfig>
        <cacheSessions>true</cacheSessions>
        <disableProtocols>sslv2,sslv3</disableProtocols>
        <preferServerCiphers>true</preferServerCiphers>
        <verificationMode>relaxed</verificationMode>
        <invalidCertificateHandler>
            <name>RejectCertificateHandler</name>
        </invalidCertificateHandler>
    </client>
</openSSL>

    詳細については、https://clickhouse.com/docs/operations/server-configuration-parameters/settings/#server_configuration_parameters-openssl を参照してください。

  7. すべてのノードで gRPC 用の TLS を構成します:

    <grpc>
    <enable_ssl>1</enable_ssl>
    <ssl_cert_file>/etc/clickhouse-server/certs/chnode1.crt</ssl_cert_file>
    <ssl_key_file>/etc/clickhouse-server/certs/chnode1.key</ssl_key_file>
    <ssl_require_client_auth>true</ssl_require_client_auth>
    <ssl_ca_cert_file>/etc/clickhouse-server/certs/marsnet_ca.crt</ssl_ca_cert_file>
    <transport_compression_type>none</transport_compression_type>
    <transport_compression_level>0</transport_compression_level>
    <max_send_message_size>-1</max_send_message_size>
    <max_receive_message_size>-1</max_receive_message_size>
    <verbose_logs>false</verbose_logs>
</grpc>

    詳細については、https://clickhouse.com/docs/interfaces/grpc/ を参照してください。

  8. 少なくとも 1 つのノードで、ClickHouse クライアントが接続に TLS を使用するように、そのノード自身の config.xml ファイル（デフォルトでは /etc/clickhouse-client/）で設定します:

    <openSSL>
    <client>
        <loadDefaultCAFile>false</loadDefaultCAFile>
        <caConfig>/etc/clickhouse-server/certs/marsnet_ca.crt</caConfig>
        <cacheSessions>true</cacheSessions>
        <disableProtocols>sslv2,sslv3</disableProtocols>
        <preferServerCiphers>true</preferServerCiphers>
        <invalidCertificateHandler>
            <name>RejectCertificateHandler</name>
        </invalidCertificateHandler>
    </client>
</openSSL>

  9. MySQL と PostgreSQL のデフォルトのエミュレーションポートを無効にします:

    <!--mysql_port>9004</mysql_port-->
<!--postgresql_port>9005</postgresql_port-->

テスト​

  1. すべてのノードを 1 台ずつ起動します:

    service clickhouse-server start

  2. セキュアポートが起動して待ち受けていることを確認します。各ノードで、次の例のように表示されるはずです:

    root@chnode1:/etc/clickhouse-server# netstat -ano | grep tcp

    tcp        0      0 0.0.0.0:9010            0.0.0.0:*               LISTEN      off (0.00/0/0)
tcp        0      0 127.0.0.53:53           0.0.0.0:*               LISTEN      off (0.00/0/0)
tcp        0      0 0.0.0.0:22              0.0.0.0:*               LISTEN      off (0.00/0/0)
tcp        0      0 0.0.0.0:8443            0.0.0.0:*               LISTEN      off (0.00/0/0)
tcp        0      0 0.0.0.0:9440            0.0.0.0:*               LISTEN      off (0.00/0/0)
tcp        0      0 0.0.0.0:9281            0.0.0.0:*               LISTEN      off (0.00/0/0)
tcp        0      0 192.168.1.221:33046     192.168.1.222:9444      ESTABLISHED off (0.00/0/0)
tcp        0      0 192.168.1.221:42730     192.168.1.223:9444      ESTABLISHED off (0.00/0/0)
tcp        0      0 192.168.1.221:51952     192.168.1.222:9281      ESTABLISHED off (0.00/0/0)
tcp        0      0 192.168.1.221:22        192.168.1.210:49801     ESTABLISHED keepalive (6618.05/0/0)
tcp        0     64 192.168.1.221:22        192.168.1.210:59195     ESTABLISHED on (0.24/0/0)
tcp6       0      0 :::22                   :::*                    LISTEN      off (0.00/0/0)
tcp6       0      0 :::9444                 :::*                    LISTEN      off (0.00/0/0)
tcp6       0      0 192.168.1.221:9444      192.168.1.222:59046     ESTABLISHED off (0.00/0/0)
tcp6       0      0 192.168.1.221:9444      192.168.1.223:41976     ESTABLISHED off (0.00/0/0)
    ClickHouse PortDescription
    8443https インターフェース
    9010interserver https ポート
    9281ClickHouse Keeper セキュアポート
    9440セキュアな Native TCP プロトコル
    9444ClickHouse Keeper Raft ポート

  3. ClickHouse Keeper の正常性を確認します The typical 4 letter word (4lW) commands won't work using echo without TLS, here is how to use the commands with openssl.

    • openssl で対話セッションを開始します
openssl s_client -connect chnode1.marsnet.local:9281

CONNECTED(00000003)
depth=0 CN = chnode1
verify error:num=20:unable to get local issuer certificate
verify return:1
depth=0 CN = chnode1
verify error:num=21:unable to verify the first certificate
verify return:1
---
Certificate chain
 0 s:CN = chnode1
   i:CN = marsnet.local CA
---
Server certificate
-----BEGIN CERTIFICATE-----
MIICtDCCAZwCFD321grxU3G5pf6hjitf2u7vkusYMA0GCSqGSIb3DQEBCwUAMBsx
...

  • OpenSSL セッションで 4LW コマンドを送信します

    mntr

    ---
Post-Handshake New Session Ticket arrived:
SSL-Session:
    Protocol  : TLSv1.3
...
read R BLOCK
zk_version      v22.7.3.5-stable-e140b8b5f3a5b660b6b576747063fd040f583cf3
zk_avg_latency  0
# highlight-next-line
zk_max_latency  4087
zk_min_latency  0
zk_packets_received     4565774
zk_packets_sent 4565773
zk_num_alive_connections        2
zk_outstanding_requests 0
# highlight-next-line
zk_server_state leader
zk_znode_count  1087
zk_watch_count  26
zk_ephemerals_count     12
zk_approximate_data_size        426062
zk_key_arena_size       258048
zk_latest_snapshot_size 0
zk_open_file_descriptor_count   187
zk_max_file_descriptor_count    18446744073709551615
# highlight-next-line
zk_followers    2
zk_synced_followers     1
closed

  1. --secure フラグと TLS ポートを指定して ClickHouse クライアントを起動します:

    root@chnode1:/etc/clickhouse-server# clickhouse-client --user default --password ClickHouse123! --port 9440 --secure --host chnode1.marsnet.local
ClickHouse client version 22.3.3.44 (official build).
Connecting to chnode1.marsnet.local:9440 as user default.
Connected to ClickHouse server version 22.3.3 revision 54455.

clickhouse :)

  2. https://chnode1.marsnet.local:8443/play にある https インターフェースを使用して Play UI にログインします。

    Configuring TLS
    注記

    ワークステーションからアクセスしており、証明書がクライアントマシンのルート CA ストアに含まれていないため、ブラウザには信頼されていない証明書として表示されます。 公開認証局またはエンタープライズ CA によって発行された証明書を使用している場合は、信頼済みとして表示されるはずです。

  3. レプリケートテーブルを作成します:

    clickhouse :) CREATE TABLE repl_table ON CLUSTER cluster_1S_2R
            (
                id UInt64,
                column1 Date,
                column2 String
            )
            ENGINE = ReplicatedMergeTree('/clickhouse/tables/{shard}/default/repl_table', '{replica}' )
            ORDER BY (id);

    ┌─host──────────────────┬─port─┬─status─┬─error─┬─num_hosts_remaining─┬─num_hosts_active─┐
│ chnode2.marsnet.local │ 9440 │      0 │       │                   1 │                0 │
│ chnode1.marsnet.local │ 9440 │      0 │       │                   0 │                0 │
└───────────────────────┴──────┴────────┴───────┴─────────────────────┴──────────────────┘

  4. chnode1 に数行追加します:

    INSERT INTO repl_table
(id, column1, column2)
VALUES
(1,'2022-04-01','abc'),
(2,'2022-04-02','def');

  5. chnode2 で行を表示してレプリケーションを確認します:

    SELECT * FROM repl_table

    ┌─id─┬────column1─┬─column2─┐
│  1 │ 2022-04-01 │ abc     │
│  2 │ 2022-04-02 │ def     │
└────┴────────────┴─────────┘

スタンドアロンの ClickHouse Keeper 向けに OpenSSL を設定する​

ClickHouse Keeper をスタンドアロン プロセスとして実行する場合 (ClickHouse サーバーに組み込むのではなく) 、OpenSSL の証明書と設定は Keeper の設定ファイルで個別に設定する必要があります。これを行わないと、Keeper はクライアント通信用のセキュアな接続 (tcp_port_secure) や、Keeper ノード間の Raft レプリケーションのためのセキュアな接続を確立できません。

各ノードのスタンドアロン ClickHouse Keeper 設定ファイルに、次の <openSSL> セクションを追加します。

注記

各ファイル名は、設定対象のノードに合わせて更新する必要があります。 たとえば、chnode2 ホストで設定する場合は、<certificateFile> の項目を chnode2.crt に更新します。

<openSSL>
    <server>
        <certificateFile>/etc/clickhouse-keeper/certs/chnode1.crt</certificateFile>
        <privateKeyFile>/etc/clickhouse-keeper/certs/chnode1.key</privateKeyFile>
        <verificationMode>relaxed</verificationMode>
        <caConfig>/etc/clickhouse-keeper/certs/marsnet_ca.crt</caConfig>
        <cacheSessions>true</cacheSessions>
        <disableProtocols>sslv2,sslv3</disableProtocols>
        <preferServerCiphers>true</preferServerCiphers>
    </server>
    <client>
        <loadDefaultCAFile>false</loadDefaultCAFile>
        <caConfig>/etc/clickhouse-keeper/certs/marsnet_ca.crt</caConfig>
        <cacheSessions>true</cacheSessions>
        <disableProtocols>sslv2,sslv3</disableProtocols>
        <preferServerCiphers>true</preferServerCiphers>
        <verificationMode>relaxed</verificationMode>
        <invalidCertificateHandler>
            <name>RejectCertificateHandler</name>
        </invalidCertificateHandler>
    </client>
</openSSL>

<server> セクションは、セキュアな Keeper ポート (tcp_port_secure) で受信するクライアント接続に使用します。<client> セクションは、Raft レプリケーション中に Keeper ノード間で確立される送信接続に使用します。

注記

上記の証明書パスには /etc/clickhouse-keeper/certs/ を使用しています。これはスタンドアロンの Keeper インストールで一般的なパスです。別のパスで Keeper をインストールした場合は、それに合わせて調整してください。証明書自体は、手順 2 で作成したものと同じです。

要約​

この記事では、ClickHouse 環境で TLS を用いた設定方法に焦点を当てました。本番環境では要件に応じて、証明書検証レベル、プロトコル、暗号スイートなどの設定が異なります。ここまでの内容により、安全な接続を構成し実装するための手順について十分に理解できているはずです。