Changing ACL Permissions in TrueNAS Scale

How do you use acl permissions in truenas scale via the CLI to change any files and folders that are present, created or modified in a directory to a different user and group?

This guide will walk you through how to use Access Control Lists (ACLs) in TrueNAS SCALE via the command line to change the owner and group of existing, new, and modified files and folders within a specific directory. This is great for centralizing access control beyond basic Unix permissions.

⚠️ Important Note: Be extremely careful when modifying ACLs recursively. Incorrectly set permissions can lead to data access issues! Test in a non-production environment first!

• Traditional Unix Permissions: Limited to owner, group, and others (read, write, execute).

• ACLs: Provide granular control. You can define permissions for specific users and groups beyond the basic owner/group/other model. This is essential for collaborative environments where multiple users need different levels of access.

• SSH Access: You'll need SSH access to your TrueNAS SCALE server.

• User & Group IDs: Know the User ID (UID) and Group ID (GID) of the target user and group. You can find these with:

id <username>  # Example: id bob

• Directory Path: Have the full path of the directory you want to modify. (e.g., /mnt/tank/data/shared)

We'll be using setfacl (set file ACL) and the -R (recursive) flag.

Basic Syntax:

setfacl -R -m "u:<UID>:<permissions>,g:<GID>:<permissions>" <directory_path>

• R: Applies the changes recursively to all files and subdirectories within the specified directory.

• m: Modifies the ACL.

• u:<UID>:<permissions>: Sets permissions for a specific user.

• g:<GID>:<permissions>: Sets permissions for a specific group.

• <permissions>: A combination of r (read), w (write), and x (execute). Use to deny a permission. (e.g., rwx, r-x, --)

Key Permissions Combinations:

• rwx: Read, write, and execute.

• r-x: Read and execute.

• r--: Read-only.

• --: No permissions.

Let's assume:

• Directory: /mnt/tank/data/shared

• User: bob (UID: 1001)

• Group: data_users (GID: 1002)

1. Grant User bob Read/Write/Execute access (rwx) to all files and folders:

setfacl -R -m "u:1001:rwx" /mnt/tank/data/shared

2. Grant Group data_users Read/Execute access (r-x) to all files and folders:

setfacl -R -m "g:1002:r-x" /mnt/tank/data/shared

3. Set both user and group at the same time:

setfacl -R -m "u:1001:rwx,g:1002:r-x" /mnt/tank/data/shared

4. Change the Default ACL (important for new files/folders):

This ensures that new files and folders created within the directory inherit the specified ACLs.

setfacl -d -m "u:1001:rwx,g:1002:r-x" /mnt/tank/data/shared

The -d flag sets the default ACL. Without this, new files/folders will revert to the default system ACLs.

Use getfacl to verify the applied ACLs:

getfacl /mnt/tank/data/shared

This command will display the ACLs for the directory. You can also check individual files/folders to confirm the changes have propagated correctly.

Sometimes, even with the -R flag, existing files might not fully inherit the default ACL. In those cases, you can "force" the application of the default ACL to existing files with a find command:

find /mnt/tank/data/shared -type f -print0 | xargs -0 setfacl -m "u:1001:rwx,g:1002:r-x"
find /mnt/tank/data/shared -type d -print0 | xargs -0 setfacl -m "u:1001:rwx,g:1002:r-x"

Explanation:

• find /mnt/tank/data/shared: Finds all files and directories within the specified directory.

• type f: Finds only files.

• type d: Finds only directories.

• print0: Prints the filenames separated by null characters (safer for filenames with spaces).

• xargs -0: Takes the null-separated filenames and passes them as arguments to setfacl.

To remove all ACLs from a directory and its contents:

setfacl -R -b /mnt/tank/data/shared

The -b flag removes all ACL entries. Use this with caution!

• Testing: Always test ACL changes in a non-production environment before applying them to your live data.

• Documentation: Keep a record of the ACL changes you make, including the directory paths, user/group IDs, and permissions.

• Backup: Before making significant ACL changes, consider backing up your data.

• ls -l doesn't show ACLs: The standard ls -l command only shows basic Unix permissions. Use getfacl to see the full ACLs.

• Use groups whenever possible: This makes permission management much easier in the long run.