Skip to content

Managing Client Proxies

A client proxy is a Teleport agent installed at a customer site. It connects outbound (443) to the Teleport cluster and exposes the customer's Windows / Active Directory servers over RDP. The Client proxies page (group of the same name) lists all connected agents. The Dashboard gives the summary: status banner, "To do" list and the cards Proxies online, Proxies offline, Proxies locked, Proxies to update.

Tenantry manages no users: access is through a single administrator credential or Teleport SSO.

Reading the page

The data comes from the real tctl: agents (tctl inventory ls), Windows desktops (tctl desktop ls), locks (tctl get locks). Filters: All proxies, Online, Unreachable, Locked, Update needed.

  • Windows servers: number of Windows desktops served by this proxy.
  • Client: read from the desktops' labels.
  • Version: compared with the cluster's (see "Version gap").

The count cards always describe the rows the table can show: client proxies only by default, every node (or the selected type) once Show all nodes is ticked. A card and its filter use the same rule (a locked node is never counted Online).

  • Sort: click a column header (ascending, descending, then back to the default order).
  • Group by client: one block per client_code label, nodes without a code last.
  • Export inventory (CSV): one line per Windows desktop of the listed proxies (a proxy without desktops still gets one line). Cells are neutralised against spreadsheet formula injection, like the audit export. The desktop list comes from GET /api/nodes/inventory, audited as nodes.export.
  • Updated N s ago: age of the data (generatedAt of the API, cached at most a few seconds).
  • Connect (proxy details, per desktop): opens the Teleport web UI on that desktop, where you pick the Windows login. The link is built from the configured proxy address (DEFAULT_PROXY_ADDR) and the cluster name; it is hidden when either is unknown or still the placeholder (*.example.com).

Every view has its own URL, so it can be bookmarked or shared:

URL Shows
/proxies/<node id> The details of that proxy (the filters of the query string are kept when it is closed).
/proxies?status=down Status filter: online, down, locked, outdated.
?q=acme Search on client name, client code or host name.
?all=1&kind=auth Every node, optionally one type (gateway, proxy, auth, app, ssh, other).
?sort=version&dir=desc Sort column (client, status, version, desktops) and direction.
?group=client Grouped by client.

The dashboard uses them: each To do item opens its proxy, each count card the matching filtered list.

Statuses

The status depends on the agent's last sign of life (last_seen).

Displayed status Rule Meaning
Online seen 5 min ago or less The agent responds normally.
Slow to respond seen more than 5 min and at most 20 min ago Short outage or overloaded agent: keep an eye on it.
Unreachable seen more than 20 min ago, or date missing / unreadable The agent no longer talks to the cluster: see the checklist.
Locked an active lock targets this node Independent of the network status.

A date in the future (clock skew) counts as recent.

Locking a proxy

A Teleport lock (tctl lock --server-id) immediately cuts the connections going through this node. Use it for: a compromised customer, a suspicious gateway, a maintenance that requires no session to remain open.

  • Administrators only; the action is audited (node.lock, node.unlock).
  • Duration: 1, 4, 12, 24 (default), 72, 168 h, or no explicit expiry; message of 200 characters maximum.
  • Refused (409 protected_node) for a node that runs Auth or Proxy (reason: protected_service) or whose type cannot be locked (reason: unsupported_kind, e.g. Kubernetes); the audit entry is denied with the same code.
  • If Teleport's cache is lagging, the response carries pending:true: refresh after a few seconds.
  • Unlock removes all active locks on the node.

This is a deliberate service disruption: see security, section 8.3.

Adding a proxy

Add a client proxy menu: two wizards.

The new proxy appears in the list as soon as its agent has joined the cluster.

Checklist after adding a proxy:

  • [ ] The proxy is listed and reachable.
  • [ ] The join token was revoked automatically (guided install: "Join token revoked"; Steward via a proxy: shown after the verification). Otherwise: tctl tokens ls, then tctl tokens rm <token>.
  • [ ] The audit shows token.revoke with outcome=ok for this deployment.

