Fixing Permission Denied: How to Apply Recursive ACLs in TrueNAS Datasets

The “Permission Denied” Loop (And How to Break It)

You set the permissions. You checked the box. You clicked “Save.” Yet, when you try to open that subfolder, Windows throws the dreaded “Access Denied” error, or your Plex container stares blankly at an empty directory. We’ve all been there. It’s the distinct, gut-wrenching feeling of 2AM sysadmin fatigue—staring at a glowing monitor, wondering why “Full Control” actually means “No Control.”

Most guides tell you to just chmod 777 and call it a day. Do not do that.

According to the 2024 Verizon Data Breach Investigations Report, “Miscellaneous Errors”—which is corporate speak for misconfigurations like bad permissions—account for 28% of all breaches. Opening your permissions to “Everyone” isn’t a fix; it’s a welcome mat for ransomware.

In this guide, we aren’t just toggling switches. We are deploying a Recursive Repair Workflow that aligns the TrueNAS WebUI, Linux kernel, and ZFS architecture to fix Error 13 permanently.

The Anatomy of “Permission Denied”: Why TrueNAS Blocks You

Answer Target: “Permission Denied” (OS Error 13) in TrueNAS Scale is rarely about the file you are trying to touch. It is usually a Path Traversal failure. If you lack the “Execute” (Traverse) bit on the root dataset or any parent directory in the path, Linux will block access before checking the file’s ACL.

The “Traverse” Check (It’s Not the File, It’s the Folder)

Imagine your dataset is a hallway with many doors (subfolders). You might have the key to the bedroom (the file), but if the front door (the root dataset) is bolted shut, your key is useless. This is the Chain of Trust.

In TrueNAS Scale (which runs on Linux), the Execute (x) permission on a directory doesn’t mean “run a program.” It means “Traverse”—the right to pass through that folder to get to the next one.

The Gap: Most tutorials focus on the ACL of the share itself. But if your pool root /mnt/tank is owned by root:root with 700 permissions, and your user bob tries to access /mnt/tank/media, the kernel blocks bob at the very first step. You must ensure that “Traverse” is granted to your user (or “Others”) all the way down the tree.

The “Disappearing Checkbox” Mystery

I see this question on forums constantly: “I checked ‘Apply permissions recursively’, hit Save, and when I looked again, the box was unchecked! Is it broken?”

No. It’s a stamp, not a switch.

• Recursion is an Action: It takes your current settings and stamps them onto every existing file. Once the job is done, the action is over. The box unchecks itself because the action is complete.
• Inheritance is a State: This is what secures future files. If you fix recursion but fail to set the “Flags” for inheritance, any new file you drop in tomorrow will have broken permissions again.

The Recursive Repair Workflow: A 4-Step Fix

Stop guessing. Follow this disciplined workflow to strip the bad config and build a clean, inherited structure.

Step 1: The Audit (Check Your Path)

Before you nuke your permissions, check the “Traverse” path. Open the TrueNAS Shell (System Settings -> Shell) and check the path to your dataset.

# Check permissions on the pool root
getfacl /mnt/tank

# Check permissions on the dataset
getfacl /mnt/tank/my_share

If you see flags like --x or r-x for your user or group on the parent folders, you are good. If you see ---, you’ve found your bottleneck.

Step 2: The Strip (Nuking the “Cruft”)

ZFS ACLs can accumulate “ghost” entries—legacy explicit deny rules from Windows or sticky bits from old experiments. We need a clean slate. We will use the CLI to strip the ACLs back to a basic standard before rebuilding them in the UI.

Warning: Only do this if you are ready to rebuild permissions from scratch.

Step 3: The Architect (Setting the Template)

Go to Datasets, select your target, and click Edit on the Permissions card. This is where we define the “Future State” (Inheritance).

The Secret Sauce: Don’t just click “Full Control.” You need to verify the Flags. Click “Advanced” on your User/Group entry and ensure these checks are active:

• File Inherit: ON (Passes permissions to new files)
• Directory Inherit: ON (Passes permissions to new subfolders)
• Inherit Only: OFF (Unless this is a drop-box)

Pro Tip: Avoid assigning permissions to Everyone@. Instead, create a specific group called family or editors. This aligns with the Principle of Least Privilege.

Step 4: The Propagation (Apply Recursively)

Now, we execute.

1. Scroll to the bottom of the ACL Editor.
2. Check “Apply permissions recursively”.
3. Check “Apply to child datasets” (if you have nested datasets).
4. Click Save Access Control List.

The system will now walk the tree. For a few thousand files, it takes seconds. For millions? Read the next section.

Bridge the Gap: Apps (Kubernetes/Docker) vs. SMB Users

The most common headache in TrueNAS Scale is the “Plex Problem.” You upload a movie via SMB (User: Bob, UID: 3000), but Plex (User: apps, UID: 568) can’t delete it or see it.

Don’t change the App user. Change the Group strategy.

The “Shared Group” Strategy

1. Create a new group in TrueNAS named multimedia (e.g., GID 8888).
2. Add your SMB user (bob) to this group as an auxiliary member.
3. Add the apps user (UID 568) to this group.
4. In the ACL Editor (Step 3 above), grant Full Control to the Group multimedia, not just the user.

Now, both your Windows PC and your Docker container share the same “badge” (GID 8888), allowing seamless read/write access without fighting over file ownership.

The CLI “Nuclear Option”: Handling Million-File Datasets

I’ve managed datasets with over 1.3 million files. When I tried to use the “Apply recursively” checkbox in the WebUI, the middleware simply timed out. The spinning circle froze, and I was left unsure if the job finished.

If you have a massive dataset, bypass the UI. Use the find command combined with setfacl. This is faster and gives you real-time feedback.

The Script Solution

Open the Shell (or SSH in) and run this. It finds all directories (-type d) and grants access, then finds all files (-type f) and grants read/write access.

# Ensure your dataset accepts POSIX commands before running this.
# Note: Using setfacl -R (recursive flag) can be faster than find for simple structures.

# Apply 'rwx' to all DIRECTORIES (Traverse allowed)
find /mnt/tank/dataset -type d -exec setfacl -m g:multimedia:rwx {} +

# Apply 'rw-' to all FILES (No execute on files for safety)
find /mnt/tank/dataset -type f -exec setfacl -m g:multimedia:rw- {} +

Note: The + at the end tells find to bundle arguments, making this significantly faster than running the command once per file.

Security First: Hardening Your ACLs (NIST Compliance)

Getting access is half the battle. Securing it is the war.

Ransomware Defense: The Read-Only Service Account

Ransomware works by encrypting files it can write to. Does Plex need to write to your movie archive? Probably not. It just needs to read.

Create a specific ACL entry for your service accounts that grants Read and Execute (Traverse), but DENY Write. Even if your Plex container is compromised, the attacker cannot encrypt your media library. This is a practical application of the NIST SP 800-209 guidelines for storage isolation.

Enable Auditing (Stop Guessing)

If you are still hitting errors, turn on the lights.

1. Go to System Settings > Services > SMB.
2. Enable Audit Logging.
3. Attempt the file access again.

Now, instead of a generic “Access Denied,” you can check /var/log/samba/log.smbd and see exactly which ACL entry blocked you.

Frequently Asked Questions

Conclusion

Fixing permissions in TrueNAS isn’t about brute force; it’s about architecture. By stripping the “cruft,” ensuring the Traverse bit is set on the parent path, and correctly applying inheritance flags, you solve the problem for today and tomorrow.

If you’ve been stuck in the “Permission Denied” loop, open your shell right now and run that getfacl check on your root dataset. That one command might save you another sleepless night.