[ClickHouse] 사용자 추가 및 설정하기 ( user.xml )

- 목차

 

들어가며.

ClickHouse 는 고성능 데이터 분석에 특화된 데이터베이스로,

사용자 및 권한 관리 기능을 통해 보다 안전하고 효율적인 운영이 가능합니다.

또한 설정 파일 중 하나인 user.xml 을 통해 사용자 계정을 관리하고, 세부적인 설정을 할 수 있는 강력한 기능을 제공합니다.

 

이번 글에서는 ClickHouse 24.9.3 Docker 이미지를 사용하여 사용자 추가 및 설정을 테스트하는 방법을 다룹니다.

 

https://hub.docker.com/_/clickhouse

clickhouse - Official Image | Docker Hub

 

user.xml 이란 ?

user.xml 은 ClickHouse 데이터베이스에서 사용자 계정 및 권한을 관리하기 위한 핵심 설정 파일입니다.

이 파일은 사용자별 비밀번호, 네트워크 접근 제한, 프로필, 쿼터 등을 정의하며, 이를 통해 개별 사용자에 대한 세부적인 제어가 가능합니다.

기본적으로 /etc/clickhouse-server/users.d/ 디렉토리에 위치하며, 새로운 사용자 설정은 개별 XML 파일로 추가 관리할 수 있습니다.

user.xml 을 활용하면 운영 환경에 맞는 사용자별 맞춤 설정을 쉽게 구성할 수 있어 보안과 효율성을 동시에 확보할 수 있습니다.

 

사용자 추가 및 설정하기.

user.xml 파일을 수정하여 사용자를 추가하거나 설정을 변경할 수 있습니다.

먼저 user.xml 의 구조에 대해서 간단히 설명드리겠습니다.

user.xml 은 <clickhouse> 라는 Root Node 과 그 하위에 <profiles>, <users>, <quotas>

 

 

• <profiles>: 사용자에게 적용할 리소스 제한 및 정책(예: 메모리 사용량, 쓰레드 수)을 정의합니다.
• <users>: 사용자 계정 및 해당 계정에 적용할 프로필, 네트워크 접근 제한, 비밀번호 등을 정의합니다.
• <quotas>: 특정 사용자나 그룹에 할당량(예: 쿼리 실행 횟수 제한)을 설정합니다.

 

 

그리하여 아래의 예시와 같은 기본적인 user.xml 을 확인할 수 있습니다.

<clickhouse>
    <profiles>
        <default>
        </default>

        <readonly>
            <readonly>1</readonly>
        </readonly>
    </profiles>

    <users>
        <default>
            <password></password>
            <networks>
                <ip>::/0</ip>
            </networks>
            <profile>default</profile>
            <quota>default</quota>
            <access_management>1</access_management>
            <named_collection_control>1</named_collection_control>
        </default>
    </users>

    <quotas>
        <default>
            <interval>
                <duration>3600</duration>
                <queries>0</queries>
                <errors>0</errors>
                <result_rows>0</result_rows>
                <read_rows>0</read_rows>
                <execution_time>0</execution_time>
            </interval>
        </default>
    </quotas>
</clickhouse>

 

위 user.xml 을 간단히 분석하게 되면 "default" 라는 이름의 사용자 하나만이 생성됩니다.

그리고 <password></password> 노드의 값이 비어있기 때문에 "default" 사용자는 비밀번호가 존재하지 않습니다.

 

아래의 명령어를 통해서 실행 중인 ClickHouse 서버와 연결을 맺을 수 있습니다.

clickhouse-client --user default

 

또는 "default" 사용자는 --user 옵션을 명시하지 않아도 접속이 가능합니다.

 

clickhouse-client

 

 

다수의 user.xml 의 병합.

여러 개의 user.xml 파일이 있을 경우, 각 파일의 설정이 병합되어 적용됩니다.
예를 들어, user_a.xml과 user_b.xml에 각각 정의된 설정은 모두 반영됩니다.

 

아래와 같이 user.xml 파일을 생성합니다.

user.xml 에는 custom_user_1 이라는 사용자를 추가하고, password 를 1234 로 설정하였습니다.

 

cat <<EOF> /tmp/user.xml
<clickhouse>
    <users>
        <custom_user_1>
            <password>1234</password>
            <networks>
                <ip>::/0</ip>
            </networks>
            <profile>default</profile>
            <quota>default</quota>
            <access_management>1</access_management>
            <named_collection_control>1</named_collection_control>
        </custom_user_1>
    </users>
</clickhouse>
EOF

 

그리고 생성한 user.xml 파일을 /etc/clickhouse-server/users.d 디렉토리 하위에 추가합니다.

/etc/clickhouse-server/users.d 하위에 추가된 user.xml 파일들은 실행되는 ClickHouse 서버에 사용자를 추가합니다.

 

