Skip to main content
이 설정은 ClickHouse 서버를 구성하며 ClickHouse 소스에서 자동으로 생성됩니다.

abort_on_logical_error

LOGICAL_ERROR 예외가 발생하면 server를 크래시합니다. 전문가만 사용하십시오.

allowed_disks_for_table_engines

Iceberg에서 사용할 수 있도록 허용된 디스크 목록

auth_use_forwarded_address

프록시를 통해 연결된 클라이언트의 인증에 원래 주소를 사용합니다.
  • 기본값: false
전달된 주소는 쉽게 위조될 수 있으므로 이 설정은 특히 주의해서 사용해야 합니다. 이러한 인증을 허용하는 서버에는 직접 접근하지 말고, 신뢰할 수 있는 프록시를 통해서만 접근해야 합니다.

bcrypt_workfactor

Bcrypt 알고리즘을 사용하는 bcrypt_password 인증 유형에 대한 작업 계수입니다. 작업 계수는 해시를 계산하고 비밀번호를 검증하는 데 필요한 연산량과 시간을 결정합니다.
  • 기본값: 12
인증 요청이 빈번한 애플리케이션에서는 작업 계수가 높을수록 bcrypt의 계산 오버헤드가 커지므로 대체 인증 메서드를 고려하십시오.

blob_storage_log

blob_storage_log 시스템 테이블의 설정입니다. 다음 설정은 하위 태그로 구성할 수 있습니다: 또한 다음 서버 수준 설정은 모든 시스템 로그 테이블의 기본 플러시 정책을 제어합니다:
예시:

builtin_dictionaries_reload_interval

내장 딕셔너리를 다시 로드하기 전까지의 인터벌이며, 단위는 초입니다. ClickHouse는 x초마다 내장 딕셔너리를 다시 로드합니다. 따라서 서버를 다시 시작하지 않고도 딕셔너리를 “실시간으로” 편집할 수 있습니다. 예시

cache_size_to_ram_max_ratio

캐시 크기의 RAM 대비 최대 비율을 설정합니다. 메모리가 적은 시스템에서 캐시 크기를 줄일 수 있습니다.

cannot_allocate_thread_fault_injection_probability

테스트용입니다.

cgroups_memory_usage_observer_wait_time

cgroups의 해당 임계값에 맞춰 서버의 최대 허용 메모리 사용량을 조정하는 시간 간격(초)입니다. cgroup observer를 비활성화하려면 이 값을 0으로 설정하십시오.

압축

MergeTree-엔진 테이블의 데이터 압축 설정입니다.
ClickHouse를 막 사용하기 시작했다면 이 값을 변경하지 않는 것이 좋습니다.
구성 템플릿:
<case> 필드:
  • min_part_size – 데이터 파트(data part)의 최소 크기입니다.
  • min_part_size_ratio – 데이터 파트 크기와 테이블 크기의 비율입니다.
  • method – 압축 방식입니다. 허용되는 값: lz4, lz4hc, zstd,deflate_qpl.
  • level – 압축 수준입니다. 코덱을 참조하십시오.
여러 개의 <case> 섹션을 구성할 수 있습니다.
조건 충족 시 동작:
  • 데이터 파트가 조건 Set과 일치하면 ClickHouse는 지정된 압축 방식을 사용합니다.
  • 데이터 파트가 여러 조건 Set과 일치하면 ClickHouse는 가장 마지막에 일치한 조건 Set을 사용합니다(<case> 섹션은 순서대로 검사되며, 일치하는 항목이 나올 때마다 이전 선택을 재정의합니다).
데이터 파트에 대해 충족되는 조건이 없으면 ClickHouse는 크기를 고려한 기본 내장 설정을 사용합니다. 즉, 100MB 미만이면 LZ4, 그 이상이면 ZSTD(3)를 사용합니다. 위의 min_part_size 조건과 마찬가지로, 여기서의 크기는 데이터가 기록되기 전 코덱을 선택해야 하는 시점에 알려진 크기입니다. 즉, 새로 삽입된 파트의 경우 0이며, 머지나 mutation의 경우 소스 파트들의 크기입니다. 따라서 TTL DELETE나 축약 머지처럼 입력보다 결과가 작아지는 재작성은 입력 크기를 기준으로 분류되며, 임계값 미만인데도 ZSTD(3)로 압축된 파트가 만들어질 수 있습니다.
예시

구성 파일

서버 구성 파일을 가리킵니다.

config_reload_interval_ms

ClickHouse가 구성을 다시 로드하고 새로운 변경 사항이 있는지 확인하는 주기입니다

core_dump

코어 덤프 파일 크기의 소프트 리밋을 설정합니다.
하드 리밋은 시스템 도구로 설정합니다
예시

crash_log

crash_log 시스템 테이블 동작에 대한 설정입니다. 다음 설정은 하위 태그로 설정할 수 있습니다: 기본 서버 구성 파일 config.xml에는 다음 설정 섹션이 포함되어 있습니다:

create_union_system_log_tables

시스템 로그 테이블과 함께 all_... 테이블을 생성하도록 요청합니다(system.query_log에는 system.all_query_log, system.text_log에는 system.all_text_log 등). 이러한 테이블은 해당 로그 테이블과 그 교체된 버전(query_log_0, query_log_1, …), 그리고/또는 클러스터의 모든 레플리카에 있는 동일한 테이블을 결합한 것이며, clusterAllReplicas(default, merge(system, '^query_log')) 같은 구문을 기억하지 않아도 한 번에 모두 쿼리할 수 있습니다. 이 섹션은 선택 사항입니다. 포함할 경우 다음 설정 중 하나 이상을 지정해야 합니다. 두 설정을 모두 지정하면 이 테이블은 클러스터의 모든 레플리카에 있는 교체된 테이블을 결합한 것입니다. 이 옵션은 모든 시스템 로그 테이블에 적용되며, 시스템 로그별로 서로 다른 구성을 지정할 수는 없습니다. 테이블은 각 로그가 처음 플러시될 때 시스템 로그 테이블과 동일한 데이터베이스에 생성되며, 로그 테이블의 구조가 변경되면(교체 시) 자동으로 다시 생성됩니다. 상태를 저장하지 않으므로 언제든지 안전하게 삭제할 수 있습니다. 생성은 Atomic, Replicated, Shared 데이터베이스 엔진에서만 지원됩니다.
cluster 설정을 사용하면 테이블 정의에서 클러스터를 참조하므로 테이블을 로드하려면 클러스터가 존재해야 합니다. 구성에서 클러스터를 제거하는 경우 all_... 테이블도 삭제하십시오(다음 플러시 시 새 구성에 따라 다시 생성됩니다).
예시

