Overview
Composable protocols allow more flexible configuration of TCP access to the
ClickHouse server. This configuration can co-exist alongside, or replace,
conventional configuration.
Configuring composable protocols
Composable protocols can be configured in an XML configuration file. The protocols
section is denoted with protocols tags in the XML config file:
Configuring protocol layers
You can define protocol layers using basic modules. For example, to define an
HTTP layer, you can add a new basic module to the protocols section:
Modules can be configured according to:
plain_http - name which can be referred to by another layertype - denotes the protocol handler which will be instantiated to process data.
It has the following set of predefined protocol handlers:
tcp - native clickhouse protocol handlerhttp - HTTP clickhouse protocol handlertls - TLS encryption layerproxy1 - PROXYv1 layermysql - MySQL compatibility protocol handlerpostgres - PostgreSQL compatibility protocol handlerprometheus - Prometheus protocol handlerinterserver - clickhouse interserver handler
gRPC protocol handler is not implemented for Composable protocols
<port> and optional <host> tags.
For example, to configure an endpoint on the previously added HTTP layer we
could modify our configuration as follows:
If the <host> tag is omitted, then the <listen_host> from the root config is
used.
Configuring layer sequences
Layers sequences are defined using the <impl> tag, and referencing another
module. For example, to configure a TLS layer on top of our plain_http module
we could further modify our configuration as follows:
Attaching endpoints to layers
Endpoints can be attached to any layer. For example, we can define endpoints for
HTTP (port 8123) and HTTPS (port 8443):
Defining additional endpoints
Additional endpoints can be defined by referencing any module and omitting the
<type> tag. For example, we can define another_http endpoint for the
plain_http module as follows:
Custom HTTP handlers per endpoint
By default, all type=http protocol entries share the same <http_handlers>
configuration. You can override this by adding a <handlers> tag that points
to a different configuration section. This allows each HTTP port to serve a
different set of HTTP routing rules.
For example, to run an alternative HTTP API on port 8124 with its own handlers:
In this example, requests to port 8123 use the standard <http_handlers> rules,
while requests to port 8124 use the <http_handlers_alt> rules. If <handlers>
is omitted, the endpoint falls back to the default <http_handlers>.
The custom handlers section follows the same format as
<http_handlers>.
Changes to the custom handlers section are detected during config reload, and the
corresponding endpoint is automatically restarted.
Default session user per endpoint
When a client connects without specifying a user name (for example, an HTTP request
without the user parameter, or a native protocol Hello packet with an empty user
name), the server authenticates it as the default session user - the
default_session_user server setting,
whose default value is default.
The <default_session_user> tag overrides this setting for a single endpoint. This
allows different listening ports to serve different anonymous users:
In this example, requests without credentials on port 8123 are authenticated as the
globally configured default session user, while those on port 8124 are authenticated
as readonly_user. A client that passes a user name explicitly is not affected.
The tag is looked up from the endpoint’s module towards the referenced (impl)
modules, and the value closest to the endpoint wins. It applies to the tcp, http,
mysql and postgres protocol handlers, and to the prometheus handlers that
authenticate requests (remote_write, remote_read, query and api_v1); the
metrics exposition endpoints (including Keeper metrics-only endpoints) are served
without authentication and ignore the setting. Handlers with a fixed user (the user
key inside handler of an http_handlers rule, or the user key inside handler
of a prometheus.handlers rule) authenticate as their configured user and also ignore the setting - in
particular, an empty default_session_user does not reject them. It cannot be used with the
interserver protocol: interserver connections are authenticated by the cluster
secret and the initial user and never use the default session user.
Specifying additional layer parameters
Some modules can contain additional layer parameters. For example, the TLS layer
allows a private key (privateKeyFile) and certificate files (certificateFile)
to be specified as follows:
