> ## Documentation Index > Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Support sessions > Enable, scope, audit, and revoke ClickHouse support access through the ClickHouse Connector export const Image = ({img, alt, size = "lg", background}) => { const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg"; const backgroundColor = background === "white" ? "white" : background === "black" ? "rgb(31 31 28)" : undefined; return
{alt}
; }; 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. ClickHouse Connector support session trust flow 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

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: ```bash theme={null} 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: ```bash theme={null} clicklink clctl troubleshoot session enable \ --gateway-url http://localhost:8443 \ --duration 4h \ --reason "" ``` Check or end it the same way: ```bash theme={null} 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](/docs/products/bring-your-own-cloud/connector/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: ```bash theme={null} sudo clicklink clctl troubleshoot session enable --duration 4h --reason "" 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: ```bash theme={null} clicklink clctl troubleshoot gateway trust \ --gateway-url https://:8443 \ --gateway-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](/docs/products/bring-your-own-cloud/connector/reference/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: ```json theme={null} { "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`: ```bash theme={null} 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](/docs/products/bring-your-own-cloud/connector/architecture): every connection the connector makes and the data flow around sessions. * [Configuration](/docs/products/bring-your-own-cloud/connector/configuration): gateway, allowlist, and redaction settings. * [FAQ](/docs/products/bring-your-own-cloud/connector/reference/faq): revocation, auditing, and data-egress questions in brief.