Remote access permissions¶

The remote-access:connect permission supports fine-grained restrictions that limit which types of remote access (console, tunnel, file transfer, agent reload) a role can use, and on which devices. This page documents the resource action format used to configure these restrictions.

For an introduction to roles and resource-based access, see Users and Roles. For step-by-step instructions, see Configure Remote Access.

When to use fine-grained permissions

Fine-grained permissions are useful when you want to give a role partial remote access to specific devices. For example, granting a CI/CD pipeline only the ability to trigger agent runs, or letting a support engineer open a console without the ability to transfer files.

Resource action format¶

Resources for the remote-access:connect permission follow this grammar:

<entity>[/<action>(<option1>=<value1>;<option2>=<value2>)]

Part	Values
`entity`	`*` (all devices), `node:<node-id>`, or `tag:<tag-name>`
`action`	`tunnel`, `console`, `reload`, or `copy`
`options`	Key=value pairs separated by `;` (specific to each action)

The action and options are optional. If you omit them (no / in the resource), the role gets full remote access on the matching devices.

Backward compatibility¶

Existing roles continue to work without modification:

A resource without an action (for example, * or tag:my-devices) grants all remote access types on the matching devices.
An empty action with no options is equivalent to no action at all.
Roles created before fine-grained permissions were introduced retain their original behavior.

Supported actions¶

Action	Options	Description
`tunnel`	`proto`, `port`, `dst`	Network tunneling (TCP and UDP)
`console`	none	Terminal/PTY access
`reload`	none	Force the agent to run
`copy`	`direction`, `path`	File upload and download

The console and reload actions do not accept options. Including options on these actions makes the resource invalid.

Tunnel options¶

The tunnel action restricts network tunneling. All options are optional and can be combined.

Option	Valid values	Example
`proto`	`tcp` or `udp`	`tunnel(proto=tcp)`
`port`	A single port, an inclusive range, or a comma-separated list	`tunnel(port=80,443,8000-9000)`
`dst`	A hostname or IP address	`tunnel(dst=localhost)`

Port specifications support:

Single port: port=80
Inclusive range: port=8000-9000 (matches 8000 through 9000)
Comma-separated list: port=80,443,8000-9000

You can combine options with ;:

tunnel(proto=tcp;port=80,443)

This restricts tunneling to TCP connections targeting ports 80 or 443.

Copy options¶

The copy action restricts file transfers.

Option	Valid values	Example
`direction`	`up` or `down`	`copy(direction=up)`
`path`	A path prefix string	`copy(path=/var/backup)`

direction=up allows uploads to the device only.
direction=down allows downloads from the device only.
path matches files whose path starts with the given prefix. For example, path=/home/user allows transferring /home/user/file.txt but not /etc/passwd.

You can combine options:

copy(direction=down;path=/var/backup)

This allows download-only access to files under /var/backup.

Wildcard and hybrid patterns¶

The wildcard (*) entity matches all devices and can be combined with actions or mixed with specific resources in the same permission.

Wildcard with action restriction¶

Pattern	Effect
`*`	All devices, all remote access types
`*/tunnel`	All devices, tunneling only
`*/console`	All devices, console access only

Mixing wildcards with specific resources¶

You can combine multiple resources in the same permission to grant different access levels to different devices:

Resources	Effect
`*/console`, `tag:dev`	Console on all devices; full remote access on `dev`-tagged devices
`tag:prod/tunnel(port=443)`, `tag:dev`	Port 443 tunnels on `prod` devices; full access on `dev` devices
`*/reload`, `tag:support/console`	Reload on all devices; console on `support`-tagged devices

When multiple resources match the same device, the union of their actions applies.

Example role configurations¶

The following examples show the resource string you would set on the remote-access:connect permission for common scenarios.

Web developer¶

Allows TCP tunneling to web ports on all devices, but no console, file transfer, or reload access.

*/tunnel(proto=tcp;port=80,443)

Support agent¶

Allows console-only access to production devices.

tag:prod/console

CI/CD pipeline¶

Allows triggering agent runs on all devices, but no other remote access.

*/reload

Backup operator¶

Allows downloading files from a specific path on backup-tagged devices.

tag:backup/copy(direction=down;path=/var/backup)

Full access¶

The wildcard pattern grants all remote access types on all devices.

Access denied behavior¶

When a user attempts a remote access action that is not permitted by their role, the request is denied.

Audit trail¶

Remote access events are recorded in the audit log.