Access control in overpass has two layers: rules (what you can manage in the web UI/API) and node access (which logins you may use on which servers).

Roles

A role has four parts:

Field	Meaning
logins	unix usernames this role may use on nodes
node_labels	a label selector — which nodes the role's logins apply to
rules	management permissions (see below)

A user has one or more roles and may also carry direct logins.

Administrators can also configure a cluster-wide default login set in Settings → General. These logins are added to every user's effective logins, but only within the node selectors already granted by that user's roles. They do not grant node access on their own, and an empty set changes nothing.

How node access is computed

When a user logs in, overpass builds one access group per role: it pairs the role's logins (plus the user's direct and cluster-default logins) with that role's node-label selector, and signs the set into the user's certificate. At connection time the node accepts a login only if some access group both lists that login and has a selector that matches the node's labels.

• An empty selector matches every node.
• A selector like env: prod matches only nodes labeled env=prod.

Note

Example. A prod role with logins: [deploy] and node_labels: {env: prod} lets its members SSH as deploy to nodes labeled env=prod — and nowhere else. Give a separate dev role node_labels: {env: dev} and the two never overlap, even for a user who holds both.

Enforcement is fail-closed and happens at the node: the proxy never makes the decision, and a node with no matching access group refuses the connection.

Management rules

Rules gate the web UI and REST/gRPC management API:

Rule	Grants
manage_users	create/delete users; lock accounts; view the audit log and every active session
manage_roles	create/edit/delete roles
manage_nodes	delete nodes; isolate nodes; view active sessions on nodes the role reaches
manage_tokens	create/revoke join tokens (and use the Add server wizard)
edit_config	manage OIDC connectors
terminal	use the browser terminal, and browse/upload/download files on a node

terminal covers file transfer as well as shells: anyone who can open a shell as a login can already read and write that login's files, so the two are the same grant.

Immediate lockout

Certificates are self-contained, so an issued one stays cryptographically valid until it expires — deleting or editing an account does not, by itself, stop a session already in flight. Two actions close that gap:

• Lock an account (Users → Lock account). Sign-in is refused, existing web and CLI sessions are revoked, live node sessions are cut, and the locked user set is pushed to every connected node so certificates they already hold are rejected there too. Nodes that are offline receive it when they reconnect, and nodes running an agent that predates this frame ignore it — so during a partial upgrade, lock plus certificate expiry remains the backstop.
• Isolate a node (Servers → Isolate server). Live sessions are cut, the tunnel is dropped, and further reconnection attempts are refused until access is restored. The agent keeps running and nothing on the server is changed.

Active sessions lists everything the control plane is currently carrying — user, server, unix login, connection type and start time — and a session can be terminated on its own without locking anyone. The list is live only; the durable record is the audit log.

Default roles

Two built-in roles always exist — they can be overridden but never deleted, so a bad edit can never lock every operator out:

• admin — all rules, empty selector → manage everything and reach every node (with the logins on the user/role).
• access — the terminal rule only, empty selector.

To restrict who reaches what, create roles with non-empty node_labels selectors and assign them instead of admin. Edit roles in the web UI under Roles or with opctl roles — those persist in the server-managed config directory — or declare them under roles: in overpass.yaml, where they are authoritative and read-only in the UI:

roles:
  - name: sre
    logins: [root, deploy]
    node_labels: { env: prod }
    rules: { manage_nodes: true, manage_tokens: true, terminal: true }