Support sessions

Support sessions are how you grant ClickHouse temporary diagnostic access through the ClickHouse Connector. This page explains what a session is, how to enable and disable one, what ClickHouse operators can do while one is active, and how to audit everything that happened.

What a support session is

A support session is a time-boxed window during which the troubleshooter accepts commands from ClickHouse support engineers. When no session is active, the troubleshooter refuses all commands, even while its outbound WebSocket is connected. There is no other execution path: nothing runs without a session, and ClickHouse cannot open one for you. ClickHouse’s control plane never connects into your environment; it only receives what the troubleshooter sends over its outbound channel, and that channel carries commands only while your session state allows it. You control sessions through two surfaces:

The session gateway, an authenticated API embedded in the troubleshooter with enable, disable, and status endpoints. Every gateway call requires a short-lived OIDC ID token whose email is on your operator allowlist.
The local session file on Linux VM installs, written directly on the host with root access.

Gateway transport depends on the target. A VM gateway serves self-signed TLS that each operator fingerprint-pins. A Kubernetes gateway listens pod-locally over HTTP, reached through kubectl port-forward (the tunnel rides the API server’s TLS) or through an Ingress that terminates TLS with a CA-issued certificate. You choose your session posture, including the operator allowlist, during clicklink clctl init.

Enabling and disabling sessions

Kubernetes
Linux VM

The gateway listens on port 8443 of the troubleshooter pod. If you have cluster access, reach it over a port-forward; the tunnel rides the Kubernetes API server’s TLS:

CONNECTOR_NAMESPACE='clicklink'   # the connector namespace you chose at init
kubectl -n "${CONNECTOR_NAMESPACE}" port-forward statefulset/clicklink-connector-troubleshooter 8443:8443

Then, in another terminal, enable a session:

clicklink clctl troubleshoot session enable \
  --gateway-url http://localhost:8443 \
  --duration 4h \
  --reason "<ticket reference>"

Check or end it the same way:

clicklink clctl troubleshoot session status --gateway-url http://localhost:8443
clicklink clctl troubleshoot session disable --gateway-url http://localhost:8443

The caller’s OIDC identity must be on the operator allowlist; unauthenticated or unlisted callers get a 401 or 403 and the attempt is logged. If you prefer not to require cluster credentials, the chart can expose the gateway through an opt-in Ingress that terminates TLS with a CA-issued certificate; see configuration.

With root access on the host, manage the session directly. State is persisted to /var/lib/clicklink/session.json, which the daemon and the CLI read and write atomically:

sudo clicklink clctl troubleshoot session enable --duration 4h --reason "<ticket reference>"
sudo clicklink clctl troubleshoot session status
sudo clicklink clctl troubleshoot session disable

The gateway is also available on a VM for callers without root access. It serves self-signed TLS, so each session user pins the gateway’s certificate fingerprint once:

clicklink clctl troubleshoot gateway trust \
  --gateway-url https://<vm-host>:8443 \
  --gateway-fingerprint <sha256-fingerprint>

The pin is stored in ~/.clicklink/clctl.yaml, and connections fail closed if the presented certificate does not match it.

Session expiry

Sessions expire on their own. The default duration is 4 hours; session enable --duration can set anything up to 24 hours. When the session expires, or the moment you run session disable, the troubleshooter stops accepting commands. Disabling the session is the immediate revocation path: no restart, no coordination with ClickHouse required.

Operator allowlist

Every gateway call is authorized against an allowlist of operator emails, matched against the email attested by the validated OIDC token, never against anything the client claims about itself.

Kubernetes: set clctl.gateway.allowedOperators in your values overlay. The list is rendered into a ConfigMap that the gateway re-reads on a 30-second window, so a values change plus helm upgrade rotates the allowlist without a pod restart.
Linux VM: the allowlist lives at /etc/clicklink/allowed-operators.txt, written by clicklink clctl init from the operator emails you provide.

What operators can do during a session

While a session is active, ClickHouse support engineers can run:

