Set up docs MCPこのガイドでは、OpenSSL 証明書を使用して接続を検証するよう ClickHouse を設定するための、シンプルで最小限の構成を説明します。このデモでは、適切な設定で接続できるように、自己署名の認証局 (CA) 証明書と秘密鍵を作成し、あわせてノード証明書も用意します。
ClickHouse デプロイメントを作成する
このガイドは、Ubuntu 20.04 を使用し、以下のホストに DEB パッケージ (apt を使用) で ClickHouse をインストールした環境を前提に作成されています。ドメインは marsnet.local です。
| Host | IP Address |
|---|---|
chnode1 |
192.168.1.221 |
chnode2 |
192.168.1.222 |
chnode3 |
192.168.1.223 |
TLS 証明書を作成する
-
新しい CA で使用する秘密鍵を生成します:
openssl genrsa -out marsnet_ca.key 2048 -
新しい自己署名 CA 証明書を生成します。以下のコマンドは、CA の秘密鍵を使用して他の証明書に署名するための新しい証明書を作成します:
openssl req -x509 -subj "/CN=marsnet.local CA" -nodes -key marsnet_ca.key -days 1095 -out marsnet_ca.crt
-
新しい CA 証明書の内容を確認します:
openssl x509 -in marsnet_ca.crt -text -
各ノードの証明書要求 (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 -
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 -
subject と issuer を確認します:
openssl x509 -in chnode1.crt -text -noout -
新しい証明書が CA 証明書で検証できることを確認します:
openssl verify -CAfile marsnet_ca.crt chnode1.crt chnode1.crt: OK
証明書と秘密鍵を格納するディレクトリを作成して設定します。
-
各ノードで、ClickHouse からアクセス可能な場所にフォルダを作成します。デフォルトの設定ディレクトリ (例:
/etc/clickhouse-server) を使用することを推奨します。mkdir /etc/clickhouse-server/certs -
各ノードに対応する CA証明書、ノード証明書、および秘密鍵を、新しく作成した certs ディレクトリにコピーします。
-
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/certstotal 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 server の
config.xmlの<clickhouse>タグ内に以下を追加します
<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>-
すべてのノードで 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> -
chnode1とchnode2のクラスター設定を更新し、以下の設定を追加します。chnode3は ClickHouse Keeper のクォーラムに使用します。
以下は、2台のサーバー (各ノードに1台) に1つの分片レプリカを持つクラスターを作成します。
<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>-
テスト用のReplicatedMergeTreeテーブルを作成できるよう、マクロの値を定義します。
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 で行います。
-
デプロイメントの表示名を設定します (任意) 。
<display_name>clickhouse</display_name> -
ClickHouse が外部ポートでリッスンするように設定します。
<listen_host>0.0.0.0</listen_host> -
各ノードで
httpsポートを設定し、httpポートを無効にします。<https_port>8443</https_port> {/*<http_port>8123</http_port>*/} -
各ノードで ClickHouse Native のセキュアな TCP ポートを設定し、デフォルトの非セキュアポートを無効にします。
<tcp_port_secure>9440</tcp_port_secure> {/*<tcp_port>9000</tcp_port>*/} -
各ノードで
interserver httpsポートを設定し、デフォルトの非セキュアポートを無効にします。<interserver_https_port>9010</interserver_https_port> {/*<interserver_http_port>9009</interserver_http_port>*/} -
証明書とパスを指定して OpenSSL を設定します
<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>詳細については、このページを参照してください。
-
すべてのノードで 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/ を参照してください。
-
少なくとも 1 つのノードで、ClickHouse client が自身の
config.xmlファイル (デフォルトでは/etc/clickhouse-client/) で接続に TLS を使用するよう設定します。<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> -
MySQL および PostgreSQL のデフォルトのエミュレーションポートを無効にします。
{/*mysql_port>9004</mysql_port*/} {/*postgresql_port>9005</postgresql_port*/}
テスト
-
各ノードを順番に起動します:
service clickhouse-server start -
セキュアなポートが起動し、待ち受け状態になっていることを確認してください。各ノードでは、次の例のように表示されるはずです:
root@chnode1:/etc/clickhouse-server# netstat -ano | grep tcptcp 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 ポート 説明 8443 HTTPS インターフェイス 9010 サーバー間 HTTPS ポート 9281 ClickHouse Keeper のセキュアポート 9440 セキュアなネイティブ TCP プロトコル 9444 ClickHouse Keeper Raft ポート -
ClickHouse Keeper の正常性を確認する 一般的な 4 letter word (4lW) コマンドは、TLS なしで
echoを使っても動作しません。以下では、opensslを使ってこれらのコマンドを実行する方法を示します。opensslで対話セッションを開始する
openssl s_client -connect chnode1.marsnet.local:9281CONNECTED(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 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 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 zk_followers 2 zk_synced_followers 1 closed
-
--secureフラグと TLS ポートを指定して ClickHouse client を起動します: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 :) -
https://chnode1.marsnet.local:8443/playのhttpsインターフェイス経由で Play UI にログインします。
-
レプリケートテーブルを作成します。
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 │ └───────────────────────┴──────┴────────┴───────┴─────────────────────┴──────────────────┘ -
chnode1に2行ほど追加します:INSERT INTO repl_table (id, column1, column2) VALUES (1,'2022-04-01','abc'), (2,'2022-04-02','def'); -
chnode2上の行を確認して、レプリケーションを検証します:SELECT * FROM repl_table┌─id─┬────column1─┬─column2─┐ │ 1 │ 2022-04-01 │ abc │ │ 2 │ 2022-04-02 │ def │ └────┴────────────┴─────────┘
スタンドアロンの ClickHouse Keeper 向けに OpenSSL を設定する
ClickHouse Keeper をスタンドアロンのプロセスとして実行する場合 (ClickHouse server に埋め込んで実行するのではなく) 、OpenSSL の証明書と設定は Keeper の設定ファイルで個別に構成する必要があります。これを行わないと、Keeper はクライアント通信用の secure connections (tcp_port_secure) や、Keeper ノード間の Raft レプリケーションを確立できません。
各ノードのスタンドアロンの ClickHouse Keeper の設定ファイルに、次の <openSSL> セクションを追加してください。
<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 ノード間で行われる送信接続に使用されます。
OpenSSL の検証モードと証明書ハンドラ
<openSSL> の設定では、ClickHouse による TLS 証明書の検証方法を制御する <verificationMode> と <invalidCertificateHandler> に、いくつかのオプションが用意されています。これらの設定は、clickhouse-server、clickhouse-client、およびスタンドアロンの ClickHouse Keeper に適用されます。
検証モード
<openSSL> の <server> または <client> セクション内で <verificationMode> を設定します。
| モード | 説明 |
|---|---|
none |
証明書の検証は行いません。接続は暗号化されますが、ピアの身元は確認されません。テスト用途でのみ使用してください。 |
relaxed |
ピア証明書が提示された場合は検証しますが、証明書が提供されなくても失敗しません。 |
once |
サーバー側では、初回のハンドシェイク時にのみクライアント証明書を検証し、再ネゴシエーション時は検証を省略します。クライアント側では、relaxed と同じ動作をします。 |
strict |
ピア証明書を必須とし、完全に検証します。証明書がない場合、期限切れの場合、または信頼された CA によって署名されていない場合、接続は失敗します。本番環境に推奨されます。 |
無効な証明書ハンドラ
<openSSL> の <server> または <client> セクション内で <invalidCertificateHandler> を設定します。このハンドラーは、証明書の検証に失敗した場合の動作を決定します。サーバー側では、無効なクライアント証明書に対する応答を制御します。クライアント側では、無効なサーバー証明書に対する応答を制御します。
| ハンドラー | 説明 |
|---|---|
RejectCertificateHandler |
証明書が無効な場合、接続を拒否します。これはデフォルトかつ推奨の設定です。 |
AcceptCertificateHandler |
証明書が無効でも接続を受け入れます。これはテスト目的でのみ使用してください。 |
例: 証明書の検証を無効にする
証明書の検証を完全にスキップするには (たとえば、テスト環境で自己署名証明書を使用する場合) 、verificationMode を none に設定し、AcceptCertificateHandler を使用します。
clickhouse-client では、--accept-invalid-certificate CLI フラグを使用することもでき、このフラグを指定すると両方の設定が自動的に適用されます。
clickhouse-client (/etc/clickhouse-client/config.xml):
<openSSL>
<client>
<loadDefaultCAFile>false</loadDefaultCAFile>
<cacheSessions>true</cacheSessions>
<disableProtocols>sslv2,sslv3</disableProtocols>
<preferServerCiphers>true</preferServerCiphers>
<verificationMode>none</verificationMode>
<invalidCertificateHandler>
<name>AcceptCertificateHandler</name>
</invalidCertificateHandler>
</client>
</openSSL>clickhouse-server (config.xml または config.d/ 内のファイル)。<server> セクションでは、クライアント証明書を検証しない場合でも、サーバー自身の証明書をクライアントに提示する必要があるため、引き続き証明書と秘密鍵のパスを指定する必要があります:
<openSSL>
<server>
<certificateFile>/etc/clickhouse-server/certs/server.crt</certificateFile>
<privateKeyFile>/etc/clickhouse-server/certs/server.key</privateKeyFile>
<verificationMode>none</verificationMode>
<caConfig>/etc/clickhouse-server/certs/ca.crt</caConfig>
<cacheSessions>true</cacheSessions>
<disableProtocols>sslv2,sslv3</disableProtocols>
<preferServerCiphers>true</preferServerCiphers>
</server>
<client>
<loadDefaultCAFile>false</loadDefaultCAFile>
<cacheSessions>true</cacheSessions>
<disableProtocols>sslv2,sslv3</disableProtocols>
<preferServerCiphers>true</preferServerCiphers>
<verificationMode>none</verificationMode>
<invalidCertificateHandler>
<name>AcceptCertificateHandler</name>
</invalidCertificateHandler>
</client>
</openSSL>スタンドアロンの ClickHouse Keeper (Keeper設定ファイル) :
<openSSL>
<server>
<certificateFile>/etc/clickhouse-keeper/certs/keeper.crt</certificateFile>
<privateKeyFile>/etc/clickhouse-keeper/certs/keeper.key</privateKeyFile>
<verificationMode>none</verificationMode>
<caConfig>/etc/clickhouse-keeper/certs/ca.crt</caConfig>
<cacheSessions>true</cacheSessions>
<disableProtocols>sslv2,sslv3</disableProtocols>
<preferServerCiphers>true</preferServerCiphers>
</server>
<client>
<loadDefaultCAFile>false</loadDefaultCAFile>
<cacheSessions>true</cacheSessions>
<disableProtocols>sslv2,sslv3</disableProtocols>
<preferServerCiphers>true</preferServerCiphers>
<verificationMode>none</verificationMode>
<invalidCertificateHandler>
<name>AcceptCertificateHandler</name>
</invalidCertificateHandler>
</client>
</openSSL>まとめ
この記事では、TLS を使用する ClickHouse 環境の構成について説明しました。本番環境では要件に応じて設定が異なり、たとえば証明書の検証レベル、プロトコル、暗号スイートなどが変わります。これで、安全な接続を構成して実装するために必要な手順を十分に理解できたはずです。