database_atomic_delay_before_drop_table_sec

삭제된 테이블을 UNDROP SQL 문으로 복원할 수 있는 유예 시간입니다. DROP TABLE이 SYNC 수정자와 함께 실행된 경우에는 이 설정이 무시됩니다. 이 설정의 기본값은 480(8분)입니다.

dead_letter_queue

‘dead_letter_queue’ 시스템 테이블의 설정입니다. 다음 설정은 하위 태그로 구성할 수 있습니다: 또한 다음 서버 수준 설정은 모든 시스템 로그 테이블의 기본 플러시 정책을 제어합니다:
기본 설정은 다음과 같습니다:

dictionary_background_reconnect_interval

background_reconnect가 활성화된 MySQL 및 Postgres 딕셔너리에서 연결 실패 시 재연결을 시도하는 간격(밀리초)입니다.

disk_transaction_wait_for_blob_removal

디스크별 wait_for_blob_removal 설정의 기본값입니다. 활성화되면 서버는 백그라운드 blob 제거가 완료될 때까지 기다린 후 작업을 확인합니다.

display_secrets_in_show_and_select

테이블, 데이터베이스, 테이블 함수 및 딕셔너리에 대한 SHOW 및 SELECT 쿼리에서 시크릿 표시를 활성화하거나 비활성화합니다. 시크릿을 보려면 사용자는 format_display_secrets_in_show_and_select 포맷 설정 이 활성화되어 있어야 하며, displaySecretsInShowAndSelect 권한도 있어야 합니다. 가능한 값:
  • 0 — 비활성화됨.
  • 1 — 활성화됨.

dns_max_consecutive_failures

호스트명의 DNS cache를 업데이트하는 작업이 이 횟수만큼 연속으로 실패하면, 이후 추가 업데이트 시도를 중지합니다. 기존 정보는 DNS cache에 계속 유지됩니다. 0은 무제한을 의미합니다. 관련 항목

dynamic_user_defined_executable_functions_path

드라이버가 동적으로 생성한 실행형 UDF의 설정 파일을 저장하는 데 사용되는 디렉터리입니다(CREATE FUNCTION ... ENGINE = DriverName(...) 참조). 서버를 다시 시작하면 이 디렉터리에서 설정 파일을 스캔하여 드라이버를 다시 호출하지 않고 해당 UDF를 로드합니다. 예시

암호화

암호화 코덱에서 사용할 키를 가져오는 명령을 설정합니다. 키(또는 여러 개의 키)는 환경 변수에 저장하거나 설정 파일에 지정해야 합니다. 키는 16바이트 길이의 16진수 값 또는 문자열일 수 있습니다. 예시 구성에서 불러오기:
설정 파일에 키를 저장하는 것은 권장되지 않습니다. 보안상 안전하지 않습니다. 키를 안전한 디스크의 별도 설정 파일로 옮기고, 해당 설정 파일을 가리키는 심볼릭 링크를 config.d/ 폴더에 둘 수 있습니다.
키가 16진수 형식일 때 구성에서 로드하는 방법:
환경 변수에서 키를 불러옵니다:
여기서 current_key_id는 암호화에 사용할 현재 키를 지정하며, 지정된 모든 키는 복호화에 사용할 수 있습니다. 이 각각의 방법은 여러 키에 적용할 수 있습니다:
여기서 current_key_id는 암호화에 사용되는 현재 키를 나타냅니다. 또한 사용자는 반드시 12바이트 길이의 nonce를 추가할 수 있습니다(기본적으로 암호화 및 복호화 과정에서는 0바이트로만 이루어진 nonce를 사용합니다):
또는 16진수 형식으로 설정할 수 있습니다:
위에서 설명한 모든 내용은 aes_256_gcm_siv에도 적용됩니다(단, 키는 32바이트여야 합니다).

enforce_keeper_component_tracking

활성화되면 모든 ZooKeeper 요청에는 Coordination::setCurrentComponent를 통해 컴포넌트 이름이 설정되어 있어야 합니다. 컴포넌트가 없으면 LOGICAL_ERROR 예외가 발생합니다.

error_log

기본적으로 비활성화되어 있습니다. 활성화 오류 이력 수집 system.error_log을 수동으로 활성화하려면, 다음 내용으로 /etc/clickhouse-server/config.d/error_log.xml 파일을 생성하십시오:
비활성화 error_log 설정을 비활성화하려면 다음 내용으로 /etc/clickhouse-server/config.d/disable_error_log.xml 파일을 생성하십시오:
다음 설정은 하위 태그로 구성할 수 있습니다: 또한 다음 서버 수준 설정은 모든 시스템 로그 테이블의 기본 플러시 정책을 제어합니다:

filesystem_caches_path

이 설정은 캐시의 경로를 지정합니다. 예시

google_protos_path

Protobuf 타입의 proto 파일이 포함된 디렉터리를 지정합니다. 예시

handshake_timeout_milliseconds

전체 TCP handshake 단계(Hello + Addendum)에 적용되는 밀리초 단위의 wall-clock timeout입니다. 인증되지 않은 connection이 thread를 점유한 채 유지될 수 있는 시간을 제한합니다. 비활성화하려면 0으로 설정하십시오.

hdfs.libhdfs3_conf

libhdfs3가 구성의 올바른 위치를 가리키도록 지정합니다.

hsts_max_age

HSTS의 만료 기간(초)입니다.
값이 0이면 ClickHouse에서 HSTS를 비활성화합니다. 양수를 설정하면 HSTS가 활성화되며, max-age는 설정한 값으로 지정됩니다.
예시

iceberg_background_schedule_pool_size

원격 Iceberg catalog에서 최신 metadata를 비동기적으로 가져오는 데 사용되는 스레드 풀의 크기입니다. 이 풀은 활성화된 모든 테이블이 공유합니다.

iceberg_manifest_decode_thread_pool_queue_size

Iceberg 데이터 manifest 파일을 디코딩하는 스레드 풀에 예약할 수 있는 최대 작업(jobs) 수입니다.

