Файлы конфигурации

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

Сервер ClickHouse можно настраивать с помощью файлов конфигурации в формате XML или YAML. В большинстве вариантов установки сервер ClickHouse использует /etc/clickhouse-server/config.xml в качестве файла конфигурации по умолчанию, но расположение файла конфигурации также можно указать вручную при запуске сервера с помощью параметра командной строки --config-file или -C. Если ни один из этих параметров не указан, сервер ищет в текущем рабочем каталоге файлы config.xml, config.yaml и config.yml (именно в этом порядке) и использует первый найденный. Если ни одного из них нет, сервер запускается с конфигурацией, встроенной в бинарный файл. Файл, указанный с помощью --config-file, используется как есть: если его нет, сервер сообщает об ошибке, а не ищет файл с другим расширением. clickhouse-keeper действует по тем же правилам, но с файлами keeper_config.xml, keeper_config.yaml и keeper_config.yml. Дополнительные файлы конфигурации можно размещать в каталоге 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 по-разному интерпретируют подставляемое значение:

Прямое значение, подставляемое через from_env, воспринимается как буквальный текст. Специальные символы XML, такие как &, < и >, экранируются автоматически, поэтому переменная окружения может содержать любое значение, представимое в XML, например a&b<c>d, и это не нарушит конфигурацию (см. ниже примечание о недопустимых в XML управляющих символах). Прямое значение никогда не интерпретируется как XML, даже если оно выглядит как фрагмент XML: <a>1</a> подставляется как буквальный текст <a>1</a>. Это относится и к случаю, когда прямой атрибут указан на обычном элементе-контейнере, например <profiles from_env="…"/>: существующую подстановку поддерева XML необходимо перевести на форму <profiles><include from_env="…"/></profiles>. Исключение составляет <include from_env="…"/>, который ради обратной совместимости ведёт себя иначе: он разбирает переменную окружения как фрагмент XML и встраивает его дочерние элементы в родительский элемент.
Интерпретация значения, подставляемого через from_zk, зависит от того, начинается ли оно с <. Значение, начинающееся с <, всегда разбирается как фрагмент XML: именно так поддерево встраивается в любой элемент — как в структурный <include from_zk="…"/>, так и в обычный контейнер, например <profiles from_zk="…"/>. Это поведение сохранено для обратной совместимости, поскольку в более ранних версиях значение from_zk всегда интерпретировалось как XML. Значение, не начинающееся с <, разбирается как поддерево YAML только при явной форме <include from_zk="…" yaml="true"/>; в этом случае некорректный YAML приводит к отклонению конфигурации. Атрибут yaml="true" включает разбор YAML везде, где используется общая форма <include>, в том числе внутри конечного элемента, поэтому не используйте его для буквальных настроек или секретов. Без yaml="true" значение, не начинающееся с <, считается буквальным текстом, в том числе при использовании общей формы замены конечного элемента <password><include from_zk="/secret"/></password>. Благодаря этому сохраняются значения, которые содержат синтаксис YAML или являются некорректным YAML, например abc # rotated или [1. В этой форме байты сохраняются в точности, только если <include> указан встроенно, без окружающих текстовых узлов с пробельными символами; для секретов и конечных настроек, где важна точность до байта, лучше использовать прямую форму <password from_zk="…"/>. На любом другом элементе — будь то подстановка в конечный элемент, например <some_setting from_zk="…"/> или <password from_zk="…"/>, или обычный контейнер, например <profiles from_zk="…"/>, — значение, не начинающееся с <, также сохраняется как буквальный текст с точными исходными байтами (специальные символы XML экранируются автоматически, как и для from_env), поэтому значение вида abc: def остаётся буквальным текстом abc: def, а не превращается во вложенный элемент <abc>def</abc>. Чтобы встроить поддерево в обычный элемент (а не в структурный <include>), передайте его как фрагмент XML (значение, начинающееся с <).

Буквальные значения должны быть допустимым текстом XML 1.0Буквальная подстановка (from_env или значение from_zk для конечного элемента, не начинающееся с <) побайтово сохраняет значение для каждого символа, который XML 1.0 может представить как текст. Управляющие символы, недопустимые в XML 1.0, — 0x00–0x08, 0x0B, 0x0C и 0x0E–0x1F — вообще невозможно передать через XML-конфигурацию (спецификация XML запрещает их даже в виде числовых ссылок на символы, например ), поэтому значение, содержащее такой символ, отклоняется при обработке подстановки. Табуляция (\t), перевод строки (\n) и возврат каретки (\r) допустимы и при записи и обратном чтении сохраняются побайтово.

