설정 파일

이 페이지에서는 ClickHouse 서버를 XML 또는 YAML 구문의 설정 파일로 구성하는 방법을 설명합니다.

XML 기반 settings profiles 및 설정 파일은 ClickHouse Cloud에서 지원되지 않습니다. 따라서 ClickHouse Cloud에서는 config.xml 파일을 찾을 수 없습니다. 대신 SQL 명령을 사용해 settings profiles를 통해 설정을 관리해야 합니다.

자세한 내용은 “설정 구성”을 참조하십시오.

ClickHouse 서버는 XML 또는 YAML 구문의 설정 파일로 구성할 수 있습니다. 대부분의 설치 방식에서 ClickHouse 서버는 /etc/clickhouse-server/config.xml을 기본 설정 파일로 사용해 실행되지만, 서버 시작 시 명령줄 옵션 --config-file 또는 -C를 사용하여 설정 파일 위치를 수동으로 지정할 수도 있습니다. 추가 설정 파일은 기본 설정 파일을 기준으로 하는 config.d/ 디렉터리(예: /etc/clickhouse-server/config.d/)에 둘 수 있습니다. 이 디렉터리의 파일과 기본 설정은 ClickHouse 서버에 구성이 적용되기 전에 전처리 단계에서 병합됩니다. 구성 조각은 전체 경로의 사전식 순서로 병합됩니다. 표준 config.d/ 디렉터리의 파일은 파일명순 정렬과 동일합니다. 기존 conf.d/ 디렉터리도 병합됩니다. conf.d는 config.d보다 먼저 정렬되므로 두 디렉터리가 모두 있으면 해당 조각이 먼저 처리됩니다. 업데이트를 단순화하고 모듈화를 개선하려면 기본 config.xml 파일은 수정하지 않고, 추가 사용자 지정은 config.d/에 두는 것이 모범 사례입니다. ClickHouse Keeper 구성은 /etc/clickhouse-keeper/keeper_config.xml에 있습니다. 마찬가지로 Keeper용 추가 설정 파일은 /etc/clickhouse-keeper/keeper_config.d/에 두어야 합니다.

XML과 YAML 설정 파일은 함께 사용할 수 있습니다. 예를 들어 기본 설정 파일로 config.xml을 두고, 추가 설정 파일로 config.d/network.xml, config.d/timezone.yaml, config.d/keeper.yaml을 둘 수 있습니다. 단일 설정 파일 안에서 XML과 YAML을 혼합하는 것은 지원되지 않습니다. XML 설정 파일은 최상위 태그로 <clickhouse>...</clickhouse>를 사용해야 합니다. YAML 설정 파일에서는 clickhouse:가 선택 사항이며, 없으면 파서가 이를 자동으로 삽입합니다.

​

구성 병합

두 개의 설정 파일(일반적으로 기본 설정 파일과 config.d/의 다른 설정 파일)은 다음과 같이 병합됩니다:

• 노드(즉, 요소로 이어지는 경로)가 두 파일에 모두 존재하고 replace 또는 remove 속성이 없으면, 해당 노드는 병합된 설정 파일에 포함되며 두 노드의 자식 요소가 모두 포함되어 재귀적으로 병합됩니다.
• 두 노드 중 하나에 replace 속성이 있으면, 해당 노드는 병합된 설정 파일에 포함되지만 replace 속성이 있는 노드의 자식 요소만 포함됩니다.
• 두 노드 중 하나에 remove 속성이 있으면, 해당 노드는 병합된 설정 파일에 포함되지 않습니다(이미 존재하는 경우 삭제됩니다).

예를 들어, 두 개의 설정 파일이 다음과 같다고 가정하겠습니다:

config.xml

<clickhouse>
    <config_a>
        <setting_1>1</setting_1>
    </config_a>
    <config_b>
        <setting_2>2</setting_2>
    </config_b>
    <config_c>
        <setting_3>3</setting_3>
    </config_c>
</clickhouse>

및

config.d/other_config.xml

<clickhouse>
    <config_a>
        <setting_4>4</setting_4>
    </config_a>
    <config_b replace="replace">
        <setting_5>5</setting_5>
    </config_b>
    <config_c remove="remove">
        <setting_6>6</setting_6>
    </config_c>
</clickhouse>

그 결과 머지된 설정 파일은 다음과 같습니다:

<clickhouse>
    <config_a>
        <setting_1>1</setting_1>
        <setting_4>4</setting_4>
    </config_a>
    <config_b>
        <setting_5>5</setting_5>
    </config_b>
</clickhouse>

​

환경 변수 및 ZooKeeper 노드를 사용한 치환