ignore_empty_sql_security_in_create_view_query

true이면 DEFINER와 SQL SECURITY를 모두 지정하지 않은 CREATE VIEW 또는 CREATE MATERIALIZED VIEW 쿼리는 작성된 그대로 저장되며, 뷰의 SQL 보안 유형은 비어 있게 됩니다. DEFINER만 지정해도 SQL SECURITY DEFINER를 지정한 것으로 간주되므로, 이러한 쿼리는 이 설정의 영향을 받지 않습니다. SQL 보안 유형이 비어 있는 일반 뷰는 호출자의 권한으로 실행됩니다. 대상 테이블을 명시적으로 지정한 materialized view에서는 대상 테이블에 대한 액세스 검사가 생략됩니다. 즉, 원본 테이블에 삽입할 때 대상 테이블에 대한 INSERT privilege가 필요하지 않으며, 뷰에서 읽을 때도 대상 테이블에 대한 SELECT privilege가 필요하지 않습니다. false이면 default_normal_view_sql_security, default_materialized_view_sql_security, default_view_definer 설정의 기본값이 생성 시 뷰 정의에 기록됩니다. 이러한 설정의 기본값을 사용하면, 어떤 절도 지정하지 않고 생성한 materialized view는 생성한 사용자를 정의자로 기록하고 해당 사용자의 권한으로 실행됩니다. 갱신 가능 구체화 뷰에는 이 설정과 관계없이 항상 기본값이 적용됩니다.
이 설정을 변경해도 이후에 생성되는 뷰에만 영향을 미치며, 기존 뷰의 저장된 정의는 변경되지 않습니다.

include_from

치환이 정의된 파일의 경로입니다. XML 및 YAML 포맷을 모두 지원합니다. 자세한 내용은 설정 파일 섹션을 참조하십시오. 기본값은 비어 있으며, 치환 파일을 사용하지 않음을 의미합니다. 버전 26.8 이전에는 /etc/metrika.xml 파일이 존재하면 암시적으로 사용되었습니다. 이 파일에 의존하는 경우 경로를 명시적으로 지정하십시오. 기본 서버 구성과 별도로 로드되는 설정 파일, 즉 사용자 구성(예: 기본 파일에 포함되지 않은 users.xml) 및 XML 딕셔너리 구성은 서버 구성이 아닌 자체 내용에서 include_from 요소를 읽습니다. 치환을 사용하는 각 파일에는 자체 include_from 요소가 필요합니다. 예시

insert_deduplication_version

지원 중단된 마이그레이션 보호 설정입니다. ClickHouse 26.7 이상 버전은 통합 삽입 중복 제거 해시(new_unified_hash)만 지원하며, 이 설정이 다른 값(예: old_separate_hashes 또는 compatible_double_hashes)으로 지정되어 있으면 서버가 시작되지 않습니다. 업그레이드하기 전에 이전 버전에서 compatible_double_hashes를 실행해(레거시 해시와 통합 해시를 모두 기록함) 중복 제거 마이그레이션을 완료하십시오. 복제된 테이블(Replicated Table)의 경우 최소 replicated_deduplication_window_seconds 동안 실행하십시오(기본값은 1시간). 기본 윈도우는 해당 기간 동안 모든 삽입의 통합 해시를 유지하므로, 일반적으로 삽입 재시도 루프를 커버하기에 충분한 것으로 간주됩니다. non_replicated_deduplication_window > 0인 비복제 테이블의 경우 윈도우는 시간 기준이 아니라 개수 기준이므로, 업그레이드하기 전에 최소 그 횟수만큼 삽입이 수행되도록 compatible_double_hashes를 실행하십시오.

io_thread_pool_queue_size

IO 스레드 풀에 예약할 수 있는 jobs의 최대 개수입니다.
값이 0이면 무제한을 의미합니다.

keep_alive_timeout

연결을 닫기 전에 ClickHouse가 HTTP protocol의 들어오는 request를 기다리는 시간(초)입니다. 예시

ldap_servers

여기에 LDAP 서버와 해당 connection 매개변수를 나열하여 다음과 같이 사용할 수 있습니다.
  • ‘password’ 대신 ‘ldap’ authentication 메커니즘이 지정된 전용 로컬 사용자의 authenticator로 사용합니다
  • 원격 user directories로 사용합니다.
다음 설정은 sub-tags로 구성할 수 있습니다. user_dn_detection 설정은 sub-tags로 구성할 수 있습니다. 예시:
예시 (후속 역할 매핑을 위해 user DN 감지가 구성된 일반적인 Active Directory):

로거

로그 메시지의 위치와 포맷입니다. 키: 로그 포맷 지정자 log 및 errorLog 경로의 파일 이름은 아래 포맷 지정자를 지원하며, 이를 결과 파일 이름에 사용할 수 있습니다(디렉터리 부분에서는 지원되지 않음). “예시” 컬럼은 2023-07-06 18:32:07 시점의 출력을 보여줍니다. 예시
콘솔에 로그 메시지만 출력하려면:
레벨별 재정의 개별 로그 이름의 로그 레벨은 재정의할 수 있습니다. 예를 들어, 로거 “Backup” 및 “RBAC”의 모든 메시지를 음소거할 수 있습니다.
syslog log messages를 syslog에도 추가로 기록하려면 다음과 같이 합니다:
<syslog>의 키: 로그 포맷 콘솔 로그에 출력할 로그 포맷을 지정할 수 있습니다. 현재는 JSON만 지원됩니다. 예시 다음은 출력되는 JSON 로그의 예시입니다:
JSON 로깅을 사용하려면 다음 스니펫을 사용하세요:
JSON 로그의 키 이름 변경 키 이름은 <names> 태그 안의 태그 값을 변경하여 수정할 수 있습니다. 예를 들어 DATE_TIME를 MY_DATE_TIME로 바꾸려면 <date_time>MY_DATE_TIME</date_time>를 사용할 수 있습니다. JSON 로그의 키 생략 속성을 주석 처리하면 JSON 로그에서 해당 로그 속성을 생략할 수 있습니다. 예를 들어 로그에 query_id가 출력되지 않도록 하려면 <query_id> 태그를 주석 처리하면 됩니다.

logger.count

로그 교체 정책: ClickHouse가 보관하는 과거 로그 파일의 최대 개수입니다.

