Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Arquivos de configuração

View as MarkdownEdit this pageReport an issueSet up docs MCP

O servidor ClickHouse pode ser configurado com arquivos de configuração em sintaxe XML ou YAML. Na maioria dos tipos de instalação, o servidor ClickHouse usa /etc/clickhouse-server/config.xml como arquivo de configuração padrão, mas também é possível especificar manualmente o local do arquivo de configuração na inicialização do servidor usando a opção de linha de comando --config-file ou -C. Arquivos de configuração adicionais podem ser colocados no diretório config.d/, relativo ao arquivo de configuração principal, por exemplo no diretório /etc/clickhouse-server/config.d/. Os arquivos desse diretório e a configuração principal são mesclados em uma etapa de pré-processamento antes de a configuração ser aplicada no servidor ClickHouse. Os fragmentos de configuração são mesclados em ordem lexicográfica por seus caminhos completos. Para arquivos no diretório padrão config.d/, isso equivale a ordená-los pelo nome do arquivo. O diretório legado conf.d/ também é mesclado; como conf.d é ordenado antes de config.d, todos os seus fragmentos são processados primeiro quando ambos os diretórios existem. Para simplificar atualizações e melhorar a modularização, é uma prática recomendada manter o arquivo padrão config.xml sem alterações e colocar personalizações adicionais em config.d/. A configuração do ClickHouse Keeper fica em /etc/clickhouse-keeper/keeper_config.xml. Da mesma forma, arquivos de configuração adicionais do Keeper precisam ser colocados em /etc/clickhouse-keeper/keeper_config.d/.

É possível misturar arquivos de configuração XML e YAML; por exemplo, você pode ter um arquivo de configuração principal config.xml e arquivos de configuração adicionais config.d/network.xml, config.d/timezone.yaml e config.d/keeper.yaml. Não há suporte para misturar XML e YAML em um único arquivo de configuração. Arquivos de configuração XML devem usar <clickhouse>...</clickhouse> como tag de nível superior. Em arquivos de configuração YAML, clickhouse: é opcional; se estiver ausente, o parser o insere automaticamente.

Mesclagem de configuração

Dois arquivos de configuração (geralmente o arquivo de configuração principal e outro arquivo de configuração em config.d/) são mesclados da seguinte forma:

  • Se um nó (ou seja, um caminho que leva a um elemento) estiver presente em ambos os arquivos e não tiver os atributos replace ou remove, ele será incluído no arquivo de configuração mesclado, e os filhos de ambos os nós serão incluídos e mesclados recursivamente.
  • Se um dos dois nós contiver o atributo replace, ele será incluído no arquivo de configuração mesclado, mas apenas os filhos do nó com o atributo replace serão incluídos.
  • Se um dos dois nós contiver o atributo remove, o nó não será incluído no arquivo de configuração mesclado (se já existir, será removido).

Por exemplo, considerando dois arquivos de configuração:

config.xmlxml
<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>

e

config.d/other_config.xmlxml
<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>

O arquivo de configuração mesclado resultante será:

<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>

Substituição por variáveis de ambiente e nós do ZooKeeper

Para especificar que o valor de um elemento deve ser substituído pelo valor de uma variável de ambiente, você pode usar o atributo from_env.

Por exemplo, com a variável de ambiente $MAX_QUERY_SIZE = 150000:

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

A configuração resultante será:

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

