> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-detect-table-modification.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Composable protocols를 사용하면 ClickHouse 서버에 대한 액세스를 더 유연하게 구성할 수 있습니다.

# Composable protocols

<div id="overview">
  ## 개요
</div>

Composable protocols를 사용하면 ClickHouse 서버에 대한 TCP 액세스를 더 유연하게 구성할 수 있습니다. 이 구성은 기존 구성과 함께 사용할 수도 있고, 이를 대체할 수도 있습니다.

<div id="composable-protocols-section-is-denoted-as-protocols-in-configuration-xml">
  ## Composable protocols 구성하기
</div>

Composable protocols는 XML 설정 파일에서 구성할 수 있습니다. 프로토콜
섹션은 XML 설정 파일에서 `protocols` 태그로 지정됩니다:

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

</protocols>
```

<div id="basic-modules-define-protocol-layers">
  ### 프로토콜 레이어 구성
</div>

기본 모듈을 사용해 프로토콜 레이어를 정의할 수 있습니다. 예를 들어
HTTP 레이어를 정의하려면 `protocols` 섹션에 새 기본 모듈을 추가하면 됩니다:

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

  <!-- plain_http 모듈 -->
  <plain_http>
    <type>http</type>
  </plain_http>

</protocols>
```

모듈은 다음과 같이 구성할 수 있습니다.

* `plain_http` - 다른 레이어에서 참조할 수 있는 이름
* `type` - 데이터를 처리하기 위해 인스턴스화되는 프로토콜 처리기를 나타냅니다.
  다음과 같은 미리 정의된 프로토콜 처리기가 있습니다:
  * `tcp` - 네이티브 ClickHouse 프로토콜 처리기
  * `http` - HTTP ClickHouse 프로토콜 처리기
  * `tls` - TLS 암호화 레이어
  * `proxy1` - PROXYv1 레이어
  * `mysql` - MySQL 호환 프로토콜 처리기
  * `postgres` - PostgreSQL 호환 프로토콜 처리기
  * `prometheus` - Prometheus 프로토콜 처리기
  * `interserver` - ClickHouse interserver 처리기

<Note>
  `gRPC` 프로토콜 처리기는 `Composable protocols`에 구현되어 있지 않습니다
</Note>

<div id="endpoint-ie-listening-port-is-denoted-by-port-and-optional-host-tags">
  ### 엔드포인트 구성
</div>

엔드포인트(수신 포트)는 `<port>`와 선택적 `<host>` 태그로 표시합니다.
예를 들어, 앞서 추가한 HTTP 레이어에서 엔드포인트를 구성하려면
구성을 다음과 같이 수정할 수 있습니다.

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

  <plain_http>

    <type>http</type>
    <!-- 엔드포인트 -->
    <host>127.0.0.1</host>
    <port>8123</port>

  </plain_http>

</protocols>
```

`<host>` 태그가 생략되면 최상위 config의 `<listen_host>`가
사용됩니다.

<div id="layers-sequence-is-defined-by-impl-tag-referencing-another-module">
  ### 레이어 시퀀스 구성
</div>

레이어 시퀀스는 `<impl>` 태그를 사용해 다른 모듈을 참조하는 방식으로 정의합니다. 예를 들어, plain\_http 모듈 위에 TLS 레이어를 구성하려면 구성을 다음과 같이 더 수정할 수 있습니다:

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

  <!-- http 모듈 -->
  <plain_http>
    <type>http</type>
  </plain_http>

  <!-- plain_http 모듈 위에 TLS 레이어로 구성된 https 모듈 -->
  <https>
    <type>tls</type>
    <impl>plain_http</impl>
    <host>127.0.0.1</host>
    <port>8443</port>
  </https>

</protocols>
```

<div id="endpoint-can-be-attached-to-any-layer">
  ### 레이어에 엔드포인트 추가하기
</div>

엔드포인트는 모든 레이어에 추가할 수 있습니다. 예를 들어,
HTTP(포트 8123)와 HTTPS(포트 8443)용 엔드포인트를 정의할 수 있습니다.

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

  <plain_http>
    <type>http</type>
    <host>127.0.0.1</host>
    <port>8123</port>
  </plain_http>

  <https>
    <type>tls</type>
    <impl>plain_http</impl>
    <host>127.0.0.1</host>
    <port>8443</port>
  </https>

</protocols>
```

<div id="additional-endpoints-can-be-defined-by-referencing-any-module-and-omitting-type-tag">
  ### 추가 엔드포인트 정의
</div>

추가 엔드포인트는 임의의 모듈을 참조하고
`<type>` 태그를 생략해 정의할 수 있습니다. 예를 들어,
`plain_http` 모듈에 대해 다음과 같이 `another_http` 엔드포인트를 정의할 수 있습니다:

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

  <plain_http>
    <type>http</type>
    <host>127.0.0.1</host>
    <port>8123</port>
  </plain_http>

  <https>
    <type>tls</type>
    <impl>plain_http</impl>
    <host>127.0.0.1</host>
    <port>8443</port>
  </https>

  <another_http>
    <impl>plain_http</impl>
    <host>127.0.0.1</host>
    <port>8223</port>
  </another_http>

</protocols>
```

<div id="custom-http-handlers-per-endpoint">
  ### 엔드포인트별 사용자 지정 HTTP 처리기
</div>