logger.errorlog

오류 로그 파일 경로입니다.

logger.formatting.type

콘솔 출력의 로그 포맷입니다. 현재는 <json>만 지원합니다.

logger.level

로그 레벨입니다. 허용되는 값: <none> (로깅 비활성화), <fatal>, <critical>, <error>, <warning>, <notice>, <information>, <debug>, <trace>, <test>.

logger.log

로그 파일의 경로입니다.

logger.rotation

로그 파일 교체 정책: 로그 파일을 언제 교체할지 제어합니다. 교체는 크기, 시간 또는 둘의 조합을 기준으로 수행할 수 있습니다. 예시: 100M, daily, 100M,daily. 로그 파일이 지정된 크기를 초과하거나 지정된 시간 인터벌에 도달하면 파일 이름이 변경되어 보관되고, 새 로그 파일이 생성됩니다.

logger.shutdown_level

종료 레벨은 서버 종료 시 루트 로거 레벨을 설정하는 데 사용됩니다.

logger.size

로그 교체 정책: 바이트 단위의 로그 파일 최대 크기입니다. 로그 파일 크기가 이 임계값을 초과하면 파일 이름이 변경되어 보관되며, 새 로그 파일이 생성됩니다.

logger.startup_level

시작 레벨은 server 시작 시 루트 로거의 로그 레벨을 설정하는 데 사용됩니다. 시작이 완료되면 로그 레벨은 <level> 설정으로 되돌아갑니다.

logger.stream_compress

LZ4를 사용해 로그 메시지를 압축합니다. 활성화하려면 <1> 또는 <true>로 설정하세요.

logger.syslog_level

syslog에 대한 로그 레벨입니다.

logger.use_syslog

로그 출력도 syslog로 전달합니다.

macros

복제된 테이블에 사용하는 매개변수 치환입니다. 복제된 테이블을 사용하지 않으면 생략할 수 있습니다. 자세한 내용은 복제된 테이블 만들기 섹션을 참조하십시오. 예시

message_queue_disable_insertion

메시지 큐 엔진(Kafka, RabbitMQ, NATS)에서 attached 상태인 materialized view로 삽입하는 기능을 비활성화합니다

metric_log

기본적으로 비활성화되어 있습니다. 활성화 메트릭 이력 수집 system.metric_log을 수동으로 활성화하려면, 다음 내용으로 /etc/clickhouse-server/config.d/metric_log.xml 파일을 생성하십시오:
비활성화 metric_log 설정을 비활성화하려면 다음 내용을 포함하는 /etc/clickhouse-server/config.d/disable_metric_log.xml 파일을 생성하십시오:
다음 설정은 하위 태그로 구성할 수 있습니다: 또한 다음 서버 수준 설정은 모든 시스템 로그 테이블의 기본 플러시 정책을 제어합니다:

mmap_cache_size

이 설정을 사용하면 빈번한 open/close 호출(연이은 페이지 폴트로 인해 비용이 매우 큼)을 줄이고, 여러 스레드와 쿼리에서 매핑을 재사용할 수 있습니다. 설정값은 매핑된 영역의 개수(보통 매핑된 파일 수와 동일)입니다. 매핑된 파일의 데이터 양은 다음 시스템 테이블에서 다음 메트릭으로 모니터링할 수 있습니다.
매핑된 파일의 데이터 양은 메모리를 직접 소비하지 않으며, 쿼리 또는 server 메모리 사용량에도 포함되지 않습니다. 이는 이 메모리가 OS 페이지 캐시와 유사하게 폐기될 수 있기 때문입니다. 이 캐시는 MergeTree 엔진 계열 테이블에서 오래된 파트가 제거되면 자동으로 해제되고(파일이 닫힘), SYSTEM DROP MMAP CACHE 쿼리로 수동 해제할 수도 있습니다.이 설정은 런타임에 변경할 수 있으며 즉시 적용됩니다.

mutation_workload

뮤테이션과 다른 워크로드 간의 리소스 활용 및 공유 방식을 조절하는 데 사용됩니다. 지정된 값은 모든 백그라운드 뮤테이션의 workload 설정 값으로 사용됩니다. 이 값은 MergeTree 설정으로 재정의할 수 있습니다. 관련 항목

named_collections_storage.type

이름이 지정된 컬렉션의 스토리지 유형입니다. 가능한 값은 local, local_encrypted, keeper, keeper_encrypted, zookeeper, zookeeper_encrypted입니다. named_collections_storage.type으로 설정합니다(XML에서는 <named_collections_storage><type>).

oom_score

Linux 시스템에서 OOM killer의 동작을 제어합니다.

openSSL

SSL 클라이언트/서버 구성. libpoco 라이브러리가 SSL을 지원합니다. 사용 가능한 구성 옵션은 SSLManager.h에 설명되어 있습니다. 기본값은 SSLManager.cpp에서 확인할 수 있습니다. certificateFile, privateKeyFile, caConfig가 참조하는 파일은 내용이 변경되거나 SYSTEM RELOAD CONFIG를 실행할 때 재시작 없이 다시 로드됩니다. 새 연결에는 다시 로드된 인증서가 사용되며, 이미 수립된 연결은 영향을 받지 않습니다. 서버/클라이언트 설정 키: 설정 예시:

openSSL.client.caConfig

신뢰할 수 있는 CA certificate가 들어 있는 파일 또는 directory의 경로입니다. 파일을 가리키는 경우 PEM 포맷이어야 하며 여러 개의 CA certificate를 포함할 수 있습니다. directory를 가리키는 경우 각 CA certificate마다 .pem 파일이 하나씩 있어야 합니다. 파일 이름은 CA subject name 해시 값을 기준으로 조회됩니다. 자세한 내용은 SSL_CTX_load_verify_locations의 man 페이지에서 확인할 수 있습니다. CA 인증서는 파일이 변경되거나 SYSTEM RELOAD CONFIG가 실행될 때 재시작 없이 다시 로드되며, 새 연결은 다시 로드된 인증서를 기준으로 검증됩니다.

openSSL.client.cacheSessions

세션 캐시 사용을 활성화하거나 비활성화합니다. <sessionIdContext>와 함께 사용해야 합니다. 허용되는 값: <true>, <false>.

openSSL.client.certificateFile

