Home · Volume 1 · Chapter 07

📖 Chapter 07 — Permissions

The rules that turn datasets and users into a working family NAS.

Learning Objectives

Explain POSIX permission bits (owner / group / others)
Decide when POSIX is enough and when you need ACLs
Apply the "TK can always recover" pattern without compromising privacy
Set up private datasets so each family member truly has their own space

Introduction

Users (Chapter 06) define who is. Datasets (Chapter 04) define what is. Permissions are the rules that connect the two: for each dataset, who can do what.

For a family NAS, the model is small. There are essentially three permission patterns to know, and they cover 90% of the cases. This chapter walks through each one and shows how TK's build uses them.

The two permission systems

TrueNAS gives you two ways to control who can do what with a dataset:

POSIX permissions — the Unix model. Owner, Group, Others. Read, Write, Execute. Three numbers. Works for almost everything.
ACLs (Access Control Lists) — the Windows model. Per-user and per-group entries with allow/deny. More expressive, more complex. Use when POSIX isn't enough.

For a family NAS, POSIX is enough for almost every dataset. ACLs come in when you need things like "Mimi can read but not delete, TK can do anything, the Family group can read but not write." That's hard to express in pure POSIX.

Rule of thumb

Start with POSIX. Switch to ACLs only when POSIX can't express what you need. ACLs work, but they have more failure modes (deny rules, inheritance flags, the recursive "reset" when you edit them). Don't reach for them prematurely.

POSIX permissions: the model

Every file and every folder in a POSIX system has three permission triples, looking like this:

  Owner   Group   Others
  rwx     rwx     rwx
  421     421     421

For a dataset (which is also a folder):

Owner: the user who owns the dataset (typically the creator)
Group: a single group that has the "group" permissions
Others: everyone else on the system

Each position has three bits: read (r, 4), write (w, 2), execute (x, 1). The numbers add up to 0-7. So:

rwx = 7 = read, write, execute
rw- = 6 = read, write (no execute)
r-- = 4 = read only
--- = 0 = no access

You'll see this written as 755 (owner can do everything, group and others can read+execute) or 644 (owner can read+write, group and others can read) — these are common defaults for system files. For datasets, you'll typically see 770 or 750 or 700.

What the bits mean for folders

For files, rwx means what you'd expect. For folders (and datasets), the meanings are slightly different:

r on a folder: can list the contents (ls)
w on a folder: can create, delete, rename files inside
x on a folder: can "enter" the folder and access its contents (cd, open files)

This is why you need both r and x to actually do anything with a folder. A folder with r-- lets you list the names but not open any files. A folder with --x lets you open files if you know their names but not list what's there.

Pattern 1: shared dataset, family read/write

The most common pattern. Used for `Family`, `Photos`, `Videos`, `Documents`.

Settings:

Owner: `tk` (the household admin)
Group: `Family`
Permissions: 770 — owner and group have rwx, others have nothing

What this means:

TK (the owner) can do anything: read, write, delete, change permissions
Everyone in the Family group (tk, mimi, lai) can read, write, create, delete
Anyone else (a future friend user, a service account) gets "Permission Denied"

To set this in the TrueNAS web UI: open the dataset's permissions, set owner to `tk`, set group to `Family`, set permissions to 770 (or use the checkboxes: Owner = Read+Write+Execute, Group = Read+Write+Execute, Others = none).

Pattern 2: private dataset, owner-only

Used for `Private/tk`, `Private/mimi`, `Private/lai`. Each person gets their own dataset that only they can read.

Settings for `Private/tk`:

Owner: `tk`
Group: `tk` (or `Family` — see below)
Permissions: 700 — owner has rwx, group and others have nothing

What this means:

TK (the owner) can do anything in his private dataset
The Family group can't even list the contents
Nobody else can access it at all

The "admin can recover" pattern

Here's a question from the conversation: if TK's private dataset is owned only by `tk`, what happens if TK forgets his password?

Two answers, with the recommendation:

Option A: TK is the owner, the dataset is truly private

Even the root user cannot access the dataset without the encryption key (if encrypted) or without resetting permissions as root. If TK loses his password, the data is essentially lost.

Option B: TK owns the dataset, but `tk` (admin) has a permission override

The admin user — let's call it `tk-admin` — also has access to the private dataset, even though `tk` (the regular user) is the "owner." This is done with an ACL that says "tk-admin: full control." The private data is private from other family members, but the admin can recover it.

The conversation's recommendation: Option B for a home NAS. Reasons:

Family members forget passwords. It happens.
If Mimi forgets her password, you want to be able to recover her data, not lose it.
True privacy from the admin is a business feature, not a home feature.
You can always add a second password or two-factor auth to make it harder for the admin account to be compromised.

To implement this with POSIX, you'd need an ACL. The conversation's v2.1 design uses POSIX where it can and ACLs where it must.