기본적으로 모든 `type=http` 프로토콜 항목은 동일한 `<http_handlers>`
구성을 사용합니다. `<handlers>` 태그를 추가해 다른 구성 섹션을
가리키도록 설정하면 이를 재정의할 수 있습니다. 이렇게 하면 각 HTTP 포트가
서로 다른 HTTP 라우팅 규칙 집합을 제공할 수 있습니다.

예를 들어, 포트 8124에서 자체 처리기를 사용하는 대체 HTTP API를 실행하려면:

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

  <plain_http>
    <type>http</type>
    <host>127.0.0.1</host>
    <port>8123</port>
  </plain_http>

  <alt_http>
    <type>http</type>
    <host>127.0.0.1</host>
    <port>8124</port>
    <handlers>http_handlers_alt</handlers>
  </alt_http>

</protocols>

<!-- Default handlers used by plain_http (port 8123) -->
<http_handlers>
    <defaults/>
</http_handlers>

<!-- Alternative handlers used by alt_http (port 8124) -->
<http_handlers_alt>
    <rule>
        <url>/custom</url>
        <handler>
            <type>predefined_query_handler</type>
            <query>SELECT 'custom_endpoint'</query>
        </handler>
    </rule>
    <defaults/>
</http_handlers_alt>
```

이 예시에서는 포트 8123에 대한 요청이 표준 `<http_handlers>` 규칙을 사용하고,
포트 8124에 대한 요청은 `<http_handlers_alt>` 규칙을 사용합니다. `<handlers>`를
생략하면 엔드포인트는 기본 `<http_handlers>`로 대체됩니다.

사용자 지정 처리기 섹션은
[`<http_handlers>`](/ko/reference/settings/server-settings/settings/http#http_handlers)와 동일한
포맷을 따릅니다.
사용자 지정 처리기 섹션의 변경 사항은 구성 다시 로드 시 감지되며, 해당
엔드포인트는 자동으로 다시 시작됩니다.

<div id="default-session-user-per-endpoint">
  ### 엔드포인트별 기본 세션 사용자
</div>

클라이언트가 사용자 이름을 지정하지 않고 연결하면(예: `user` 매개변수 없이 전송된 HTTP 요청 또는 사용자 이름이 비어 있는 네이티브 프로토콜 `Hello` 패킷) 서버는 기본 세션 사용자로 인증합니다. 기본 세션 사용자는 기본값이 `default`인 `default_session_user` [서버 설정](/ko/reference/settings/server-settings/settings)입니다.

`<default_session_user>` 태그를 사용하면 단일 엔드포인트에 대해 이 설정을 재정의할 수 있습니다. 이를 통해 서로 다른 수신 포트에서 서로 다른 익명 사용자를 처리할 수 있습니다:

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

  <plain_http>
    <type>http</type>
    <host>127.0.0.1</host>
    <port>8123</port>
  </plain_http>

  <readonly_http>
    <impl>plain_http</impl>
    <host>127.0.0.1</host>
    <port>8124</port>
    <default_session_user>readonly_user</default_session_user>
  </readonly_http>

</protocols>
```

이 예시에서 포트 8123으로 들어오는 자격 증명 없는 요청은 전역으로 구성된 기본 세션 사용자로 인증되며, 포트 8124로 들어오는 요청은
`readonly_user`로 인증됩니다. 사용자 이름을 명시적으로 지정하는 클라이언트에는 영향을 주지 않습니다.

태그는 엔드포인트의 모듈에서 참조된 (`impl`)
모듈을 향해 조회되며, 엔드포인트에 가장 가까운 값이 적용됩니다. 이 설정은 `tcp`, `http`,
`mysql`, `postgres` 프로토콜 처리기와 요청을 인증하는 `prometheus` 처리기
(`remote_write`, `remote_read`, `query`, `api_v1`)에 적용됩니다. 메트릭 노출 엔드포인트(Keeper 메트릭 전용 엔드포인트 포함)는
인증 없이 제공되며 이 설정을 무시합니다. 고정 사용자가 설정된 처리기(`http_handlers` 규칙의 `handler`
내 `user` 키 또는 `prometheus.handlers` 규칙의 `handler` 내 `user` 키)는 구성된 사용자로 인증되고 이 설정도 무시합니다. 특히
비어 있는 `default_session_user`로 인해 이러한 처리기가 거부되지는 않습니다. 이 설정은
`interserver` 프로토콜과 함께 사용할 수 없습니다. interserver 연결은 클러스터
시크릿과 초기 사용자로 인증되며 기본 세션 사용자를 사용하지 않습니다.

<div id="some-modules-can-contain-specific-for-its-layer-parameters">
  ### 추가 레이어 매개변수 지정
</div>

일부 모듈에는 추가 레이어 매개변수가 있을 수 있습니다. 예를 들어, TLS 레이어에서는
개인 키(`privateKeyFile`)와 인증서 파일(`certificateFile`)을
다음과 같이 지정할 수 있습니다:

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

  <plain_http>
    <type>http</type>
    <host>127.0.0.1</host>
    <port>8123</port>
  </plain_http>

  <https>
    <type>tls</type>
    <impl>plain_http</impl>
    <host>127.0.0.1</host>
    <port>8443</port>
    <privateKeyFile>another_server.key</privateKeyFile>
    <certificateFile>another_server.crt</certificateFile>
  </https>

</protocols>
```