What’s up guys, welcome back. Today we’re continuing our deep dive into TrueNAS SCALE, and we’re talking about something that every TrueNAS user eventually bumps into...Permissions. If you’ve ever touched permissions in TrueNAS SCALE before, you already know—it’s one of those things that can make you want to toss a chair out the window. It’s confusing, it’s layered, and sometimes it feels like it’s fighting you for no reason.
But in this guide, we’re going to break it all down, because understanding permissions was the turning point for me, and I'm hoping it will be the same for you. This article is part one of a two-part series. In this part, we break down users, groups, datasets, and ACLs.
In part two, we’ll talk about share-level permissions (SMB, NFS, etc.) and how those interact with everything underneath.
If you want to join the community and talk about TrueNAS or anything else we’re building here, the Discord is open. You can also subscribe to the channel or hop on my newsletter. all links are below. Alright… let’s dive in.
The Four Layers of Permissions in TrueNAS SCALE
Before we start clicking buttons, it helps to zoom out and understand the layers TrueNAS uses to decide who can do what. Permissions in TrueNAS SCALE aren’t a single setting—they’re a stack.
Here’s the big picture:
- Who the user is: This is your foundation. Users and groups define identity inside TrueNAS.
- What they can do in the TrueNAS web UI: This includes admin roles, privileges, and what parts of the UI a user can access.
- What they can access in the filesystem: This is where ACLs and dataset permissions come in.
- What they can access through a share: SMB, NFS, iSCSI—these add another layer of control on top.
A key thing to remember: Share permissions decide whether a person can connect.
ACLs decide what they can do after they connect. Once that clicked everything else with start making sense.
Users & Groups — Your Foundation
Before we even touch datasets or ACLs, we need to understand users and groups. Think of users and groups as the identity system TrueNAS relies on for everything you’re going to build. Here are the core concepts—explained simply.
- Local Users & Groups: These are accounts you create directly inside TrueNAS. You’ll use them for SMB access, app permissions, or anything that needs authentication.
- Built-In Users & Groups: These are created automatically by TrueNAS for system services. We don’t touch these—changing them usually breaks something.
- Auxiliary Groups: These are the “team groups” you add users to when multiple users need access to the same dataset or share. This is how you avoid managing permissions one user at a time.
- UID & GID: Every user has a UID and every group has a GID. Even if two users have the same name (not recommended), TrueNAS uses UID/GID to know who owns what.
- User Privileges: This is where you decide:
- Can the user log in through SMB?
- Can they SSH?
- Can they access the TrueNAS web interface?
- TrueNAS UI Roles: These control what a user can actually do inside the web UI—view settings, manage shares, read-only, full admin, etc.
The important thing is this: Users and groups don’t matter until you attach them to datasets. That’s where permission actually begins.
Groups: The Secret to Staying Organized
Groups keep your environment clean. Instead of assigning permissions to individual users over and over again, you assign permissions to a group… and then drop users inside that group.
If a user no longer needs access, you remove them from the group and you’re done. This is how you avoid creating a permissions disaster six months from now.
One thing to always remember: When you delete a user, delete their primary group too—unless you’re reusing it.
Otherwise, you end up with old groups hanging around doing nothing. Trust me… it adds up fast.
ACLs, Datasets, and the Real Permission Engine
Now we get into the heart of the system. ACLs (“Access Control Lists”) are the detailed rules that decide exactly what users and groups can do inside a dataset. Read, write, delete, modify—ACLs handle all of that. When you create a dataset, you’ll notice two ACL types:
- POSIX (Simple / Linux-style): Straightforward. User, group, other. You can layer ACLs on top, but it’s still limited.
- NFSv4 / SMB (Advanced): Windows-style permissions with inheritance, granular rules, and preset templates.
Choosing the right ACL type depends on what the dataset is used for. Most SMB or app datasets get the advanced type, while simple UNIX-style folders can use POSIX.
Inheritance — The Part Everyone Misunderstands
ACL inheritance works differently depending on which ACL type you're using.
- POSIX ACLs: Inheritance only applies inside a single dataset. If you create a new dataset under a parent, it will not inherit the parent’s ACL. You must reapply or recreate permissions manually.
- NFSv4/SMB ACLs: These support full, Windows-style inheritance. You choose what gets inherited—new files, new folders, both, or nothing. This is where things become powerful, but also where people break things the most.
Building an ACL: What’s Actually Happening
Whether you're using POSIX or NFSv4 ACLs, you’re working with the same concepts:
- The Owner: The user who owns the dataset.
- The Group Owner: The primary group attached to the dataset.
- Other / Everyone: Anyone who isn’t the owner or in the owner group.
- Additional Users / Groups: Anyone else you manually add.
- The Mask (POSIX only): This limits the maximum permissions anyone except the owner can have. This is the part that confused me the most at the beginning.
- Default / Inherit Flags: These decide whether new files and folders should automatically use these rules. Without the defaults/inheritance set correctly, your permissions only apply to the dataset itself—not the files inside it. This is one of the biggest reasons people end up fighting TrueNAS.
Why ACL Presets Are Your Best Friend
After you finally get an ACL structure that works, save it as a preset. Trust me—this is the difference between having a clean system and wanting to rip your server out of the rack. Once saved, you can apply your preset to new datasets with one click. No mask errors. No missing defaults. No broken apps. No permission hell.
A Warning From Experience
TrueNAS is extremely powerful, but you can also break things instantly if you start modifying permissions on datasets that already contain data—especially app data.
Before making changes:
- Understand the users your apps run as
- Understand which folders they need permission for
- Understand what inheritance will do
Once you change ownership or ACLs blindly, apps may stop working, shares may fail to mount, or files may disappear from clients. Take your time. Test on empty datasets first. Don’t rush it.
Wrapping Up — And What’s Next
Alright—that’s a lot, but this is the foundation you need to understand TrueNAS SCALE permissions without wanting to break something. Today we learned how users and groups define identity, how datasets and ACLs use that identity, how POSIX and NFSv4 ACLs differ, why inheritance matters, and how presets save your sanity, and in Part 2 we’ll take this into the real world by exploring SMB permissions, NFS permissions, iSCSI access control, how share-level rules layer on top of dataset rules, and how conflicts are resolved.
As always, thank you for hanging out with me. If you want to dive deeper or you have questions about something I didn’t cover, join the Discord—we talk about this stuff all the time. Stay geeking. Stay curious. And I’ll see you in the next one. Peace.
