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

Individual roles (builtin=true)

Individual 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 predefined group roles cover. Custom privileges can combine any set of these roles to grant precisely the access required for a given use case.

Predefined group roles (builtin=false)

Predefined group 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 individual 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 predefined group 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 individual 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 roles rather than starting from a broad predefined group role.

Predefined Group 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 individual 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 individual 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 individual 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, WebShare

• 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.

Individual Roles Reference

The table below lists all individual roles available for use in custom privileges. Roles marked unavailable under STIG cannot be granted to any session when system.security has enable_gpos_stig=true.

Subsystem	Roles	Notes
Local Accounts	ACCOUNT_READ, ACCOUNT_WRITE
API Keys	API_KEY_READ, API_KEY_WRITE	API_KEY_WRITE unavailable under STIG
Auth Sessions	AUTH_SESSIONS_READ, AUTH_SESSIONS_WRITE
Boot Environments	BOOT_ENV_READ, BOOT_ENV_WRITE
Certificates	CERTIFICATE_READ, CERTIFICATE_WRITE
Cloud Backup	CLOUD_BACKUP_READ, CLOUD_BACKUP_WRITE
Cloud Sync	CLOUD_SYNC_READ, CLOUD_SYNC_WRITE
Containers / LXC	CONTAINER_READ, CONTAINER_WRITE, CONTAINER_DEVICE_READ, CONTAINER_DEVICE_WRITE, CONTAINER_IMAGE_READ, CONTAINER_IMAGE_WRITE, LXC_CONFIG_READ, LXC_CONFIG_WRITE	All *_WRITE roles unavailable under STIG
Dataset	DATASET_READ, DATASET_WRITE, DATASET_DELETE
Directory Services	DIRECTORY_SERVICE_READ, DIRECTORY_SERVICE_WRITE
Disk	DISK_READ, DISK_WRITE
Apps / Docker	APPS_READ, APPS_WRITE, CATALOG_READ, CATALOG_WRITE, DOCKER_READ, DOCKER_WRITE	All *_WRITE roles unavailable under STIG
Enclosure / JBOF	ENCLOSURE_READ, ENCLOSURE_WRITE, JBOF_READ, JBOF_WRITE
Failover	FAILOVER_READ, FAILOVER_WRITE
Filesystem	FILESYSTEM_ATTRS_READ, FILESYSTEM_ATTRS_WRITE, FILESYSTEM_DATA_READ, FILESYSTEM_DATA_WRITE, FILESYSTEM_FULL_CONTROL
IPMI	IPMI_READ, IPMI_WRITE
Keychain Credentials	KEYCHAIN_CREDENTIAL_READ, KEYCHAIN_CREDENTIAL_WRITE
KMIP	KMIP_READ, KMIP_WRITE
Mail	MAIL_WRITE
Network	NETWORK_GENERAL_READ, NETWORK_GENERAL_WRITE, NETWORK_INTERFACE_READ, NETWORK_INTERFACE_WRITE
Pool	POOL_READ, POOL_WRITE, POOL_SCRUB_READ, POOL_SCRUB_WRITE
Privilege	PRIVILEGE_READ, PRIVILEGE_WRITE
Replication	REPLICATION_TASK_CONFIG_READ, REPLICATION_TASK_CONFIG_WRITE, REPLICATION_TASK_READ, REPLICATION_TASK_WRITE, REPLICATION_TASK_WRITE_PULL
Reporting	REPORTING_READ, REPORTING_WRITE
Services	SERVICE_READ, SERVICE_WRITE
Sharing — FTP	SHARING_FTP_READ, SHARING_FTP_WRITE
Sharing — iSCSI	SHARING_ISCSI_READ, SHARING_ISCSI_WRITE, SHARING_ISCSI_AUTH_READ, SHARING_ISCSI_AUTH_WRITE, SHARING_ISCSI_EXTENT_READ, SHARING_ISCSI_EXTENT_WRITE, SHARING_ISCSI_GLOBAL_READ, SHARING_ISCSI_GLOBAL_WRITE, SHARING_ISCSI_HOST_READ, SHARING_ISCSI_HOST_WRITE, SHARING_ISCSI_INITIATOR_READ, SHARING_ISCSI_INITIATOR_WRITE, SHARING_ISCSI_PORTAL_READ, SHARING_ISCSI_PORTAL_WRITE, SHARING_ISCSI_TARGET_READ, SHARING_ISCSI_TARGET_WRITE, SHARING_ISCSI_TARGETEXTENT_READ, SHARING_ISCSI_TARGETEXTENT_WRITE
Sharing — NFS	SHARING_NFS_READ, SHARING_NFS_WRITE
Sharing — NVMe-oF	SHARING_NVME_TARGET_READ, SHARING_NVME_TARGET_WRITE
Sharing — SMB	SHARING_SMB_READ, SHARING_SMB_WRITE
Sharing — WebShare	SHARING_WEBSHARE_READ, SHARING_WEBSHARE_WRITE
Sharing (aggregate)	SHARING_READ, SHARING_WRITE	Each expands into all SHARING_*_READ / SHARING_*_WRITE roles
Snapshots	SNAPSHOT_READ, SNAPSHOT_WRITE, SNAPSHOT_DELETE, SNAPSHOT_TASK_READ, SNAPSHOT_TASK_WRITE
SSH	SSH_READ, SSH_WRITE
Support	SUPPORT_READ, SUPPORT_WRITE
System Audit	SYSTEM_AUDIT_READ, SYSTEM_AUDIT_WRITE
System Settings	SYSTEM_ADVANCED_READ, SYSTEM_ADVANCED_WRITE, SYSTEM_CRON_READ, SYSTEM_CRON_WRITE, SYSTEM_GENERAL_READ, SYSTEM_GENERAL_WRITE, SYSTEM_PRODUCT_READ, SYSTEM_PRODUCT_WRITE, SYSTEM_SECURITY_READ, SYSTEM_SECURITY_WRITE, SYSTEM_TUNABLE_READ, SYSTEM_TUNABLE_WRITE, SYSTEM_UPDATE_READ, SYSTEM_UPDATE_WRITE
TrueCommand	TRUECOMMAND_READ, TRUECOMMAND_WRITE	TRUECOMMAND_WRITE unavailable under STIG
TrueNAS Connect	TRUENAS_CONNECT_READ, TRUENAS_CONNECT_WRITE	TRUENAS_CONNECT_WRITE unavailable under STIG
Virtual Machines	VM_READ, VM_WRITE, VM_DEVICE_READ, VM_DEVICE_WRITE	All *_WRITE roles unavailable under STIG
ZFS Resources (filesystems, zvols)	ZFS_RESOURCE_READ, ZFS_RESOURCE_WRITE, ZFS_RESOURCE_DELETE

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 predefined group 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.