요소의 값이 환경 변수의 값으로 대체되도록 지정하려면 from_env 속성을 사용할 수 있습니다.

예를 들어, 환경 변수 $MAX_QUERY_SIZE = 150000이 설정되어 있으면:

<clickhouse>
    <profiles>
        <default>
            <max_query_size from_env="MAX_QUERY_SIZE"/>
        </default>
    </profiles>
</clickhouse>

결과 구성은 다음과 같습니다:

<clickhouse>
    <profiles>
        <default>
            <max_query_size>150000</max_query_size>
        </default>
    </profiles>
</clickhouse>

from_zk(ZooKeeper 노드)를 사용해도 동일하게 할 수 있습니다:

<clickhouse>
    <postgresql_port from_zk="/zk_configs/postgresql_port"/>
</clickhouse>

# clickhouse-keeper-client
/ :) touch /zk_configs
/ :) create /zk_configs/postgresql_port "9005"
/ :) get /zk_configs/postgresql_port
9005

그러면 다음과 같은 구성이 됩니다:

<clickhouse>
    <postgresql_port>9005</postgresql_port>
</clickhouse>

​

기본값

from_env 또는 from_zk 속성이 있는 요소에는 replace="1" 속성을 추가로 지정할 수 있습니다(replace="1"은 from_env/from_zk보다 앞에 와야 합니다). 이 경우 요소에 기본값을 정의할 수 있습니다. 값이 설정되어 있으면 요소는 환경 변수 또는 ZooKeeper 노드의 값을 사용하고, 그렇지 않으면 기본값을 사용합니다.

앞선 예시를 다시 살펴보되, MAX_QUERY_SIZE가 설정되지 않았다고 가정합니다:

<clickhouse>
    <profiles>
        <default>
            <max_query_size replace="1" from_env="MAX_QUERY_SIZE">150000</max_query_size>
        </default>
    </profiles>
</clickhouse>

그러면 다음과 같은 구성이 됩니다:

<clickhouse>
    <profiles>
        <default>
            <max_query_size>150000</max_query_size>
        </default>
    </profiles>
</clickhouse>

​

파일 내용으로 치환

파일 내용을 사용해 구성의 일부를 대체할 수도 있습니다. 이는 두 가지 방식으로 수행할 수 있습니다.

• 값 치환: 요소에 incl 속성이 있으면 해당 값이 참조된 파일의 내용으로 대체됩니다. 치환 값을 담은 파일의 경로는 서버 구성의 include_from 요소에서 설정합니다. 기본 경로는 없으므로, 지정한 경우에만 치환 값을 읽습니다. 치환 값은 이 파일의 /clickhouse/substitution_name 요소에 지정합니다. incl에 지정된 치환이 존재하지 않으면 로그에 기록됩니다. 누락된 치환에 대해 ClickHouse가 로그를 남기지 않도록 하려면 optional="true" 속성을 지정하십시오(예: macros 설정).
• 요소 치환: 전체 요소를 치환 값으로 바꾸려면 요소 이름으로 include를 사용하십시오. 요소 이름 include는 from_zk = "/path/to/node" 속성과 함께 사용할 수 있습니다. 이 경우 요소 값은 /path/to/node에 있는 ZooKeeper 노드의 내용으로 대체됩니다. 전체 XML 하위 트리를 ZooKeeper 노드에 저장한 경우에도 동일하게 작동하며, 해당 트리가 원본 요소에 완전히 삽입됩니다.

버전 26.8부터 변경됨: 이전 버전에서는 include_from을 지정하지 않았더라도 파일 /etc/metrika.xml이 존재하면 암묵적으로 사용되었습니다. 해당 파일에 의존하는 경우 include_from에 해당 경로를 명시적으로 지정하십시오. include_from은 각 구성 파일에서 개별적으로 읽힙니다. 즉, 기본 서버 구성과 별도로 로드되는 파일인 사용자’ 구성(예: 기본 파일에 포함되지 않은 경우의 users.xml) 및 XML 딕셔너리 구성에는 각각 자체 include_from 요소가 필요하며, 기본 서버 구성에만 지정해도 적용되지 않습니다.

이에 대한 예시는 아래와 같습니다.

<clickhouse>
    <!-- Appends XML subtree found at `/profiles-in-zookeeper` ZK path to `<profiles>` element. -->
    <profiles from_zk="/profiles-in-zookeeper" />

    <users>
        <!-- Replaces `include` element with the subtree found at `/users-in-zookeeper` ZK path. -->
        <include from_zk="/users-in-zookeeper" />
        <include from_zk="/other-users-in-zookeeper" />
    </users>
