Support sessions

A support session grants ClickHouse temporary diagnostic access through the ClickHouse Connector. This page covers what a session is, how to enable and disable one, what ClickHouse support engineers can do during one, and how to audit it.

What a support session is

A support session is a time-boxed window in which the troubleshooter accepts commands from ClickHouse support engineers. Outside a session it refuses every command, even while its outbound WebSocket is connected. There is no other execution path, and ClickHouse cannot open a session for you. ClickHouse Cloud never connects into your environment; it receives only what the troubleshooter sends over its outbound channel. Sessions govern diagnostics only. Lifecycle commands for services in managed mode travel over the executor’s separate channel, which a support session neither opens nor gates; see managed services. You control sessions through two surfaces:

The session gateway, an authenticated API embedded in the troubleshooter. It serves POST /v1/clctl/session/enable, POST /v1/clctl/session/disable, and GET /v1/clctl/session/status. Every call requires a short-lived OIDC ID token whose email is on your operator allowlist.
The local session file on Linux VM installs, written 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; you reach it 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. With cluster access, reach it over a port-forward:

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 gateway logs the attempt. To let operators work without cluster credentials, expose the gateway through the chart’s opt-in Ingress, which terminates TLS with a CA-issued certificate; see configuration.

With root access on the host, manage the session directly. The daemon and the CLI read and write the state file /var/lib/clicklink/session.json 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. A connection fails closed when the presented certificate does not match it. If the gateway serves a certificate from your own CA instead, pass that CA bundle with --gateway-ca on each session command.

Session expiry

Sessions expire on their own. The default duration is 4 hours; session enable --duration accepts up to 24 hours. At expiry, or the moment you run session disable, the troubleshooter stops accepting commands. Disabling revokes access immediately: no restart, and no coordination with ClickHouse.

Operator allowlist

Every gateway call is authorized against an allowlist of operator emails. The match uses the email attested by the validated OIDC token, never a value the client supplies.

Kubernetes: set clctl.gateway.allowedOperators in your values overlay. The chart renders the list into a ConfigMap, 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.

On both targets the gateway re-reads the file on the next request once 30 seconds have passed since the last read. Edits take effect without a restart.

What operators can do during a session

While a session is active, ClickHouse support engineers can run two kinds of command. Read-only SQL runs against your clusters as the pcm_troubleshooter user, whose grants are limited to the session table allowlist. The troubleshooter also rejects any statement that does not start with SELECT, WITH, SHOW, DESCRIBE, or EXPLAIN. The user holds per-table SELECT grants only, with no write, DDL, or admin privileges. The default allowlist covers system tables such as system.parts, system.merges, system.replicas, system.metrics, and system.settings. system.query_log and system.text_log cannot be added to it: the daemon refuses a configuration that lists them, so no grant on them is ever provisioned. The default allowlist does include system.processes, whose query column shows the text of running statements. Remove it from troubleshooter.allowedTables (Helm overlay) or troubleshooter.allowed_tables (VM configuration file) if live query text must never be visible in a session. Read-only Kubernetes views are get, list, and watch on pods, pod status, pod logs, services, configmaps, events, PersistentVolumeClaims, deployments, statefulsets, and replicasets in the granted namespaces. Access bundles are anchored to Kubernetes ServiceAccounts on both install targets. Without a provisioned bundle, the troubleshooter refuses kubectl-type commands outright. The executor provisions the scraper for a managed service but not the troubleshooter; see support sessions for a managed service. The troubleshooter’s RBAC contains no exec, delete, or patch permission, so operators cannot open a shell in your pods or change anything through a session. The full grant and RBAC listing is in the privilege model reference.

Audit log

Every command executed during a session is appended to /var/log/clicklink/troubleshoot-audit.log as one JSON object per line (NDJSON). Blocked commands are recorded too, with blocked_by naming the reason (for example session inactive). submitted_by is the organization ID on the command channel: your own org ID. The individual ClickHouse engineer is recorded on the ClickHouse Cloud side, not in this file. A session-command entry looks like this:

{
  "timestamp": "2026-06-22T22:30:00.123456789Z",
  "command_id": "11111111-2222-4333-8444-555555555555",
  "submitted_by": "<org-id>",
  "command_type": "sql",
  "command_text": "SELECT database, table, active, count() FROM system.parts GROUP BY ALL",
  "instance_id": "analytics",
  "status": "completed",
  "duration_ms": 42,
  "output_lines": 12
}

status carries the command outcome: completed, error, or rejected. Gateway calls are logged separately. Every call, including rejected ones, is emitted as a structured clctl.gateway line in the troubleshooter’s own log: the journal on a VM, the container log on Kubernetes. The line carries submitted_by (the email attested by the validated token, never a client-supplied value) and command_type (clctl.session.enable, clctl.session.disable, or clctl.session.status). It also carries reason (the enable --reason), remote_addr, and status. status is ok, unauthorized, forbidden, rate_limited, bad_request, conflict, or error, so denied access shows up in the log too. Local session changes on a VM are not audit-log entries. The invoking host user is recorded as enabled_by in /var/lib/clicklink/session.json and shown by session status. On a VM, read the audit log 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 audit 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.

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.

Get started

Services and infrastructure

Bring Your Own Cloud

Data and integrations

Connect and query

Access management

Security and compliance

Monitoring and backups

AI tools and agents

Cloud API

Billing

Support

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