TrueNASTrueNAS Nightly Development Documentation
This content follows experimental nightly development software. Pre-release software is intended for testing purposes only.
Use the Product and Version selectors above to view content specific to a stable software release.

Permissions

TrueNAS offers two Access Control List (ACL) types: POSIX (the TrueNAS default) and NFSv4. For a more in-depth explanation of ACLs and configurations in TrueNAS, see our ACL Primer.

The Dataset Preset option on the Add Dataset screen sets the ACL type applied for SMB shares, apps, multi-protocol shares, and general-use datasets.

The ACL Type setting in the Advanced Options on both the Add Dataset and Edit Dataset screens, determines the ACL presets available on the ACL Select a preset ACL window. It also determines which permissions editor screens you see after you click the edit edit icon on the Dataset Permissions widget.

Set ACL Type to NSFv4 to activate and select which ACL Mode the dataset uses.

While creating an ACL, users can choose to skip an execution check. We only recommend skipping execution checks for users who need to join their Microsoft Active Directory to a TrueNAS system.

Unix Permissions Editor Screen

If you set Dataset Preset to Generic, or selected POSIX or Inherit as the ACL Type settings on the Add Dataset > Advanced Options screen, the first screen you see after clicking Edit on the Permissions widget is the Dataset > Edit Permissions screen Unix Permissions Editor.

Unix Permissions Editor
Figure 1: Unix Permissions Editor

Use the settings on this screen to configure basic ACL permissions.

POSIX ACL Owner Settings

The Owner section controls which TrueNAS user and group has full control of this dataset.

SettingDescription
UserEnter or select a user to control the dataset. Users created manually or imported from a directory service appear in the menu.
Apply UserSelect to confirm user changes. To prevent errors, TrueNAS only submits changes after you select this option.
GroupEnter or select the group to control the dataset. Groups created manually or imported from a directory service appear in the menu.
Apply GroupSelect to confirm group changes. To prevent errors, TrueNAS only submits changes after you select this option.

POSIX ACL Access Settings

The Access section lets users define the basic Read, Write, and Execute permissions for the User, Group, and Other accounts that might access this dataset.

A common misconfiguration is removing the Execute permission from a dataset that is a parent to other child datasets. Removing this permission results in lost access to the path.

POSIX ACL Advanced Settings

The Advanced section lets users Apply Permissions Recursively to all directories, files, and child datasets within the current dataset.

To access advanced POSIX ACL settings, click Add ACL on the Unix Permissions Editor. The Select a preset ACL window displays with two radio buttons.

Select an ACL Preset

There are two different Select a preset ACL windows, one for the POSIX ACL and the other for the NFSv4 ACL. Selecting a preset replaces the ACL currently displayed on the Edit ACL screen and deletes any unsaved changes.

For a POSIX ACL, a window with three setting options displays before you see the Edit ACL screen. These setting options allow you to select and use a pre-configured set of permissions that match general permissions situations or to create a custom set of permissions. You can add to a pre-configured ACL preset on the Edit ACL screen.

POSIX Select a Preset ACL
Figure 2: POSIX Select a Preset ACL

For an NFSv4 ACL, click Use Preset ACL on the Edit ACL screen to access the NFS4 Select a Preset ACL window.

NFS4 Select a Preset ACL
Figure 3: NFS4 Select a Preset ACL

The ACL Type setting determines the pre-configured options presented on the Default ACL Options dropdown list on each of these windows. For POSIX, the options are POSIX_OPEN, POSIX_RESTRICTED, or POSIX_HOME. For NFSv4, the options are NFS4_OPEN, NFS4_RESTRICTED, NFS4_HOME, and NFS4_DOMAIN_HOME.

SettingDescription
Select a preset ACLClick to populate the Default ACL Options dropdown list with pre-configured POSIX permissions.
Create a custom ACLClick to open the Edit ACL screen with no default permissions, users, or groups or to configure your own set of permissions. Click Continue to display the Edit ACL screen.

The Edit ACL screen options are based on ACL type (POSIX or NFSv4). The Dataset Preset and ACL Type settings determine the ACL type. They are under Advanced Options in the Add Dataset and Edit Dataset screens

The section below describes the differences between screens for each ACL type.

ACL Editor Settings - POSIX and NFSv4

Select any user account or group manually entered or imported from a directory service in the Owner or Owner Group. The value entered or selected in each field displays in the Access Control List below these fields.

Dataset displays the dataset path (name) you selected to edit.

ACL Editor Owner Settings
Figure 4: ACL Editor Owner Settings

Access Control List - POSIX and NFS4

The Access Control List section displays the items and a permissions summary for the owner@, group@, and everyone@ for both POSIX and NSFv4 ACL types. The list of items changes based on a selected pre-configured set of permissions.

To add a new item to the ACL, click Add Item, define Who the Access Control Entry (ACE) applies to, and configure permissions and inheritance flags for the ACE.

Edit ACL Functions - POSIX and NFS4

These functions display on the Edit ACL screen for both POSIX and NSFv4 ACL types except for Strip ACL, which only displays for NSFv4 types.