PEM 포맷의 클라이언트/서버 인증서 파일 경로입니다. <privateKeyFile>에 인증서가 포함되어 있으면 생략할 수 있습니다.

openSSL.client.cipherList

지원되는 OpenSSL 암호 목록입니다.

openSSL.client.disableProtocols

사용할 수 없도록 설정된 프로토콜입니다.

openSSL.client.extendedVerification

활성화된 경우 인증서의 CN 또는 SAN이 상대 호스트명과 일치하는지 확인합니다.

openSSL.client.fips

OpenSSL FIPS 모드를 활성화합니다. 라이브러리의 OpenSSL 버전이 FIPS를 지원하는 경우에 지원됩니다.

openSSL.client.invalidCertificateHandler.name

유효하지 않은 인증서를 검증하기 위한 클래스(CertificateHandler의 하위 클래스)입니다. 예시: <<invalidCertificateHandler> <name>RejectCertificateHandler</name> </invalidCertificateHandler>>.

openSSL.client.loadDefaultCAFile

기본 CA 인증서를 사용할지 여부를 결정합니다. ClickHouse는 </etc/ssl/cert.pem> 파일(또는 </etc/ssl/certs> 디렉터리), 환경 변수 <SSL_CERT_FILE>(또는 <SSL_CERT_DIR>)로 지정된 파일(또는 디렉터리), 그리고 여러 배포판에서 널리 사용되는 위치에서 해당 인증서를 찾습니다. 파일 시스템에서 CA 인증서를 찾지 못하고, 명시적인 caConfig도 구성되어 있지 않으며, 바이너리가 내장 CA 인증서를 포함하도록 빌드되었다면(기본값이며 ENABLE_EMBEDDED_CA_CERTIFICATES 빌드 옵션으로 제어됨) 내장 인증서가 대신 사용됩니다. 따라서 “from scratch”로 빌드한 컨테이너처럼 파일이 전혀 없는 최소 환경에서도 TLS가 동작합니다. 내장 CA 인증서가 없는 빌드에서는 이 경우 오류가 발생합니다.

openSSL.client.preferServerCiphers

클라이언트가 선호하는 서버 암호 스위트입니다.

openSSL.client.privateKeyFile

PEM 인증서의 개인 키가 들어 있는 파일 경로입니다. 이 파일에는 키와 인증서가 함께 포함될 수 있습니다.

openSSL.client.privateKeyPassphraseHandler.name

개인 키에 액세스할 때 사용할 패스프레이스를 요청하는 클래스(PrivateKeyPassphraseHandler 하위 클래스)입니다. 예시: <<privateKeyPassphraseHandler>>, <<name>KeyFileHandler</name>>, <<options><password>test</password></options>>, <</privateKeyPassphraseHandler>>

openSSL.client.verificationDepth

검증 체인의 최대 길이입니다. 인증서 체인의 길이가 설정된 값을 초과하면 검증에 실패합니다.

openSSL.client.verificationMode

노드 인증서를 검증하는 방식입니다. 자세한 내용은 Context 클래스 설명을 참조하십시오. 가능한 값: <none>, <relaxed>, <strict>, <once>.

openSSL.server.caConfig

신뢰할 수 있는 CA 인증서가 들어 있는 파일 또는 디렉터리의 경로입니다. 파일을 가리키는 경우 PEM 포맷이어야 하며 여러 개의 CA 인증서를 포함할 수 있습니다. 디렉터리를 가리키는 경우 각 CA 인증서마다 .pem 파일이 하나씩 있어야 합니다. 파일 이름은 CA subject name의 hash value를 기준으로 조회됩니다. 자세한 내용은 SSL_CTX_load_verify_locations의 man 페이지에서 확인할 수 있습니다. 파일이 변경되거나 SYSTEM RELOAD CONFIG가 실행되면 CA 인증서는 재시작 없이 다시 로드되며, 새로운 연결은 다시 로드된 인증서를 기준으로 검증됩니다.

openSSL.server.cacheSessions

세션 캐싱 사용 여부를 설정합니다. <sessionIdContext>와 함께 사용해야 합니다. 허용되는 값: <true>, <false>.

openSSL.server.certificateFile

PEM 포맷의 클라이언트/서버 인증서 파일 경로입니다. <privateKeyFile>에 인증서가 포함되어 있으면 생략할 수 있습니다.

openSSL.server.cipherList

OpenSSL에서 지원하는 암호화 방식입니다.

openSSL.server.disableProtocols

사용이 허용되지 않는 프로토콜입니다.

openSSL.server.extendedVerification

활성화되면 인증서의 CN 또는 SAN이 상대 호스트명과 일치하는지 확인합니다.

openSSL.server.fips

OpenSSL FIPS 모드를 활성화합니다. library의 OpenSSL 버전에서 FIPS를 지원하는 경우 사용할 수 있습니다.

openSSL.server.invalidCertificateHandler.name

유효하지 않은 인증서를 검증하는 데 사용하는 클래스(CertificateHandler의 하위 클래스)입니다. 예시: <<invalidCertificateHandler> <name>RejectCertificateHandler</name> </invalidCertificateHandler>>.

openSSL.server.loadDefaultCAFile

기본 CA 인증서를 사용할지 여부를 결정합니다. ClickHouse는 </etc/ssl/cert.pem> 파일(또는 </etc/ssl/certs> 디렉터리), 환경 변수 <SSL_CERT_FILE>(또는 <SSL_CERT_DIR>)로 지정된 파일(또는 디렉터리), 그리고 여러 배포판에서 널리 사용되는 위치에서 인증서를 찾습니다. 파일 시스템에서 CA 인증서를 찾지 못하고, 명시적인 caConfig도 구성되어 있지 않으며, 바이너리가 내장 CA 인증서를 포함하여 빌드된 경우(기본 동작이며 ENABLE_EMBEDDED_CA_CERTIFICATES 빌드 옵션으로 제어됨)에는 내장 인증서가 대신 사용됩니다. 따라서 “from scratch”로 빌드된 컨테이너처럼 파일이 전혀 없는 최소 환경에서도 TLS가 동작합니다. 내장 CA 인증서가 포함되지 않은 빌드에서는 이 경우 오류가 발생합니다.

openSSL.server.preferServerCiphers

클라이언트가 선호하는 서버 암호군입니다.

openSSL.server.privateKeyFile