Também é possível usar from_zk (nó do 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

Resultando na configuração a seguir:

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

Valores padrão

Um elemento com os atributos from_env ou from_zk também pode ter o atributo replace="1" (este último deve aparecer antes de from_env/from_zk). Nesse caso, o elemento pode definir um valor padrão. O elemento assume o valor da variável de ambiente ou do nó do ZooKeeper, se estiver definido; caso contrário, assume o valor padrão.

O exemplo anterior é repetido, mas supondo que MAX_QUERY_SIZE não esteja definido:

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

O resultado é a configuração:

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

Substituição com conteúdo de arquivo

Também é possível substituir partes da configuração pelo conteúdo de arquivos. Isso pode ser feito de duas formas:

  • Substituição de valores: se um elemento tiver o atributo incl, seu valor será substituído pelo conteúdo do arquivo referenciado. O caminho para o arquivo com substituições é definido pelo elemento include_from da configuração do servidor; não há um caminho padrão, portanto as substituições são lidas somente quando ele é especificado. Os valores de substituição são especificados em elementos /clickhouse/substitution_name nesse arquivo. Se uma substituição especificada em incl não existir, isso será registrado no log. Para impedir que o ClickHouse registre substituições ausentes, especifique o atributo optional="true" (por exemplo, para configurações de macros).
  • Substituição de elementos: se você quiser substituir o elemento inteiro por uma substituição, use include como nome do elemento. O nome de elemento include pode ser combinado com o atributo from_zk = "/path/to/node". Nesse caso, o valor do elemento é substituído pelo conteúdo do nó do ZooKeeper em /path/to/node. Isso também funciona quando você armazena uma subárvore XML inteira como um nó do ZooKeeper; ela será inserida por completo no elemento de origem.

Um exemplo disso é mostrado abaixo:

<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>

Se você quiser mesclar o conteúdo da substituição com a configuração existente, em vez de apenas anexá-lo, pode usar o atributo merge="true". Por exemplo: <include from_zk="/some_path" merge="true">. Nesse caso, a configuração existente será mesclada com o conteúdo da substituição, e as configurações existentes serão substituídas pelos valores da substituição.

Criptografando e ocultando a configuração

Você pode usar criptografia simétrica para criptografar um elemento de configuração, por exemplo, uma senha em texto simples ou uma chave privada. Para isso, primeiro configure o codec de criptografia e, em seguida, adicione o atributo encrypted_by, com o nome do codec de criptografia como valor, ao elemento que será criptografado.

Diferentemente dos atributos from_zk, from_env e incl, ou do elemento include, nenhuma substituição (ou seja, a descriptografia do valor criptografado) é realizada no arquivo pré-processado. A descriptografia ocorre apenas em tempo de execução, no processo do servidor.

Por exemplo:

<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>

Os atributos from_env e from_zk também podem ser aplicados a 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>

Chaves de criptografia e valores criptografados podem ser definidos em qualquer um dos arquivos de configuração.

Um exemplo de config.xml é o seguinte:

<clickhouse>

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

</clickhouse>

Um exemplo de users.xml é o seguinte:

<clickhouse>

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

</clickhouse>

Para criptografar um valor, você pode usar o programa de exemplo encrypt_decrypt:

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

Mesmo com elementos de configuração criptografados, eles ainda aparecem no arquivo de configuração pré-processado. Se isso for um problema para a sua implantação do ClickHouse, há duas alternativas: definir as permissões do arquivo pré-processado como 600 ou usar o atributo hide_in_preprocessed.

Por exemplo:

<clickhouse>

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

</clickhouse>

Configurações de usuário

O arquivo config.xml pode especificar uma configuração separada com configurações de usuário, perfis e cotas. O caminho relativo para essa configuração é definido no elemento users_config. Por padrão, ele é users.xml. Se users_config for omitido, as configurações de usuário, os perfis e as cotas serão especificados diretamente em config.xml.

A configuração de usuário pode ser dividida em arquivos separados, assim como em config.xml e config.d/. O nome do diretório é definido pela configuração users_config, sem o sufixo .xml, concatenado com .d. O diretório users.d é usado por padrão, já que users_config tem como padrão users.xml. Os fragmentos de configuração de usuário são mesclados em ordem lexicográfica por seus caminhos completos. Para arquivos no diretório padrão users.d/, isso equivale a ordená-los pelo nome do arquivo. O diretório legado conf.d/ também é mesclado; como conf.d é ordenado antes de users.d, todos os seus fragmentos são processados primeiro quando ambos os diretórios existem.

Observe que os arquivos de configuração primeiro são mesclados, levando em conta as configurações, e as inclusões são processadas depois disso.

Exemplo em XML

Por exemplo, você pode ter um arquivo de configuração separado para cada usuário, assim:

$ 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>

Exemplos de YAML

Aqui você pode ver a configuração padrão escrita em YAML: config.yaml.example.

Há algumas diferenças entre os formatos YAML e XML no que diz respeito às configurações do ClickHouse. As dicas para escrever configurações no formato YAML são apresentadas abaixo.

Uma tag XML com um valor de texto é representada por um par chave-valor em YAML

key: value

XML correspondente:

<key>value</key>

Um nó XML aninhado é representado como um mapa YAML:

map_key:
  key1: val1
  key2: val2
  key3: val3

XML correspondente:

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

Para criar a mesma tag XML várias vezes, use uma sequência YAML:

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

XML correspondente:

<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>

Para fornecer um atributo XML, você pode usar uma chave de atributo com o prefixo @. Observe que @ é reservado pelo padrão YAML e, por isso, deve ser colocado entre aspas duplas:

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

XML correspondente:

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

Também é possível usar atributos em uma sequência YAML:

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

XML correspondente:

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

A sintaxe mencionada anteriormente não permite representar, em YAML, nós de texto XML com atributos XML. Esse caso especial pode ser tratado usando uma chave de atributo #text:

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

XML correspondente:

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

Detalhes de implementação

Para cada arquivo de configuração, o servidor também gera arquivos file-preprocessed.xml ao iniciar. Esses arquivos contêm todas as substituições e sobrescritas já resolvidas e se destinam apenas à consulta. Se substituições do ZooKeeper tiverem sido usadas nos arquivos de configuração, mas o ZooKeeper não estiver disponível na inicialização do servidor, o servidor carregará a configuração a partir do arquivo pré-processado.

O servidor monitora alterações nos arquivos de configuração, bem como nos arquivos e nós do ZooKeeper usados para realizar substituições e sobrescritas, e recarrega dinamicamente as configurações de usuários e clusters. Isso significa que você pode modificar o cluster, os usuários e suas configurações sem reiniciar o servidor.

Navigation