📖 Chapter 02 — The Mental Model
How TrueNAS works in one picture. Memorize this. Every other chapter in this volume is a deeper dive into one of these layers.
Learning Objectives
- State the seven layers of a TrueNAS system, in order, without looking
- Explain what each layer is responsible for, and what it isn't
- Identify which layer any given TrueNAS menu or config screen belongs to
Introduction
TrueNAS looks like a wall of menus. Storage. Datasets. Shares. Users. Permissions. Apps. It feels like a hundred disconnected settings.
It isn't. It's seven layers stacked on top of each other, in a strict order. Once you have the stack in your head, every screen in the web UI has a place to live.
The stack
From the bottom (the metal) to the top (the user), here is the entire system:
Every layer builds on the one below it. The pool exists because of the vdevs. The datasets live inside the pool. The shares expose the datasets. The permissions decide who can reach which share.
That's it. Seven layers. Everything else is detail.
What each layer is
Layer 1 — Hardware
The physical machine. The motherboard, the CPU, the RAM, the network card, the case, the power supply, the fans. This is what you bought. You don't configure this in TrueNAS — you configured it when you chose the parts.
Why it matters: certain software features require certain hardware. ECC RAM matters for ZFS. A real NIC matters for SMB performance. A UPS matters for surviving brownouts. We'll come back to this in Volume 1's final chapter.
Layer 2 — Hard drives
The actual spinning rust (or the SSDs). For TK: 6 × 12TB. They sit in the case, connected to the motherboard's SATA ports (or an HBA card).
Drives do exactly two things: store bytes, and report when they're about to die (via SMART).
Why it matters: drives are the most failure-prone component in any server. Everything from Layer 3 up exists to cope with drive failure.
Layer 3 — VDEVs (Virtual Devices)
A vdev is a group of drives that work together as one. ZFS (the filesystem underneath TrueNAS) doesn't see individual drives — it sees vdevs.
The most common vdev type for a home NAS is RAIDZ2, which means: "any 2 drives in this group can fail and your data is still safe."
For TK's 6 × 12TB, that's one vdev with all 6 drives in it. The vdev reports itself to the pool as one big device.
Why it matters: vdevs are the unit of redundancy. Lose more drives than the vdev can tolerate, and the entire pool is gone. This is the layer where you decide how paranoid to be.
Layer 4 — Pool
The pool is the storage container. It collects one or more vdevs and presents them to the system as a single filesystem.
For TK: one pool, named tank, built from one RAIDZ2 vdev with 6 × 12TB.
Why it matters: a pool is a long-term commitment. You can replace drives within a vdev. You can add a whole new vdev to a pool (with caveats). You generally can't reshape a vdev in place. Choose your pool layout once and live with it.
Layer 5 — Datasets
Datasets are the most important concept in the whole system. A dataset is like a folder, but it has its own:
- Permissions
- Compression settings
- Snapshot schedule
- Quota (max size)
- Encryption
- Replication rules
- SMB share configuration
For TK: tank/Family, tank/Photos, tank/Videos, tank/Documents, tank/Private, tank/Backups, tank/Apps — each a separate dataset, each with its own rules.
Why it matters: datasets are how you get the benefits of "folders" without the limits. A snapshot of tank/Documents doesn't snapshot the videos. A quota on tank/PhoneUploads keeps your phone backups from filling the pool. Encrypted datasets can be locked and unlocked independently.
Layer 6 — Shares (SMB, NFS, etc.)
Shares are how Windows, Mac, Linux, and phones actually see the data. The dataset tank/Photos is invisible to your laptop until you create an SMB share that points to it.
For TK: an SMB share for each dataset the family needs. SMB is the protocol Windows and Mac both speak natively — no client software required.
Why it matters: the share is the boundary between "the data exists on the NAS" and "the data is accessible from my laptop." The share's name, the share's permissions, and the dataset it points to are three independent choices.
Layer 7 — Users & Permissions
Users are accounts: Tom, Spouse, Child1, Child2. Groups are collections of users: Family. Permissions are the rules: "Tom can read and write to Photos. The Family group can read and write to Family. Nobody except Tom can read Private/Tom."
Why it matters: this is the layer that decides whether your 6-year-old accidentally deletes the family photos. Or whether your spouse can see your tax documents. Or whether your friend who logs in next year can read anything at all.
How the layers interact
Here's a single sentence that captures it: a user authenticates against an SMB share, which points to a dataset, which lives in a pool, which is built from a vdev, which is a group of hard drives, in a physical machine.
Read that sentence again. Every TrueNAS question you've ever had is somewhere inside it.
Why the order matters
You cannot create a dataset before you create a pool. You cannot share a dataset that doesn't exist. You cannot set permissions on a user who hasn't been created.
This is why the chapters in this volume are in the order they are. We start at the bottom of the stack and work our way up. By Chapter 10, you'll have set up all seven layers on a real install.
Diagram: TK's actual configuration
Here's the same stack with TK's actual choices filled in. We'll build this exact thing over the next 8 chapters.
Engineering Note
The stack is a contract. Each layer promises the one above it a specific thing. Drives promise to store bytes. VDEVs promise not to lose them. Pools promise to present them as one filesystem. Datasets promise their own rules. Shares promise access. Permissions promise that only the right people have it.
When something goes wrong in your NAS, ask: "Which layer's contract was broken?" The answer is almost always obvious once you have the stack in your head.
Summary
Seven layers. Hardware at the bottom, users at the top. Every TrueNAS screen is one of the seven. Every problem is in one of the seven. The rest of this volume walks down the stack and back up — drives, vdevs, pool, datasets, shares, users, permissions, then the apps that tie it together.
Checklist
- ⬜ Draw the seven-layer stack on paper. Don't look at this chapter while you do.
- ⬜ For each layer, write one sentence about what its job is, in your own words.
- ⬜ Pin the stack diagram somewhere you'll see it. It's the most useful single image in the entire handbook.
Looking Ahead
Chapter 3 dives into Layer 2, 3, and 4: the actual hard drives, the RAIDZ2 vdev they'll form, and the pool that wraps it all. By the end, you'll know why TK's 6×12TB gives him ~44TB of usable space, and why he can't just add a 7th drive later.