NFS4 Edit ACL Screen
Figure 5: NFS4 Edit ACL Screen
Edit ACL Settings
SettingDescription
Add ItemAdds a new ACE to the Access Control List.
Apply permissions recursivelySelect to apply all settings or changes on the Edit ACL screen to all child datasets in the path in Dataset.
Save Access Control ListSaves settings or changes made on the Edit ACL screen.
Strip ACL(NSFv4 only) Remove all ACLs from the current dataset and any directories or files contained within this dataset. Stripping the ACL resets dataset permissions and can make data inaccessible until you create new permissions.
Permissions Editor(POSIX only) Displays the Unix Permissions Editor screen for POSIX ACL types.
Use PresetDisplays the Select a preset ACL window. If the ACL Type setting, found in the Advanced Options of both the Add Dataset and Edit Dataset screens, is POSIX or Inherit, the Default ACL Options dropdown displays POSIX pre-configured options. If set to NFSv4, the preset options displayed are pre-configured NSFv4 options.
Save As PresetSaves the current access control list as a custom preset and adds it to the Access Control List.

POSIX Access Control Entry Settings

The POSIX Access Control Entry settings include Who, Permissions, and Flags options.

POSIX Access Control Entry Settings
Figure 6: POSIX Access Control Entry Settings
POSIX ACE Settings
SettingDescription
WhoSelect the user or group from the dropdown list the permissions apply to.

User denotes access rights for users identified by the entry qualifier.
Group denotes access rights for the filegroup.
Other denotes access rights for processes that do not match any other entry in the ACL.
Group Obj denotes access rights for the filegroup.
User Obj denotes access rights for the file owner.
Mask denotes the maximum access rights User, Group Obj, or Group type entries can grant.
PermissionsSelect the checkbox for each permission type (Read, Write and Execute) to apply to the user or group in Who.
FlagsSelect the Default option to include a flag setting for the user or group in Who.

NFS4 Access Control Entry Settings

There are two Access Control Entry settings, Who and ACL Type.

The NFSv4 ACL Type radio buttons change the Permissions and Flags setting options. Select Allow to grant the specified permissions or Deny to restrict the permissions for the user or group in Who.

NSFv4 Access Control Entry Settings
Figure 7: NSFv4 Access Control Entry Settings
NFS ACE Settings
SettingDescription
WhoAccess Control Entry (ACE) user or group. Select a specific User or Group for this entry. See nfs4_setfacl(1) NFSv4 ACL ENTRIES.

User denotes access rights for users identified by the qualifier.
Group denotes access rights for groups identified by the qualifier.
owner@ applies this entry to the user that owns the dataset.
group@ applies this entry to the group that owns the dataset.
everyone@ applies this entry to all users and groups.
ACL TypeDetermines how the Permissions apply to the chosen Who. Choose Allow to grant the specified permissions and Deny to restrict the specified permissions.

NFS4 Permissions and Flags

TrueNAS divides permissions and inheritance flags into basic and advanced options. The basic permissions options are commonly-used groups of advanced options. Basic inheritance flags only enable or disable ACE inheritance. Advanced flags offer finer control for applying an ACE to new files or directories.

Basic Permissions Settings

Click the Basic radio button to display the Permissions dropdown list of options that applies to the user or group in Who.

NSFv4 Basic Permissions Options
Figure 8: NSFv4 Basic Permissions Options
NFSv4 Basic Permissions Settings
PermissionCLI CommandDescription
Readr-x---a-R-c---View file or directory contents, attributes, named attributes, and ACL.
ModifyrwxpDdaARWc--sAdjust file or directory contents, attributes, and named attributes. Create new files or subdirectories. Includes the Traverse permission.
Traverse--x---a-R-c---Execute a file or move through a directory.
Full ControlrwxpDdaARWcCosApply all permissions.

Advanced Permissions Settings

Click the Advanced radio button to display the Permissions options for the user or group in Who.

NSFv4 Advanced Permissions Options
Figure 9: NSFv4 Advanced Permissions Options
NFSv4 Advanced Permisions Settings
PermissionCLI CommandDescription
Read DatarView file contents or list directory contents.
Write DatawCreate new files or modify any part of a file.
Append DatapAdd new data to the end of a file.
Read Named AttributesRView the named attributes directory.
Write Named AttributesWCreate a named attribute directory. Must be paired with the Read Named Attributes permission.
ExecutexExecute a file, move through, or search a directory.
Delete ChildrenDDelete files or subdirectories from inside a directory.
Read AttributesaView file or directory non-ACL attributes.
Write AttributesAChange file or directory non-ACL attributes.
DeletedRemove the file or directory.
Read ACLcView the ACL.
Write ACLCChange the ACL and the ACL mode.
Write OwneroChange the user and group owners of the file or directory.
SynchronizesSynchronous file read/write with the server. This permission does not apply to FreeBSD clients.

NFSv4 Basic Flags

Click the Basic radio button to display the flag settings that enable or disable ACE inheritance.

NSFv4 Basic Flags Options
Figure 10: NSFv4 Basic Flags Options
NFSv4 Basic Flag Settings
FlagCLI CommandDescription
Inheritfd-----Enable ACE inheritance.
No Inherit-------Disable ACE inheritance.

NFSv4 Advanced Flags

Click the Advanced radio button to display the flag settings that enable or disable ACE inheritance and offer finer control for applying an ACE to new files or directories.

NFSv4 Advanced Flags Options
Figure 11: NFSv4 Advanced Flags Options
NFSv4 Advanced Flag Settings
FlagCLI CommandDescription
File InheritfThe ACE is inherited with subdirectories and files. It applies to new files.
Directory InheritdNew subdirectories inherit the full ACE.
No Propagate InheritnThe ACE can only be inherited once.
Inherit OnlyiRemove the ACE from permission checks but allow new files or subdirectories to inherit it. Inherit Only is removed from these new objects.
InheritedISet when this dataset inherits the ACE from another dataset.