> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

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

  Подробнее см. в разделе ["Настройка параметров"](/docs/ru/products/cloud/reference/settings)
</Note>

Сервер 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:` указывать необязательно; если он отсутствует, парсер добавляет его автоматически.

<div id="merging">
  ## Слияние конфигурации
</div>

Два файла конфигурации (обычно основной файл конфигурации и другой файл конфигурации из `config.d/`) объединяются следующим образом:

* Если узел (то есть путь, ведущий к элементу) присутствует в обоих файлах и не имеет атрибутов `replace` или `remove`, он включается в итоговый файл конфигурации, а дочерние элементы из обоих узлов включаются и рекурсивно объединяются.
* Если один из двух узлов содержит атрибут `replace`, он включается в итоговый файл конфигурации, но включаются только дочерние элементы из узла с атрибутом `replace`.
* Если один из двух узлов содержит атрибут `remove`, узел не включается в итоговый файл конфигурации (если он уже существует, он удаляется).

Например, даны два файла конфигурации:

```xml title="config.xml" theme={null}
<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>
```

и

```xml title="config.d/other_config.xml" theme={null}
<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>
```

Итоговый объединённый конфигурационный файл будет:

```xml theme={null}
<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>
```

<div id="from_env_zk">
  ### Подстановка с использованием переменных окружения и узлов ZooKeeper
</div>

Чтобы указать, что значение элемента должно подставляться из переменной окружения, можно использовать атрибут `from_env`.

Например, при переменной окружения `$MAX_QUERY_SIZE = 150000`:

```xml theme={null}
<clickhouse>
    <profiles>
        <default>
            <max_query_size from_env="MAX_QUERY_SIZE"/>
        </default>
    </profiles>
</clickhouse>
```

В результате получится следующая конфигурация:

```xml theme={null}
<clickhouse>
    <profiles>
        <default>
            <max_query_size>150000</max_query_size>
        </default>
    </profiles>
</clickhouse>
```

То же самое можно сделать с помощью `from_zk` (узла ZooKeeper):

```xml theme={null}
<clickhouse>
    <postgresql_port from_zk="/zk_configs/postgresql_port"/>
</clickhouse>
```

```shell theme={null}
# clickhouse-keeper-client
/ :) touch /zk_configs
/ :) create /zk_configs/postgresql_port "9005"
/ :) get /zk_configs/postgresql_port
9005
```

В результате получаем следующую конфигурацию:

```xml theme={null}
<clickhouse>
    <postgresql_port>9005</postgresql_port>
</clickhouse>
```

<div id="default-values">
  #### Значения по умолчанию
</div>

Элемент с атрибутами `from_env` или `from_zk` также может иметь атрибут `replace="1"` (последний должен располагаться перед `from_env`/`from_zk`).
В этом случае для элемента можно задать значение по умолчанию.
Элемент принимает значение переменной окружения или узла ZooKeeper, если оно задано; в противном случае используется значение по умолчанию.

Ниже повторяется предыдущий пример, но при условии, что `MAX_QUERY_SIZE` не задан:

```xml theme={null}
<clickhouse>
    <profiles>
        <default>
            <max_query_size replace="1" from_env="MAX_QUERY_SIZE">150000</max_query_size>
        </default>
    </profiles>
</clickhouse>
```

В результате получится конфигурация:

```xml theme={null}
<clickhouse>
    <profiles>
        <default>
            <max_query_size>150000</max_query_size>
        </default>
    </profiles>
</clickhouse>
```

<div id="substitution-with-file-content">
  ## Подстановка содержимого файла
</div>

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

* *Подстановка значений*: Если у элемента есть атрибут `incl`, его значение будет заменено содержимым указанного файла. По умолчанию путь к файлу с подстановками — `/etc/metrika.xml`. Его можно изменить в элементе [`include_from`](/docs/ru/reference/settings/server-settings/settings#include_from) в конфигурации сервера. Значения для подстановки задаются в элементах `/clickhouse/substitution_name` в этом файле. Если подстановка, указанная в `incl`, не существует, об этом будет сделана запись в журнале. Чтобы ClickHouse не писал в журнал об отсутствующих подстановках, укажите атрибут `optional="true"` (например, для настроек [macros](/docs/ru/reference/settings/server-settings/settings#macros)).
* *Подстановка элементов*: Если вы хотите заменить подстановкой весь элемент целиком, используйте `include` в качестве имени элемента. Имя элемента `include` можно использовать вместе с атрибутом `from_zk = "/path/to/node"`. В этом случае значение элемента заменяется содержимым узла ZooKeeper по пути `/path/to/node`. Это также работает, если вы храните в узле ZooKeeper всё XML-поддерево: оно будет полностью вставлено в исходный элемент.

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

```xml theme={null}
<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">`. В этом случае существующая конфигурация будет объединена с содержимым подстановки, а существующие параметры конфигурации будут заменены значениями из подстановки.

<div id="encryption">
  ## Шифрование и скрытие конфигурации
</div>