</clickhouse>

치환 콘텐츠를 추가하는 대신 기존 구성과 병합하려면 속성 merge="true"를 사용할 수 있습니다. 예시: <include from_zk="/some_path" merge="true">. 이 경우 기존 구성은 치환 콘텐츠와 병합되며, 기존 구성의 설정은 치환 콘텐츠의 값으로 대체됩니다.

​

구성 암호화 및 숨기기

대칭 암호화를 사용해 구성 요소를 암호화할 수 있습니다. 예를 들어 평문 비밀번호 또는 개인 키를 암호화할 수 있습니다. 이렇게 하려면 먼저 암호화 코덱을 구성한 다음, 암호화할 요소에 encrypted_by 속성을 추가하고 그 값으로 암호화 코덱 이름을 지정합니다.

속성 from_zk, from_env, incl 또는 요소 include와 달리, 전처리된 파일에서는 치환(즉, 암호화된 값의 복호화)이 수행되지 않습니다. 복호화는 서버 프로세스의 런타임에서만 수행됩니다.

예시:

<clickhouse>

    <encryption_codecs>
        <aes_128_gcm_siv>
            <key_hex>00112233445566778899aabbccddeeff</key_hex>
        </aes_128_gcm_siv>
    </encryption_codecs>

    <interserver_http_credentials>
        <user>admin</user>
        <password encrypted_by="AES_128_GCM_SIV">961F000000040000000000EEDDEF4F453CFE6457C4234BD7C09258BD651D85</password>
    </interserver_http_credentials>

</clickhouse>

속성 from_env와 from_zk는 encryption_codecs에도 적용할 수 있습니다:

<clickhouse>

    <encryption_codecs>
        <aes_128_gcm_siv>
            <key_hex from_env="CLICKHOUSE_KEY_HEX"/>
        </aes_128_gcm_siv>
    </encryption_codecs>

    <interserver_http_credentials>
        <user>admin</user>
        <password encrypted_by="AES_128_GCM_SIV">961F000000040000000000EEDDEF4F453CFE6457C4234BD7C09258BD651D85</password>
    </interserver_http_credentials>

</clickhouse>

<clickhouse>

    <encryption_codecs>
        <aes_128_gcm_siv>
            <key_hex from_zk="/clickhouse/aes128_key_hex"/>
        </aes_128_gcm_siv>
    </encryption_codecs>

    <interserver_http_credentials>
        <user>admin</user>
        <password encrypted_by="AES_128_GCM_SIV">961F000000040000000000EEDDEF4F453CFE6457C4234BD7C09258BD651D85</password>
    </interserver_http_credentials>

</clickhouse>

암호화 키와 암호화된 값은 두 구성 파일 중 어느 쪽에나 정의할 수 있습니다.

예시 config.xml은 다음과 같습니다:

<clickhouse>

    <encryption_codecs>
        <aes_128_gcm_siv>
            <key_hex from_zk="/clickhouse/aes128_key_hex"/>
        </aes_128_gcm_siv>
    </encryption_codecs>

</clickhouse>

다음은 users.xml의 예시입니다:

<clickhouse>

    <users>
        <test_user>
            <password encrypted_by="AES_128_GCM_SIV">96280000000D000000000030D4632962295D46C6FA4ABF007CCEC9C1D0E19DA5AF719C1D9A46C446</password>
            <profile>default</profile>
        </test_user>
    </users>

</clickhouse>

값을 암호화하려면 (예시) 프로그램 encrypt_decrypt를 사용할 수 있습니다:

./encrypt_decrypt /etc/clickhouse-server/config.xml -e AES_128_GCM_SIV abcd

961F000000040000000000EEDDEF4F453CFE6457C4234BD7C09258BD651D85

암호화된 구성 요소를 사용하더라도 암호화된 요소는 전처리된 설정 파일에 계속 표시됩니다. 이것이 ClickHouse 배포 환경에서 문제가 된다면 두 가지 대안이 있습니다. 전처리된 파일의 접근 권한을 600으로 설정하거나 속성 hide_in_preprocessed를 사용하십시오.

예시:

<clickhouse>

    <interserver_http_credentials hide_in_preprocessed="true">
        <user>admin</user>
        <password>secret</password>
    </interserver_http_credentials>

</clickhouse>

​

사용자 설정

config.xml 파일에서 사용자 설정, 프로필, 쿼터에 대한 별도의 구성을 지정할 수 있습니다. 이 구성의 상대 경로는 users_config 요소에서 설정합니다. 기본값은 users.xml입니다. users_config를 생략하면 사용자 설정, 프로필, 쿼터를 config.xml에 직접 지정합니다.