PEM 인증서의 개인 키가 들어 있는 파일의 경로입니다. 이 파일에는 키와 인증서가 함께 포함될 수 있습니다.

openSSL.server.privateKeyPassphraseHandler.name

개인 키에 액세스할 때 사용할 패스프레이스를 요청하는 클래스(PrivateKeyPassphraseHandler 하위 클래스)입니다. 예시: <<privateKeyPassphraseHandler>>, <<name>KeyFileHandler</name>>, <<options><password>test</password></options>>, <</privateKeyPassphraseHandler>>

openSSL.server.sessionCacheSize

서버가 캐시에 저장하는 세션의 최대 개수입니다. 값이 0이면 세션 수는 무제한입니다.

openSSL.server.sessionIdContext

서버가 생성하는 각 식별자 끝에 추가하는 고유한 임의 문자 집합입니다. 문자열 길이는 <SSL_MAX_SSL_SESSION_ID_LENGTH>를 초과해서는 안 됩니다. 이 매개변수는 서버가 세션을 캐시하는 경우와 클라이언트가 캐싱을 요청한 경우 모두에서 문제를 방지하는 데 도움이 되므로 항상 지정하는 것이 좋습니다.

openSSL.server.sessionTimeout

서버에서 세션을 캐싱하는 시간(단위: 시간)입니다.

openSSL.server.verificationDepth

검증 체인의 최대 길이입니다. 인증서 체인 길이가 설정된 값을 초과하면 검증에 실패합니다.

openSSL.server.verificationMode

노드의 인증서를 검증하는 방식입니다. 자세한 내용은 Context 클래스 설명을 참조하십시오. 가능한 값: <none>, <relaxed>, <strict>, <once>.

opentelemetry_span_log

opentelemetry_span_log 시스템 테이블 설정입니다. 다음 설정은 하위 태그로 구성할 수 있습니다: 또한 다음 서버 수준 설정은 모든 시스템 로그 테이블의 기본 플러시 정책을 제어합니다:
예시:

part_log

MergeTree와 관련된 이벤트를 로깅합니다. 예를 들어 데이터 추가나 머지 같은 작업이 해당됩니다. 이 로그를 사용하면 머지 알고리즘을 시뮬레이션하고 특성을 비교할 수 있습니다. 머지 프로세스도 시각화할 수 있습니다. 쿼리는 별도의 파일이 아니라 system.part_log 테이블에 기록됩니다. 이 테이블의 이름은 table 매개변수에서 설정할 수 있습니다(아래 참조). 다음 설정은 하위 태그로 구성할 수 있습니다: 또한 다음 서버 수준 설정은 모든 시스템 로그 테이블의 기본 플러시 정책을 제어합니다:
예시

경로

데이터가 저장된 디렉터리의 경로입니다.
끝의 슬래시는 필수입니다.
예시

per_cpu_untracked_memory_thread_buffer

각 스레드가 공유 per-CPU 예산에 접근하지 않고 보유할 수 있는 추적되지 않은 메모리의 양(바이트)입니다. 이는 작은 메모리 할당에 대한 per-CPU bookkeeping 비용을 분산시키며, 최악의 경우 max_per_cpu_untracked_memory * number_of_cpus 위에 추가되는 여유분입니다. 값이 0이면 이 여유분이 제거됩니다. 즉, 모든 allocation이 공유 per-CPU 카운터를 업데이트합니다(가장 정확하지만 contention이 더 커집니다). Linux에서만 지원됩니다.

point_in_polygon_cache_size

상수 다각형 인수를 사용하는 pointInPolygon 함수에서 사용되는 전처리된 다각형 캐시의 최대 크기(바이트)입니다. 한도를 초과한 항목은 가장 최근에 사용되지 않은 순서대로 제거됩니다. 이 값을 0으로 설정하면 캐시가 비활성화됩니다. 즉, 캐시된 모든 다각형이 제거되고, 이후 실행되는 모든 쿼리는 상수 다각형을 매번 새로 전처리합니다. 이 한도를 변경하지 않고도 SYSTEM DROP POINT IN POLYGON CACHE 쿼리로 캐시를 수동으로 비울 수 있습니다.
이 설정은 런타임에 수정할 수 있으며 즉시 적용됩니다.

prefixes_deserialization_thread_pool_thread_pool_queue_size

prefixes 역직렬화용 스레드 풀에 예약할 수 있는 최대 작업 수입니다.
값이 0이면 제한이 없음을 의미합니다.

prepare_system_log_tables_on_startup

값이 true이면 ClickHouse는 시작 전에 구성된 모든 system.*_log 테이블을 생성합니다. 일부 시작 스크립트가 이러한 테이블에 의존하는 경우 도움이 될 수 있습니다.

process_query_plan_packet

이 설정을 사용하면 쿼리 계획 패킷을 읽을 수 있습니다. 이 패킷은 serialize_query_plan이 활성화되면 분산 쿼리에서 전송됩니다. 쿼리 계획의 바이너리 역직렬화 과정에서 발생할 수 있는 버그로 인한 잠재적인 보안 문제를 방지하기 위해 기본적으로 비활성화되어 있습니다. 예시

processors_profile_log

processors_profile_log 시스템 테이블에 대한 설정입니다. 다음 설정은 하위 태그로 구성할 수 있습니다: 또한 다음 서버 수준 설정은 모든 시스템 로그 테이블의 기본 플러시 정책을 제어합니다:
기본 설정은 다음과 같습니다.

prometheus