Вы можете использовать симметричное шифрование, чтобы зашифровать элемент конфигурации, например пароль в открытом виде или приватный ключ.
Для этого сначала настройте [кодек шифрования](/docs/ru/reference/statements/create/table#encryption-codecs), а затем добавьте к элементу, который нужно зашифровать, атрибут `encrypted_by` со значением — именем кодека шифрования.

В отличие от атрибутов `from_zk`, `from_env` и `incl`, а также элемента `include`, в предварительно обработанном файле подстановка (то есть расшифровка зашифрованного значения) не выполняется.
Расшифровка происходит только во время выполнения в процессе сервера.

Например:

```xml theme={null}
<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_env_zk) и [`from_zk`](#from_env_zk) также можно использовать для `encryption_codecs`:

```xml theme={null}
<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>
```

```xml theme={null}
<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` приведён ниже:

```xml theme={null}
<clickhouse>

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

</clickhouse>
```

Ниже приведён пример `users.xml`:

```xml theme={null}
<clickhouse>

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

</clickhouse>
```

Чтобы зашифровать значение, можно использовать программу (пример) `encrypt_decrypt`:

```bash theme={null}
./encrypt_decrypt /etc/clickhouse-server/config.xml -e AES_128_GCM_SIV abcd
```

```text theme={null}
961F000000040000000000EEDDEF4F453CFE6457C4234BD7C09258BD651D85
```

Даже при использовании зашифрованных элементов конфигурации они всё равно отображаются в предварительно обработанном конфигурационном файле.
Если для вашего развертывания ClickHouse это проблема, есть два варианта: либо установить права доступа к предварительно обработанному файлу на 600, либо использовать атрибут `hide_in_preprocessed`.

Например:

```xml theme={null}
<clickhouse>

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

</clickhouse>
```

<div id="user-settings">
  ## Пользовательские настройки
</div>

В файле `config.xml` можно указать отдельную конфигурацию с пользовательскими настройками, профилями и квотами. Относительный путь к этой конфигурации задается в элементе `users_config`. По умолчанию используется `users.xml`. Если `users_config` не указан, пользовательские настройки, профили и квоты задаются прямо в `config.xml`.

Пользовательскую конфигурацию можно разделить на отдельные файлы, аналогично `config.xml` и `config.d/`.
Имя каталога определяется как значение параметра `users_config` без суффикса `.xml` с добавлением `.d`.
По умолчанию используется каталог `users.d`, так как значение `users_config` по умолчанию — `users.xml`.

Обратите внимание, что файлы конфигурации сначала [сливаются](#merging) с учетом настроек, и только после этого обрабатываются директивы include.

<div id="example">
  ## Пример XML
</div>

Например, можно создать отдельный файл конфигурации для каждого пользователя:

```bash theme={null}
$ cat /etc/clickhouse-server/users.d/alice.xml
```

```xml theme={null}
<clickhouse>
    <users>
      <alice>
          <profile>analytics</profile>
            <networks>
                  <ip>::/0</ip>
            </networks>
          <password_sha256_hex>...</password_sha256_hex>
          <quota>analytics</quota>
      </alice>
    </users>
</clickhouse>
```

<div id="example-1">
  ## Примеры YAML
</div>

Здесь приведена конфигурация по умолчанию в формате YAML: [`config.yaml.example`](https://github.com/ClickHouse/ClickHouse/blob/master/programs/server/config.yaml.example).

Форматы YAML и XML имеют некоторые различия в контексте конфигураций ClickHouse.
Ниже приведены рекомендации по написанию конфигурации в формате YAML.

XML-тег с текстовым значением в YAML представляется как пара ключ-значение

```yaml theme={null}
key: value
```

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

```xml theme={null}
<key>value</key>
```

Вложенный XML-узел задаётся в виде YAML-словаря:

```yaml theme={null}
map_key:
  key1: val1
  key2: val2
  key3: val3
```

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

```xml theme={null}
<map_key>
    <key1>val1</key1>
    <key2>val2</key2>
    <key3>val3</key3>
</map_key>
```

Чтобы создать один и тот же тег XML несколько раз, используйте последовательность YAML:

```yaml theme={null}
seq_key:
  - val1
  - val2
  - key1: val3
  - map:
      key2: val4
      key3: val5
```

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

```xml theme={null}
<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, поэтому его нужно заключать в двойные кавычки:

```yaml theme={null}
map:
  "@attr1": value1
  "@attr2": value2
  key: 123
```

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

```xml theme={null}
<map attr1="value1" attr2="value2">
    <key>123</key>
</map>
```

Атрибуты также можно использовать в YAML-последовательности:

```yaml theme={null}
seq:
  - "@attr1": value1
  - "@attr2": value2
  - 123
  - abc
```

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

```xml theme={null}
<seq attr1="value1" attr2="value2">123</seq>
<seq attr1="value1" attr2="value2">abc</seq>
```

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

```yaml theme={null}
map_key:
  "@attr1": value1
  "#text": value2
```

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

```xml theme={null}
<map_key attr1="value1">value2</map>
```

<div id="implementation-details">
  ## Подробности реализации
</div>

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

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