docker run -d --platform linux/amd64 \
--name clickhouse-server \
--mount type=bind,source=/tmp/user.xml,target=/etc/clickhouse-server/users.d/user.xml \
clickhouse:24.9.3

 

아래의 캡쳐 사진은 custom_user_1 사용자로 ClickHouse Shell 에 접속하는 과정을 의미합니다.

 

 

 

User 상세 설정 알아보기.

이제 user.xml 설정 파일을 통해서 설정할 수 있는 사용자 설정에 대해서 알아보도록 하겠습니다.

 

password.

password 영역은 사용자의 계정 비밀번호를 설정하는 영역입니다.

위에서 살펴본 내용처럼 Plaintext 로 비밀번호를 설정하는 방식이 존재합니다.

뿐만 아니라 Hash 된 비밀번호를 설정하여 보안을 강화할 수 있습니다.

 

먼저 사용할 비밀번호인 1234 를 sha256sum 을 통해서 Hash 암호화를 적용합니다.

echo -n 1234 | sha256sum | tr -d '-'

03ac674216f3e15c761ee1a5e255f067953623c8b388b4459e13f978d7c846f4  -

 

그리고 <password_sha256_hex> 태그를 통해서 Hash 암호화된 비밀번호를 설정합니다.

cat <<EOF> /tmp/user.xml
<clickhouse>
    <users>
        <custom_user_1>
            <password_sha256_hex>03ac674216f3e15c761ee1a5e255f067953623c8b388b4459e13f978d7c846f4</password_sha256_hex>
            <networks>
                <ip>::/0</ip>
            </networks>
            <profile>default</profile>
            <quota>default</quota>
            <access_management>1</access_management>
            <named_collection_control>1</named_collection_control>
        </custom_user_1>
    </users>
</clickhouse>
EOF

docker run -d --platform linux/amd64 \
--name clickhouse-server \
--mount type=bind,source=/tmp/user.xml,target=/etc/clickhouse-server/users.d/user.xml \
clickhouse:24.9.3

 

아래의 사진과 같이 1234 비밀번호로 접속할 수 있습니다.

 

 

profile.

profile 설정을 통해서 user 와 profile 을 연결할 수 있습니다.

profile 은 사용자의 권한과 역할에 대한 설정입니다.

기본적으로 제공되는 profile 는 <default> 와 <readonly> 두가지가 제공되구요.

사용자가 커스텀하게 생성하거나 수정할 수 있습니다.

 

저는 새로운 사용자를 만들고 이 사용자에게 <readonly> profile 을 적용해보도록 하겠습니다.

 

custom_user_2 사용자를 추가합니다.

<profile>readonly</profile> 와 같이 설정하여 readonly 권한을 만을 적용합니다.

cat <<EOF> /tmp/user.xml
<clickhouse>
    <users>
        <custom_user_1>
            <password_sha256_hex>03ac674216f3e15c761ee1a5e255f067953623c8b388b4459e13f978d7c846f4</password_sha256_hex>
            <networks>
                <ip>::/0</ip>
            </networks>
            <profile>default</profile>
            <quota>default</quota>
            <access_management>1</access_management>
            <named_collection_control>1</named_collection_control>
        </custom_user_1>
        <custom_user_2>
            <password>0000</password>
            <networks>
                <ip>::/0</ip>
            </networks>
            <profile>readonly</profile>
            <quota>default</quota>
        </custom_user_2>        
    </users>
</clickhouse>
EOF

 

docker run -d --platform linux/amd64 \
--name clickhouse-server \
--mount type=bind,source=/tmp/user.xml,target=/etc/clickhouse-server/users.d/user.xml \
clickhouse:24.9.3

 

아래의 이미지는 custom_user_2 계정으로 접속한 결과입니다.

그리고 create database test; 와 같은 DDL 를 시도하였고, readonly mode 임으로 쿼리 실행에 실패한 결과를 보여줍니다.

 

 

 

 

access_management.

user.xml 파일 내부에서 <user> 태그를 통해 사용자의 여러가지 설정을 구성할 수 있습니다.

access_management 는 default 사용자에게 흔히 부여됩니다.

 

• 특정 사용자 계정을 생성, 수정, 삭제.
• 사용자의 인증 방식(비밀번호 등) 및 접근 가능성을 제어.
• 데이터베이스, 테이블, 또는 특정 작업(예: SELECT, INSERT)에 대한 세밀한 권한 부여 및 관리.
• 권한을 기반으로 사용자와 역할 간의 작업 범위를 설정.

 

그래서 일반적으로 default 사용자에게 access_management 의 권한을 부여하고,

ClickHouse Query 를 통하여 여러 가지 설정을 동적으로 구성할 수 있게 됩니다.