Pattern 3: shared by subset of family

Sometimes a dataset is for some family members, not all. The conversation's design has one example: the `Private` dataset at the top level is shared between TK and Mimi (the spouse) but not Lai (the sibling). The sub-datasets are individual.

Implementation: create a `tk-and-mimi` group, put `tk` and `mimi` in it, and grant that group read/write to the `Private` parent dataset. The individual `Private/tk` and `Private/mimi` sub-datasets use Pattern 2 (owner only).

For a family of 4, this is rare. For a family with adult children + parents + grandparents who all share some things but not others, it becomes useful.

The full permissions table

For TK's build, the complete dataset permission setup:

Dataset	Owner	Group	Mode	Effect
Family	tk	Family	770	Family can read/write; others can't
Photos	tk	Family	770	Same
Videos	tk	Family	770	Same
Documents	tk	Family	770	Same
Private	tk	tk	770	Only TK; Mimi's subdataset will be different
Private/mimi	mimi	mimi	700	Only Mimi, owner-only
Private/lai	lai	lai	700	Only Lai, owner-only
PhoneUploads	tk	Family	770	Family can drop files; TK manages
Apps	tk	Family	770	Family has read-only by default; apps have their own accounts
Media	tk	Family	770	Family has read-only by default; TK does most work
Lab	tk	tk	700	Only TK, owner-only

How permissions and SMB interact

From Chapter 05: a user has to pass both the share permission and the dataset permission. Let's trace through what happens for Mimi trying to open \\NAS\Private:

Mimi tries to list \\NAS\ from her laptop. The SMB service shows her: Family, Photos, Videos, Documents, PhoneUploads, Apps, Media. Private does not appear, because Access Based Share Enumeration is on, and Mimi isn't in the Private share's allow list.
Mimi knows the share exists anyway. She types \\NAS\Private directly.
The SMB service authenticates her as `mimi` and looks up the Private share.
The share's ACL says: "Only `tk` and `tk-admin` can access." Mimi is denied.
Mimi sees "Access Denied" or "The network path was not found" (depending on the OS).

Even if the share allowed Mimi, the dataset underneath has mode 770 with owner `tk` and group `tk` — Mimi is neither, so she'd be denied at the dataset layer too. Both layers enforce.

Debugging permission issues

When someone says "I can't see my files," work through this checklist:

Can they see the share? (Network browse or type the path)
Can they connect to the share? (SMB auth works)
Can they list the share's contents? (Share-level ACL)
Can they open a specific folder? (Dataset permission for the user and group)
Can they open a specific file? (File permission, which usually inherits from the dataset)

Most issues are at step 1, 3, or 4. The conversation's most-common TK-mistake was setting the dataset owner to `tk` but the group to `Family`, then giving the dataset mode 770, then wondering why Mimi couldn't access it (because the group was Family, not mimi's group). The fix: either make the group the actual group of intended users, or use an ACL to specify per-user access.

Engineering Note

Permissions are not a security system by themselves. They're an organizational tool. The real security of a family NAS comes from: who has physical access to the machine, whether the network is trusted, whether the admin password is strong, whether SMB1 is disabled, whether encryption is on for the most sensitive data.

Permissions matter most when: a child accidentally tries to delete a parent's tax documents, a friend logs in to a wrong share, an app fails because it can't write to its data directory. They prevent accidents and guide behavior. They don't stop a determined attacker.

For "determined attacker" security, you want: encryption at rest, a strong admin password with 2FA, no SMB exposed to the internet, regular security updates, and (eventually) a hardware security key for the admin account.

Summary

POSIX permissions are enough for most family NAS use cases. Use mode 770 for shared datasets (owner + group have full access, others get nothing). Use mode 700 for truly private datasets. The owner is typically the admin user; the group is typically `Family`. Access Based Share Enumeration on the share + a tight share ACL prevents users from even seeing shares they can't access. The "admin can always recover" pattern is the right default for a home NAS — use an ACL to give the admin override access to private datasets, in case of forgotten passwords.

Checklist

⬜ Apply the permission table from this chapter to your datasets
⬜ Enable Access Based Share Enumeration on the Private share
⬜ Test from each family member's perspective: what can they see? What can they open?
⬜ If using Option B for the "admin can recover" pattern, set up the ACL on each private dataset

Looking Ahead

Chapter 08 covers the first apps — the services that turn a NAS into infrastructure. Tailscale for remote access, Immich for photos, Jellyfin for media, Vaultwarden for passwords, Paperless-ngx for documents. Each is a Docker container in the `Apps` dataset, each with its own identity model.

Previous← Ch 06 · Users & Groups Next📖 Ch 08 · First Apps →

Ch 07 · v0.1 · drafted from the original ChatGPT conversation, July 2026