Prometheus에서 스크레이핑할 수 있도록 메트릭 데이터를 노출합니다. 설정:
  • endpoint – Prometheus server가 메트릭을 스크레이핑할 HTTP 엔드포인트입니다. ’/‘로 시작해야 합니다.
  • port – endpoint에 사용할 포트입니다.
  • metrics – system.metrics 테이블의 메트릭을 노출합니다.
  • events – system.events 테이블의 메트릭을 노출합니다.
  • asynchronous_metrics – system.asynchronous_metrics 테이블의 현재 메트릭 값을 노출합니다. 키-값 메트릭(CPU core, 블록 디바이스, 네트워크 인터페이스 또는 디스크별로 분리된 메트릭)은 키마다 하나의 샘플로 노출되며, 키를 레이블로 포함합니다: ClickHouseAsyncMetrics_BlockReadBytes{device="sda"}. asynchronous_metrics_key_values_mode server setting을 사용하면 26.8 이전의 변형된 이름(ClickHouseAsyncMetrics_BlockReadBytes_sda)으로 노출하거나, 두 형식을 동시에 노출할 수 있습니다.
  • errors - 마지막 server 재시작 이후 error codes별 오류 수를 노출합니다. 이 정보는 system.errors에서도 확인할 수 있습니다.
  • labels – 노출되는 모든 메트릭에 추가되는 상수 레이블입니다. 각 하위 요소는 하나의 레이블을 정의합니다. 요소 이름은 레이블 이름이며([a-zA-Z_][a-zA-Z0-9_]*와 일치해야 함), 요소 값은 레이블 값입니다. 레이블 값은 from_env 속성 같은 표준 구성 치환을 지원합니다. 레이블 이름이 __로 시작하는 경우(Prometheus에서 예약됨) 또는 이 엔드포인트의 활성화된 섹션에서 이미 기록하는 레이블과 충돌하는 경우 거부됩니다. 그렇지 않으면 샘플에 동일한 레이블 이름이 두 번 포함되기 때문입니다. 따라서 예약되는 이름은 엔드포인트에서 활성화된 내보내기 범위에 따라 달라집니다. histograms가 활성화된 경우 le, info가 활성화된 경우 ClickHouse_Info 레이블(name, version, version_describe, version_major, version_minor, version_patch), asynchronous_metrics가 활성화되어 있고 키-값 형식으로 게시되는 경우(asynchronous_metrics_key_values_mode server setting이 결정) 키-값 비동기 메트릭의 키 레이블(channel, cpu, device, disk, interface, mc, sensor), histograms/dimensional_metrics가 활성화된 경우 노출된 히스토그램 또는 차원 메트릭 패밀리에서 사용되는 모든 레이블(예: group, direction, operation_type)이 이에 해당합니다. 엔드포인트가 실제로 노출하는 항목에 따라 달라지므로 한 엔드포인트에서는 유효한 이름이 다른 엔드포인트에서는 거부될 수 있습니다. 예를 들어 Keeper keeper_metrics_only 엔드포인트는 keeper_* 패밀리만 노출하므로 server 패밀리에서만 사용되는 레이블은 여기에서 허용됩니다. 상수 레이블은 SYSTEM RELOAD CONFIG를 포함하여 구성이 로드될 때 동일한 규칙으로 검증됩니다. 상수 레이블이 충돌하게 만드는 다시 로드는 — 그러한 레이블을 추가하거나 asynchronous_metrics_key_values_mode를 변경하여 키 레이블이 기록되기 시작하는 경우 — 동일한 레이블을 두 번 노출하는 대신 적용되기 전에 전체가 거부됩니다. 모드 변경이 허용되면 메트릭을 노출하는 엔드포인트가 다시 생성되어, 동일한 구성의 새 형식과 레이블이 함께 게시됩니다.
예시
다음을 확인하세요(127.0.0.1을 ClickHouse 서버의 IP 주소 또는 호스트명으로 바꾸십시오):

prometheus.keeper_metrics_only

Keeper 관련 메트릭만 노출합니다

프록시

현재 S3 스토리지, S3 테이블 함수 및 URL 함수에서 지원하는 HTTP 및 HTTPS 요청용 프록시 서버를 정의합니다. 프록시 서버를 정의하는 방법은 세 가지입니다.
  • 환경 변수
  • 프록시 목록
  • 원격 프록시 리졸버
특정 호스트에 대해서는 no_proxy를 사용해 프록시 서버를 우회할 수도 있습니다. 환경 변수 http_proxy 및 https_proxy 환경 변수를 사용하면 지정한 프로토콜에 대한 프록시 서버를 설정할 수 있습니다. 시스템에 설정되어 있다면 별도 설정 없이 원활하게 작동합니다. 이 방법은 지정한 프로토콜에 프록시 서버가 하나뿐이고 해당 프록시 서버가 변경되지 않을 때 가장 간단합니다. 프록시 목록 이 방법을 사용하면 지정한 프로토콜에 대해 하나 이상의 프록시 서버를 설정할 수 있습니다. 프록시 서버가 둘 이상 정의되면 ClickHouse는 서로 다른 프록시를 라운드 로빈 방식으로 사용하여 서버 간에 부하를 분산합니다. 이 방법은 프로토콜에 대해 프록시 서버가 둘 이상 있고 프록시 서버 목록이 변경되지 않을 때 가장 간단합니다. 구성 템플릿
아래 탭에서 상위 필드를 선택하면 해당 하위 필드를 볼 수 있습니다:
원격 프록시 리졸버 프록시 서버는 동적으로 변경될 수 있습니다. 이 경우 리졸버의 엔드포인트를 정의할 수 있습니다. ClickHouse는 해당 엔드포인트로 본문이 없는 GET 요청을 보내고, 원격 리졸버는 프록시 호스트를 반환해야 합니다. ClickHouse는 이를 사용하여 다음 템플릿으로 프록시 URI를 구성합니다: \{proxy_scheme\}://\{proxy_host\}:{proxy_port} 구성 템플릿
아래 탭에서 상위 필드를 선택하여 하위 항목을 확인하십시오:
우선순위 프록시 설정은 다음 순서로 결정됩니다: ClickHouse는 요청 프로토콜에 대해 우선순위가 가장 높은 리졸버 유형을 확인합니다. 해당 항목이 정의되어 있지 않으면, 환경 리졸버에 도달할 때까지 그다음으로 우선순위가 높은 리졸버 유형을 차례로 확인합니다. 따라서 리졸버 유형을 혼합하여 사용할 수도 있습니다.

remap_executable

대형 페이지(huge pages)를 사용해 기계어(machine code)(“text”)용 메모리를 재할당하는 설정입니다.
이 기능은 아직 매우 실험적인 단계입니다.
예시

replica_group_name

Replicated 데이터베이스의 레플리카 그룹 이름입니다. 복제된 데이터베이스에서 생성된 cluster는 동일한 그룹의 레플리카로 구성됩니다. DDL 쿼리는 동일한 그룹의 레플리카만 기다립니다.
  • 기본값: ""
예시

replicated_merge_tree