A proxy is "unreachable": what to check

  1. Agent running at the customer site: systemctl status teleport (or the Windows service), journalctl -u teleport -n 100.
  2. Outbound 443 to the cluster's public address (no firewall or proxy blocking): curl -v https://<cluster>:443/webapi/ping.
  3. Clock: a skew of more than a few minutes causes TLS failures; enable NTP on both sides.
  4. Expired token: a join token has a limited lifetime; an agent that never joined, or whose identity has expired, must rejoin with a new token (regenerate the deployment).
  5. Update: teleport-update status; if the agent stayed on a version that is too old or the update failed, run teleport-update update again.
  6. Last resort: reinstall the agent with a new token.

Version gap

A proxy is marked Update needed when its version is lower than the cluster's. Teleport tolerates an agent one major version behind, never ahead: update the agents before they drift. With teleport-update the update is automatic; otherwise, reinstall the package matching the cluster version at the customer site.

The dashboard card Agent auto-updates and the line next to Update needed in a proxy's detail show the cluster rollout, read-only (GET /api/teleport/autoupdate): mode (autoupdate_config), target version (autoupdate_version), strategy, rollout state and the state of each update group (autoupdate_agent_rollout). A proxy whose group (client-<code>) is not scheduled is never updated automatically: add the group to the schedule (see the Steward / gateway bundles) or update it by hand. A missing autoupdate_config or autoupdate_version resource is reported as a warning.

Troubleshooting

Symptom Likely cause Action
"Could not load the proxies." / "Tenantry's Teleport credentials have expired" (502 teleport_credentials_expired) --auth identity: the tctl identity file has expired (TTL of tctl auth sign). --auth machine-id: tbot stopped renewing it --auth identity: generate a new file and replace the one mounted in Tenantry, without restart; the dashboard warns 24 h ahead. Better: switch to --auth machine-id (Install options, recommended). --auth machine-id: restart tbot and read its logs (Troubleshooting); the dashboard warns as soon as a renewal is missed.
502 teleport_access_denied ("Tenantry's role is not allowed to ... on ...") Tenantry role is missing a rule Regenerate Tenantry role (Steward page, "Generated files").
502 teleport_unavailable error tctl cannot read the cluster tctl status in the container; valid identity (Troubleshooting).
Lock refused, 403 Read-only technician on this client (insufficient_level) Operator level on the client (Technicians) or an administrator.
502 lock_failed Tenantry role without create + update on lock Regenerate the role with locking (snippet below).
Proxies visible but 0 desktops Role without windows_desktop_labels Add the selector below.
Lock set, state unchanged Teleport cache lagging (pending:true) Refresh after a few seconds.
409 protected_node Auth or Proxy node Do not lock it.
Proxy "unreachable" although it works Agent or cluster clock skewed NTP on both sides.

Required identity role

With Machine ID, this is the role of the tenantry bot (tctl bots add tenantry --roles=tenantry); the Security page generates it with the "Fleet locking" switch. For fleet management, Tenantry identity's role (generated with locking enabled) must contain, in addition to the Steward permissions:

spec:
  allow:
    # Teleport filters desktop lists by this selector. WITHOUT windows_desktop_logins:
    # visibility (count per proxy), no RDP access.
    windows_desktop_labels:
      '*': '*'
    rules:
      - resources: [lock]
        verbs: [list, read, create, update, delete]   # create also requires update (verified, Teleport 18.2)
      - resources: [instance, windows_desktop_service, windows_desktop]
        verbs: [list, read]

Wherever Tenantry creates join tokens (guided Windows deployment, client proxy for Steward), it also revokes them once they have done their job, so the role needs:

      - resources: [token]
        verbs: [list, read, create, delete]   # delete: automatic revocation (tctl tokens rm)

Without delete, the revocation fails: the UI shows the manual command and the audit records token.revoke with outcome=error; the token then lives until its TTL.

Creating locks can disrupt the cluster: enable this role only with a short-lived credential. See security 8.3 and Steward integration.