Поведение после обновления для конечных значений, закодированных XML-сущностямиПредыдущие версии повторно разбирали каждое значение, заданное напрямую через from_env, как XML, поэтому «сырые» символы &, < или > отклонялись как некорректно сформированный XML, и единственным способом встроить такой символ было закодировать его XML-сущностью: переменная окружения со значением a&b декодировалась в a&b, <a>1</a> — в <a>1</a>, а  — в символ возврата каретки. Теперь значение, заданное напрямую через from_env, трактуется как буквальный текст, поэтому те же значения переменных окружения разрешаются в буквальные строки a&b, <a>1</a> и . Таким образом, прежний смысл сохраняют только значения в виде обычного текста: значение переменной окружения, закодированное сущностями для старого способа разбора XML, теперь нужно задавать в «сыром» виде (например, задайте a&b — прежде такое значение отклонялось, а теперь принимается как буквальный текст a&b).Предыдущие версии повторно разбирали каждое конечное значение from_zk как XML, поэтому «сырые» символы &, < или > отклонялись как некорректно сформированный XML, и единственным способом встроить такой символ было закодировать его XML-сущностью: значение, сохранённое как a&b, декодировалось в a&b, <a>1</a> — в <a>1</a>, а  — в символ возврата каретки. Теперь конечное значение, не начинающееся с <, сохраняется байт в байт, поэтому те же узлы разрешаются в буквальные строки a&b, <a>1</a> и . Таким образом, прежний смысл сохраняют только скалярные значения в виде обычного текста: конечное значение, закодированное сущностями для старого способа разбора XML, теперь нужно хранить в «сыром» виде (например, сохраните a&b — прежде такое значение отклонялось, а теперь принимается как буквальный текст a&b).Это же изменение касается простого скалярного значения, подставляемого через встроенный <include from_zk="…"/> внутри конечной настройки или секрета, например <password><include from_zk="/secret"/></password>: здесь скалярное значение тоже сохраняется байт в байт, поэтому /secret = a&b (раньше декодировалось в a&b) теперь разрешается в буквальную строку a&b, и хранить значение нужно в «сыром» виде — a&b. Не добавляйте пробельные символы вокруг такой конструкции, поскольку они становятся частью итогового значения настройки; если важна точная последовательность байтов, используйте прямую форму <password from_zk="…"/>. (Значения from_zk, начинающиеся с <, а также поддеревья YAML, на которые ссылается <include from_zk="…" yaml="true"/>, это изменение не затрагивает — буквально сохраняются только немаркированные значения, не начинающиеся с <.)

Значения по умолчанию

Элемент с атрибутами 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, его значение будет заменено содержимым указанного файла. Путь к файлу с подстановками задаётся элементом include_from в конфигурации сервера; пути по умолчанию нет, поэтому подстановки считываются только при его указании. Значения для подстановки задаются в элементах /clickhouse/substitution_name в этом файле. Если подстановка, указанная в incl, не существует, об этом будет сделана запись в журнале. Чтобы ClickHouse не писал в журнал об отсутствующих подстановках, укажите атрибут optional="true" (например, для настроек macros).
Подстановка элементов: Если вы хотите заменить подстановкой весь элемент целиком, используйте include в качестве имени элемента. Имя элемента include можно использовать вместе с атрибутом from_zk = "/path/to/node". В этом случае значение элемента заменяется содержимым узла ZooKeeper по пути /path/to/node. Это также работает, если вы храните в узле ZooKeeper всё XML-поддерево: оно будет полностью вставлено в исходный элемент.

Изменено в версии 26.8: до этой версии файл /etc/metrika.xml неявно использовался всегда, когда он существовал, даже если include_from не был указан. Если вы используете этот файл, явно укажите его путь в 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/. Имя каталога определяется как значение параметра users_config без суффикса .xml с добавлением .d. По умолчанию используется каталог users.d, так как значение users_config по умолчанию — users.xml. Фрагменты пользовательской конфигурации сливаются в лексикографическом порядке по их полным путям. Для файлов в стандартном каталоге 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. Форматы 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_key>

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

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

Основы

Основные понятия ClickHouse

Рекомендации

Слияние конфигурации

Подстановка с использованием переменных окружения и узлов ZooKeeper

Как интерпретируются значения

Значения по умолчанию

Подстановка содержимого файла

Шифрование и скрытие конфигурации

Пользовательские настройки

Пример XML

Примеры YAML

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

​Слияние конфигурации

​Подстановка с использованием переменных окружения и узлов ZooKeeper

​Как интерпретируются значения

​Значения по умолчанию

​Подстановка содержимого файла

​Шифрование и скрытие конфигурации

​Пользовательские настройки

​Пример XML

​Примеры YAML

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

Слияние конфигурации

Подстановка с использованием переменных окружения и узлов ZooKeeper

Как интерпретируются значения

Значения по умолчанию

Подстановка содержимого файла

Шифрование и скрытие конфигурации

Пользовательские настройки

Пример XML

Примеры YAML

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