Read-only SQL against your clusters as the pcm_troubleshooter user, restricted to an explicit table allowlist. The default allowlist covers ClickHouse system tables such as system.parts, system.merges, system.replicas, system.metrics, and system.settings; system.query_log and system.text_log are denied unconditionally, so query history never leaves. The default allowlist does include system.processes, whose query column shows the text of statements running at that moment; remove it from the session table allowlist (troubleshooter.allowedTables in the Helm overlay, troubleshooter.allowed_tables in the VM configuration file) if live query text must never be visible in a session. The user holds per-table SELECT grants only, with no write, DDL, or admin privileges.
Read-only Kubernetes views on every provisioned deployment (access bundles are anchored to Kubernetes ServiceAccounts on both install targets): get, list, and watch on pods, pod logs, services, configmaps, events, PersistentVolumeClaims, deployments, statefulsets, and replicasets in the granted namespaces. Without a provisioned bundle, the troubleshooter refuses kubectl-type commands outright.

The troubleshooter’s RBAC contains no exec, delete, or patch permission, so operators cannot open a shell in your pods or change anything through the connector. The full grant and RBAC listing is in the privilege model reference.

Audit log

Every gateway call and every command executed during a session is appended to /var/log/clicklink/troubleshoot-audit.log as one JSON object per line (NDJSON). The submitted_by field records the identity behind each entry, and what that is depends on how the entry originated: gateway calls carry the email attested by the validated token, never a client-supplied value; session changes made locally on a VM record the invoking host user; and commands executed during a session record the org identity carried on the authenticated command channel. A gateway session-enable entry looks like this:

{
  "timestamp": "2026-06-22T22:30:00.123456789Z",
  "command_id": "11111111-2222-4333-8444-555555555555",
  "submitted_by": "operator@clickhouse.com",
  "command_type": "clctl.session.enable",
  "command_text": "ticket #1234",
  "instance_id": "",
  "status": "ok",
  "duration_ms": 42,
  "output_lines": 0,
  "remote_addr": "10.20.30.40"
}

Session lifecycle entries use the clctl.session.enable, clctl.session.disable, and clctl.session.status command types, with the enable --reason recorded as command_text; commands run during a session are logged with the same schema. status distinguishes successful calls from unauthorized, forbidden, and rate_limited attempts, so denied access shows up in the log too. On a VM, read the file directly with clicklink clctl troubleshoot audit tail. On Kubernetes the log lives inside the troubleshooter pod, and the container image has no shell, so invoke the binary’s own reader through kubectl exec:

CONNECTOR_NAMESPACE='clicklink'   # the connector namespace you chose at init
kubectl -n "${CONNECTOR_NAMESPACE}" exec statefulset/clicklink-connector-troubleshooter -- \
  /clicklink clctl troubleshoot audit tail

The log is a plain file inside your environment; ship it to your own SIEM like any other host or container log.

Redaction

Everything the troubleshooter returns is redacted before it leaves your environment. Built-in patterns cover IPv4 and IPv6 addresses, bearer tokens, AWS access keys, email addresses, JWTs, SSH private keys, and credentials embedded in connection strings. You can extend or override them in /etc/clicklink/redaction-patterns.yaml; an entry with the same name as a built-in replaces it. The daemon refuses to start on an invalid patterns file, and clicklink clctl preflight validates it, so a broken redaction configuration fails loudly instead of silently passing data through.

Architecture: every connection the connector makes and the data flow around sessions.
Configuration: gateway, allowlist, and redaction settings.
FAQ: revocation, auditing, and data-egress questions in brief.

ClickHouse Cloud

Bring Your Own Cloud

ClickHouse Private

What a support session is

Enabling and disabling sessions

Session expiry

Operator allowlist

What operators can do during a session

Audit log

Redaction

​What a support session is

​Enabling and disabling sessions

​Session expiry

​Operator allowlist

​What operators can do during a session

​Audit log

​Redaction

​Related pages

What a support session is

Enabling and disabling sessions

Session expiry

Operator allowlist

What operators can do during a session

Audit log

Redaction

Related pages