Конфигурационные файлы

На этой странице объясняется, как настроить сервер ClickHouse с помощью конфигурационных файлов в формате XML или YAML.

Профили настроек и конфигурационные файлы на основе XML не поддерживаются в ClickHouse Cloud. Поэтому в ClickHouse Cloud вы не найдете файл config.xml. Вместо этого для управления настройками через профили настроек следует использовать команды SQL.

Подробнее см. в разделе “Настройка параметров”

Сервер ClickHouse можно настраивать с помощью конфигурационных файлов в формате XML или YAML. В большинстве вариантов установки сервер ClickHouse использует /etc/clickhouse-server/config.xml в качестве конфигурационного файла по умолчанию, но расположение конфигурационного файла также можно указать вручную при запуске сервера с помощью параметра командной строки --config-file или -C. Дополнительные конфигурационные файлы можно размещать в каталоге config.d/ относительно основного конфигурационного файла, например в каталоге /etc/clickhouse-server/config.d/. Файлы в этом каталоге и основная конфигурация объединяются на этапе предварительной обработки перед применением конфигурации в сервере ClickHouse. Конфигурационные файлы объединяются в алфавитном порядке. Чтобы упростить обновления и улучшить модульность, рекомендуется не изменять файл 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" (последний должен располагаться перед 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, его значение будет заменено содержимым указанного файла. По умолчанию путь к файлу с подстановками — /etc/metrika.xml. Его можно изменить в элементе include_from в конфигурации сервера. Значения для подстановки задаются в элементах /clickhouse/substitution_name в этом файле. Если подстановка, указанная в incl, не существует, об этом будет сделана запись в журнале. Чтобы ClickHouse не писал в журнал об отсутствующих подстановках, укажите атрибут optional="true" (например, для настроек macros).
• Подстановка элементов: Если вы хотите заменить подстановкой весь элемент целиком, используйте include в качестве имени элемента. Имя элемента include можно использовать вместе с атрибутом from_zk = "/path/to/node". В этом случае значение элемента заменяется содержимым узла ZooKeeper по пути /path/to/node. Это также работает, если вы храните в узле ZooKeeper всё XML-поддерево: оно будет полностью вставлено в исходный элемент.

Пример показан ниже:

<clickhouse>
    <!-- Добавляет XML-поддерево, найденное по ZK-пути `/profiles-in-zookeeper`, к элементу `<profiles>`. -->
    <profiles from_zk="/profiles-in-zookeeper" />

    <users>
        <!-- Заменяет элемент `include` поддеревом, найденным по ZK-пути `/users-in-zookeeper`. -->
        <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/. Имя каталога определяется как значение параметра users_config без суффикса .xml с добавлением .d. По умолчанию используется каталог users.d, так как значение users_config по умолчанию — users.xml.

Обратите внимание, что файлы конфигурации сначала сливаются с учетом настроек, и только после этого обрабатываются директивы 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.

Форматы YAML и XML имеют некоторые различия в контексте конфигураций ClickHouse. Ниже приведены рекомендации по написанию конфигурации в формате 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>

Описанный выше синтаксис не позволяет представить в YAML текстовые узлы XML с атрибутами XML. Этот особый случай можно описать с помощью ключа атрибута #text:

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

Соответствующий XML:

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

​

Подробности реализации

Для каждого конфигурационного файла сервер также при запуске генерирует файлы file-preprocessed.xml. Эти файлы содержат все выполненные подстановки и переопределения и предназначены только для ознакомления. Если в конфигурационных файлах использовались подстановки из ZooKeeper, но при запуске сервера ZooKeeper недоступен, сервер загружает конфигурацию из предварительно обработанного файла.

Сервер отслеживает изменения в конфигурационных файлах, а также в файлах и узлах ZooKeeper, которые использовались при выполнении подстановок и переопределений, и на лету перезагружает настройки для пользователей и кластеров. Это означает, что вы можете изменять кластер, пользователей и их настройки без перезапуска сервера.