Server Settings

## keeper\_server.socket\_receive\_timeout\_sec[​](#keeper_server.socket_receive_timeout_sec "Direct link to keeper_server.socket_receive_timeout_sec")

Keeper socket receive timeout.

## keeper\_server.socket\_send\_timeout\_sec[​](#keeper_server.socket_send_timeout_sec "Direct link to keeper_server.socket_send_timeout_sec")

Keeper socket send timeout.

## ldap\_servers[​](#ldap_servers "Direct link to ldap_servers")

List LDAP servers with their connection parameters here to:

- use them as authenticators for dedicated local users, who have an 'ldap' authentication mechanism specified instead of 'password'
- use them as remote user directories.

The following settings can be configured by sub-tags:

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Setting Description|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `bind_dn` Template used to construct the DN to bind to. The resulting DN will be constructed by replacing all `\{user_name\}` substrings of the template with the actual user name during each authentication attempt.| `enable_tls` Flag to trigger use of secure connection to the LDAP server. Specify `no` for plain text (`ldap://`) protocol (not recommended). Specify `yes` for LDAP over SSL/TLS (`ldaps://`) protocol (recommended, the default). Specify `starttls` for legacy StartTLS protocol (plain text (`ldap://`) protocol, upgraded to TLS).| `host` LDAP server hostname or IP, this parameter is mandatory and cannot be empty.|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `port` LDAP server port, default is 636 if `enable_tls` is set to true, `389` otherwise.| `tls_ca_cert_dir` path to the directory containing CA certificates.|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `tls_ca_cert_file` path to CA certificate file.|  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `tls_cert_file` path to certificate file.|  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `tls_cipher_suite` allowed cipher suite (in OpenSSL notation).|  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `tls_key_file` path to certificate key file.|  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | | `tls_minimum_protocol_version` The minimum protocol version of SSL/TLS. Accepted values are: `ssl2`, `ssl3`, `tls1.0`, `tls1.1`, `tls1.2` (the default).| `tls_require_cert` SSL/TLS peer certificate verification behavior. Accepted values are: `never`, `allow`, `try`, `demand` (the default).| `user_dn_detection` Section with LDAP search parameters for detecting the actual user DN of the bound user. This is mainly used in search filters for further role mapping when the server is Active Directory. The resulting user DN will be used when replacing `\{user_dn\}` substrings wherever they are allowed. By default, user DN is set equal to bind DN, but once search is performed, it will be updated with to the actual detected user DN value.| `verification_cooldown` A period of time, in seconds, after a successful bind attempt, during which a user will be assumed to be successfully authenticated for all consecutive requests without contacting the LDAP server. Specify `0` (the default) to disable caching and force contacting the LDAP server for each authentication request. | | | | | | | | | | | | | | | | | | | | | | | | | | | |

Setting `user_dn_detection` can be configured with sub-tags:

|  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- |
| Setting Description|  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | | `base_dn` template used to construct the base DN for the LDAP search. The resulting DN will be constructed by replacing all `\{user_name\}` and '{bind\_dn}' substrings of the template with the actual user name and bind DN during the LDAP search.| `scope` scope of the LDAP search. Accepted values are: `base`, `one_level`, `children`, `subtree` (the default).| `search_filter` template used to construct the search filter for the LDAP search. The resulting filter will be constructed by replacing all `\{user_name\}`, `\{bind_dn\}`, and `\{base_dn\}` substrings of the template with the actual user name, bind DN, and base DN during the LDAP search. Note, that the special characters must be escaped properly in XML. | | | | | | | |

Example:

```
<my_ldap_server>
    <host>localhost</host>
    <port>636</port>
    <bind_dn>uid={user_name},ou=users,dc=example,dc=com</bind_dn>
    <verification_cooldown>300</verification_cooldown>
    <enable_tls>yes</enable_tls>
    <tls_minimum_protocol_version>tls1.2</tls_minimum_protocol_version>
    <tls_require_cert>demand</tls_require_cert>
    <tls_cert_file>/path/to/tls_cert_file</tls_cert_file>
    <tls_key_file>/path/to/tls_key_file</tls_key_file>
    <tls_ca_cert_file>/path/to/tls_ca_cert_file</tls_ca_cert_file>
    <tls_ca_cert_dir>/path/to/tls_ca_cert_dir</tls_ca_cert_dir>
    <tls_cipher_suite>ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:AES256-GCM-SHA384</tls_cipher_suite>
</my_ldap_server>
```

Example (typical Active Directory with configured user DN detection for further role mapping):

```
<my_ad_server>
    <host>localhost</host>
    <port>389</port>
    <bind_dn>EXAMPLE\{user_name}</bind_dn>
    <user_dn_detection>
        <base_dn>CN=Users,DC=example,DC=com</base_dn>
        <search_filter>(&amp;(objectClass=user)(sAMAccountName={user_name}))</search_filter>
    </user_dn_detection>
    <enable_tls>no</enable_tls>
</my_ad_server>
```

## license\_file[​](#license_file "Direct link to license_file")

License file contents for ClickHouse Enterprise Edition

## license\_public\_key\_for\_testing[​](#license_public_key_for_testing "Direct link to license_public_key_for_testing")

Licensing demo key, for CI use only

## listen\_backlog[​](#listen_backlog "Direct link to listen_backlog")

Backlog (queue size of pending connections) of the listen socket. The default value of `<4096>` is the same as that of linux 5.4+).

Usually this value does not need to be changed, since:

- The default value is large enough,
- For accepting client's connections server has separate thread.

So even if you have `<TcpExtListenOverflows>` (from `<nstat>`) non-zero and this counter grows for ClickHouse server it does not mean that this value needs to be increased, since:

- Usually if `<4096>` is not enough it shows some internal ClickHouse scaling issue, so it is better to report an issue.
- It does not mean that the server can handle more connections later (and even if it could, by that moment clients may be gone or disconnected).

**Example**

```
<listen_backlog>4096</listen_backlog>
```

## listen\_host[​](#listen_host "Direct link to listen_host")

Restriction on hosts that requests can come from. If you want the server to answer all of them, specify `::`.

Examples:

```
<listen_host>::1</listen_host>
<listen_host>127.0.0.1</listen_host>
```

## listen\_reuse\_port[​](#listen_reuse_port "Direct link to listen_reuse_port")

Allow multiple servers to listen on the same address:port. Requests will be routed to a random server by the operating system. Enabling this setting is not recommended.

**Example**

```
<listen_reuse_port>0</listen_reuse_port>
```

## listen\_try[​](#listen_try "Direct link to listen_try")

The server will not exit if IPv6 or IPv4 networks are unavailable while trying to listen.

**Example**

```
<listen_try>0</listen_try>
```