ReplicatedMergeTree 테이블용 미세 조정 설정입니다. 이 설정은 더 높은 우선순위를 가집니다. 자세한 내용은 MergeTreeSettings.h 헤더 파일을 참조하십시오. 예시

restore_threads

RESTORE 요청을 실행하는 최대 스레드 수입니다.

send_crash_reports

ClickHouse 코어 개발팀으로 크래시 보고서를 전송하기 위한 설정입니다. 특히 프로덕션 전 환경에서는 이 기능을 활성화해 주시면 매우 감사하겠습니다. 키: 권장 사용법

series_keeper_path

generateSerialID 함수로 생성된 자동 증가 번호를 포함하는 Keeper 경로입니다. 각 series는 이 경로 아래의 노드로 생성됩니다.

ssh_server

호스트 키의 공개 키 부분은 처음 연결할 때 SSH 클라이언트 측의 known_hosts 파일에 기록됩니다. Host Key Configurations는 기본적으로 비활성화되어 있습니다. 해당 호스트 키 구성을 활성화하려면 주석을 해제하고 각 SSH key의 경로를 지정하십시오: 예시:

table_engines_require_grant

true로 설정하면 사용자가 특정 엔진으로 테이블을 생성하려면 권한(grant)이 필요합니다. 예: GRANT TABLE ENGINE ON TinyLog to user.
  • 기본값: false
기본적으로는 이전 버전과의 호환성을 위해 특정 테이블 엔진으로 테이블을 생성할 때 권한 검사를 무시합니다. 하지만 이 값을 true로 설정하여 이러한 동작을 변경할 수 있습니다.

tcp_ssh_port

PTY를 통해 내장 클라이언트를 사용해 대화형으로 연결하고 쿼리를 실행할 수 있도록 하는 SSH 서버의 포트입니다. 예시:

text_log

텍스트 메시지 로깅을 위한 text_log 시스템 테이블의 설정입니다. 다음 설정은 하위 태그로 구성할 수 있습니다: 또한 다음 서버 수준 설정은 모든 시스템 로그 테이블의 기본 플러시 정책을 제어합니다:
추가로: 예시

thread_pool_queue_size

Global Thread 풀에 예약할 수 있는 작업의 최대 개수입니다. 큐 크기를 늘리면 메모리 사용량이 증가합니다. 이 값은 max_thread_pool_size와 동일하게 유지하는 것이 좋습니다.
값이 0이면 무제한을 의미합니다.
예시

throw_on_unknown_workload

쿼리 설정 ‘workload’로 알 수 없는 WORKLOAD에 접근할 때의 동작을 정의합니다.
  • true이면, 알 수 없는 WORKLOAD에 접근하려는 쿼리에서 RESOURCE_ACCESS_DENIED 예외가 발생합니다. WORKLOAD 계층 구조가 설정되고 WORKLOAD default가 포함된 이후에는 모든 쿼리에 리소스 스케줄링을 강제하는 데 유용합니다.
  • false(기본값)이면, ‘workload’ 설정이 알 수 없는 WORKLOAD를 가리키는 쿼리에 리소스 스케줄링 없이 무제한 접근이 허용됩니다. 이는 WORKLOAD default가 추가되기 전, WORKLOAD 계층 구조를 설정하는 동안 중요합니다.
예시
관련 항목

시간대

server의 시간대입니다. UTC 시간대 또는 지리적 위치를 나타내는 IANA 식별자(예: Africa/Abidjan)로 지정합니다. DateTime 필드를 텍스트 포맷(화면이나 파일에 출력되는 형식)으로 출력할 때 String과 DateTime 포맷 사이를 변환하거나, 문자열에서 DateTime 값을 가져올 때 시간대가 필요합니다. 또한 시간 및 날짜를 처리하는 함수에 입력 매개변수로 시간대가 전달되지 않은 경우에도 이 시간대가 사용됩니다. 예시
관련 항목

trace_log

trace_log 시스템 테이블 동작에 대한 설정입니다. 다음 설정은 하위 태그로 구성할 수 있습니다: 또한 다음 서버 수준 설정은 모든 시스템 로그 테이블의 기본 플러시 정책을 제어합니다:
기본 서버 구성 파일 config.xml에는 다음 설정 섹션이 있습니다:

url_scheme_mappers

축약되거나 기호로 표시된 URL 프리픽스를 전체 URL로 변환하는 구성입니다. 예시:

validate_tcp_client_information

Query 패킷을 수신할 때 클라이언트 정보의 유효성 검사를 수행할지 여부를 결정합니다. 기본값은 false입니다:

wait_dictionaries_load_at_startup

이 설정은 dictionaries_lazy_load가 false일 때의 동작을 지정합니다. (dictionaries_lazy_load가 true이면 이 설정은 아무런 영향이 없습니다.) wait_dictionaries_load_at_startup가 false이면 서버는 시작 시 모든 딕셔너리 로드를 시작하며, 로드와 동시에 연결도 수신합니다. 딕셔너리가 쿼리에서 처음 사용될 때 아직 로드되지 않았다면, 해당 쿼리는 딕셔너리 로드가 완료될 때까지 대기합니다. wait_dictionaries_load_at_startup를 false로 설정하면 ClickHouse를 더 빠르게 시작할 수 있지만, 일부 쿼리는 더 느리게 실행될 수 있습니다 (일부 딕셔너리가 로드될 때까지 기다려야 하기 때문입니다). wait_dictionaries_load_at_startup가 true이면 서버는 시작 시 모든 딕셔너리의 로드가 완료될 때까지 (성공 여부와 관계없이) 대기한 후 연결을 수신합니다. 예시

webassembly_udf_engine

WebAssembly UDF를 실행하는 데 사용하는 engine입니다. 지원되는 유일한 값은 ‘wasmtime’입니다.

webterminal_allowed_origins

/webterminal WebSocket 세션을 열 수 있도록 허용되는 전체 오리진(origin) 목록을 쉼표로 구분해 지정합니다 (scheme + host + 선택적 port). 비어 있으면 동일 출처 정책이 엄격하게 적용됩니다 (Origin은 요청의 scheme, host, port와 일치해야 합니다). 브라우저는 https를 사용하지만 request.isSecure()는 false를 반환하는 TLS 종료 리버스 프록시 뒤의 배포 환경에서는 이 값을 설정하십시오. 예시: https://example.com,https://app.example.com:8443.
마지막 수정일 2026년 9월 26일