사용자 구성은 config.xml 및 config.d/와 마찬가지로 별도의 파일로 분리할 수 있습니다. 디렉터리 이름은 .xml 접미사를 제거한 users_config 설정값에 .d를 덧붙여 정의합니다. 기본적으로 users_config의 기본값이 users.xml이므로 users.d 디렉터리를 사용합니다. 사용자 구성 조각은 전체 경로의 사전순으로 병합됩니다. 표준 users.d/ 디렉터리의 파일에서는 파일 이름순으로 정렬하는 것과 동일합니다. 기존 conf.d/ 디렉터리도 병합되며, conf.d가 users.d보다 앞에 정렬되므로 두 디렉터리가 모두 존재할 때는 해당 조각이 모두 먼저 처리됩니다.

설정 파일은 먼저 설정을 고려하여 병합되며, 그 이후에 include가 처리된다는 점에 유의하십시오.

​

XML 예시

예를 들어, 사용자별로 다음과 같이 별도의 구성 파일을 둘 수 있습니다.

$ cat /etc/clickhouse-server/users.d/alice.xml

<clickhouse>
    <users>
      <alice>
          <profile>analytics</profile>
            <networks>
                  <ip>::/0</ip>
            </networks>
          <password_sha256_hex>...</password_sha256_hex>
          <quota>analytics</quota>
      </alice>
    </users>
</clickhouse>

​

YAML 예시

여기에서 YAML로 작성된 기본 구성을 확인할 수 있습니다: config.yaml.example.

ClickHouse 구성에서는 YAML 포맷과 XML 포맷 사이에 몇 가지 차이점이 있습니다. 아래에는 YAML 포맷으로 구성을 작성할 때 유용한 팁을 정리했습니다.

텍스트 값을 가진 XML 태그는 YAML의 키-값 쌍으로 표현됩니다.

key: value

해당 XML:

<key>value</key>

중첩된 XML 노드는 YAML 맵으로 나타냅니다:

map_key:
  key1: val1
  key2: val2
  key3: val3

해당 XML:

<map_key>
    <key1>val1</key1>
    <key2>val2</key2>
    <key3>val3</key3>
</map_key>

동일한 XML 태그를 여러 번 생성하려면 YAML 시퀀스를 사용하십시오.

seq_key:
  - val1
  - val2
  - key1: val3
  - map:
      key2: val4
      key3: val5

해당 XML:

<seq_key>val1</seq_key>
<seq_key>val2</seq_key>
<seq_key>
    <key1>val3</key1>
</seq_key>
<seq_key>
    <map>
        <key2>val4</key2>
        <key3>val5</key3>
    </map>
</seq_key>

XML 속성을 지정하려면 @ 접두사가 붙은 속성 키를 사용할 수 있습니다. @는 YAML 표준에서 예약된 문자이므로 큰따옴표로 감싸야 합니다:

map:
  "@attr1": value1
  "@attr2": value2
  key: 123

대응하는 XML:

<map attr1="value1" attr2="value2">
    <key>123</key>
</map>

YAML 시퀀스에서도 속성을 사용할 수 있습니다.

seq:
  - "@attr1": value1
  - "@attr2": value2
  - 123
  - abc

해당 XML:

<seq attr1="value1" attr2="value2">123</seq>
<seq attr1="value1" attr2="value2">abc</seq>

앞서 설명한 구문으로는 XML 속성이 있는 XML 텍스트 노드를 YAML로 표현할 수 없습니다. 이러한 특수한 경우에는 #text 속성 키를 사용하면 됩니다:

map_key:
  "@attr1": value1
  "#text": value2

해당하는 XML:

<map_key attr1="value1">value2</map>

​

구현 세부 사항

서버는 시작할 때 각 구성 파일에 대해 file-preprocessed.xml 파일도 생성합니다. 이 파일에는 적용이 완료된 모든 치환과 재정의가 포함되며, 참고용으로 제공됩니다. 구성 파일에서 ZooKeeper 치환을 사용했지만 서버 시작 시 ZooKeeper를 사용할 수 없는 경우, 서버는 전처리된 파일에서 구성을 로드합니다.

서버는 구성 파일의 변경 사항뿐 아니라 치환과 재정의를 수행할 때 사용된 파일 및 ZooKeeper 노드의 변경 사항도 추적하고, 사용자와 클러스터의 설정을 즉시 다시 로드합니다. 즉, 서버를 재시작하지 않고도 클러스터, 사용자 및 해당 설정을 수정할 수 있습니다.