Role-Based Access Control

TrueNAS uses a role-based access control (RBAC) system to restrict which API methods a session may call. Roles are grouped into privileges, and privileges are linked to local or directory-service groups. When a user authenticates, the TrueNAS resolves that user’s group memberships to a set of active roles, which are then checked against every API call the user makes.

Privilege management is performed via the privilege.* API namespace (privilege.create, privilege.update, privilege.delete, privilege.query).

Role Concepts

Low-level roles (builtin=true)

Low-level roles are fine-grained roles attached directly to individual API methods. Examples: DISK_READ, SHARING_SMB_WRITE, ACCOUNT_READ. They are provided to allow selective expansion of access beyond what the high-level roles cover. Custom privileges can combine any set of these roles to grant precisely the access required for a given use case.

High-level roles (builtin=false)

High-level roles are the four top-level roles surfaced in the UI and API for privilege assignment:

• FULL_ADMIN

• READONLY_ADMIN

• SHARING_ADMIN

• REPLICATION_ADMIN

READONLY_ADMIN is the minimum role required for UI access. A privilege that grants only low-level roles — without including at least READONLY_ADMIN — will not be sufficient to log in to the web interface.

Use privilege.roles (filter builtin=false) to retrieve the current list of high-level roles at runtime.

Role inclusion

Roles can declare that they include other roles. Inclusion is expanded transitively, so a user assigned SHARING_ADMIN automatically gains all of the low-level roles that READONLY_ADMIN expands into, plus the additional write roles specific to sharing.

As a general convention, write roles include their corresponding read role. For example, ACCOUNT_WRITE includes ACCOUNT_READ, so granting write access to a subsystem always implies read access to that same subsystem.

Roles are additive and cannot be scoped down. There is no way to grant a role while simultaneously excluding a subset of what it includes — for example, it is not possible to assign FULL_ADMIN while blocking ACCOUNT_WRITE. If finer-grained control is required, build a custom privilege from individual low-level roles rather than starting from a broad high-level role.

High-Level Roles

Role	Description	Notable included roles
FULL_ADMIN	Unrestricted access to all API methods	All roles
READONLY_ADMIN	Read-only access across all subsystems	All *_READ low-level roles
SHARING_ADMIN	Manage datasets and all file-sharing protocols	READONLY_ADMIN + DATASET_WRITE + SHARING_WRITE + FILESYSTEM_ATTRS_WRITE + SERVICE_READ
REPLICATION_ADMIN	Manage replication, snapshots, and keychain credentials	KEYCHAIN_CREDENTIAL_WRITE + REPLICATION_TASK_CONFIG_WRITE + REPLICATION_TASK_WRITE + SNAPSHOT_TASK_WRITE + SNAPSHOT_WRITE

FULL_ADMIN

FULL_ADMIN grants unrestricted access to every API method. It cannot be scoped down — a session holding this role may call any method regardless of what other roles are present or absent.

The local root and truenas_admin accounts implicitly hold this privilege.

Under GPOS STIG mode, any method not covered by a role becomes unreachable for all users.

READONLY_ADMIN

READONLY_ADMIN expands into every *_READ low-level role defined in the system. A session with this role can call any *.query or *.get_instance endpoint and any other read-only method, but cannot create, update, or delete any resource or change any configuration.

This role corresponds to the built-in READONLY_ADMINISTRATOR privilege.

GPOS STIG has no effect on this role — all *_READ low-level roles are GPOS-available.

SHARING_ADMIN

SHARING_ADMIN is a superset of READONLY_ADMIN with additional write access scoped to storage and sharing:

• Create, update, and delete ZFS datasets

• Manage all file-sharing protocols: SMB, NFS, iSCSI, NVMe-oF, FTP, WebDAV

• Modify filesystem ACLs and other filesystem attributes

• Read service status (but not change service settings)

A session with SHARING_ADMIN cannot manage user accounts, system-level settings, network interfaces, storage pools, replication tasks, virtual machines, or applications.

This role corresponds to the built-in SHARING_ADMINISTRATOR privilege.

GPOS STIG has no effect on this role — all included roles are GPOS-available.

REPLICATION_ADMIN

REPLICATION_ADMIN provides write access to the replication subsystem:

• Replication tasks (push and pull)

• Periodic snapshot tasks

• ZFS snapshots

• Keychain credentials (SSH keypairs and cloud credentials used by replication)

A session with REPLICATION_ADMIN cannot manage datasets or pools directly, configure sharing protocols, manage user accounts, or change system settings.

There is no built-in local group for REPLICATION_ADMIN; it must be assigned through a custom privilege entry.

GPOS STIG has no effect on this role — all included roles are GPOS-available.

GPOS STIG Mode

When system.security has enable_gpos_stig=true, the GPOS STIG profile is active. Under this profile certain write roles become unavailable, meaning sessions that hold only those roles lose write access to the corresponding subsystems. The matching read roles remain available in all cases.

The stig field in privilege.roles output indicates which STIG profiles permit a role. A value of null means the role is not permitted under any STIG profile; a non-null value identifies the profile(s) that allow it.

Unavailable role(s)	Affected area
API_KEY_WRITE	API key management (API_KEY_READ still permitted)
VM_WRITE, VM_DEVICE_WRITE	Virtual machines
CONTAINER_WRITE, CONTAINER_DEVICE_WRITE, CONTAINER_IMAGE_WRITE, LXC_CONFIG_WRITE	Containers and LXC
DOCKER_WRITE	Docker back-end
APPS_WRITE, CATALOG_WRITE	Applications catalog
TRUECOMMAND_WRITE	TrueCommand integration
TRUENAS_CONNECT_WRITE	TrueNAS Connect cloud service

For FULL_ADMIN specifically, see the note in the FULL_ADMIN section above.

Managing Privileges

Use the following API methods to manage privileges:

• privilege.create — create a new privilege and link it to one or more local or directory-service groups

• privilege.update — modify an existing privilege (change roles or group membership)

• privilege.delete — remove a custom privilege

• privilege.query — list all privileges, including the three built-in ones

• privilege.roles — list all roles; pass [["builtin", "=", false]] as the filter argument to return only the high-level roles

• auth.me — returns the currently authenticated session, including the full list of roles that have been granted to it

Note

Enterprise license requirement. Linking a privilege to a directory-service group (Active Directory or LDAP group) requires an Enterprise license. On Community Edition, privileges can only be assigned to local Unix groups.

Note

Secret field redaction. API responses automatically redact fields marked secret in the schema (for example, credentials and passwords) for any session that does not hold the FULL_ADMIN role. Such fields are replaced with a redacted placeholder rather than being omitted, so the response structure remains consistent.