💾 TrueNAS Tutorial¶

TrueNAS is an open-source NAS (Network Attached Storage) operating system built on the OpenZFS filesystem. It enables you to turn standard hardware into a reliable and high-performance storage server. It supports common protocols like SMB, NFS, making it suitable for home, business, and enterprise environments.

TrueNAS provides features such as data integrity, snapshots, replication, and fine-grained access control.

truenas-screen

Installation¶

Download TrueNAS

Download the latest TrueNAS Community Edition ISO from the official website:

https://www.truenas.com/download/

Create Installation Media

Flash the ISO to a USB drive using balenaEtcher:

https://etcher.balena.io/

Boot from the USB Drive

Ensure your system boots from the USB installation media. You may need to access the BIOS/UEFI settings to change the boot order.

Option A: From Windows (Shift + Restart)

Open the Start menu
Hold the Shift key
Click Power → Restart
Navigate to Use a device or UEFI Firmware Settings to select the USB drive

Option B: From Windows 11 (UEFI Firmware Settings)

Open Settings
Go to System → Recovery
Under Advanced startup, click Restart now
Select Troubleshoot → Advanced options → UEFI Firmware Settings
Click Restart to enter BIOS/UEFI

Multi-User SMB Configuration¶

Storage Layout & Access Control¶

The goal is to configure TrueNAS to clearly separate personal and shared data, with appropriate access control.

Personal directory: Accessible only by its owner
Shared directory: Accessible to all authorized users

To achieve this, datasets are organized as follows:

Vault
├── users
│   ├── UserA
│   └── UserB
└── Shared

Dataset	Purpose
`Vault/users/UserA`	Personal storage for UserA
`Vault/users/UserB`	Personal storage for UserB
`Vault/Shared`	Shared files between users

Each dataset supports:

independent permissions
independent snapshots
optional quotas

Create Users¶

Create Users

Create two users (UserA and UserB) and assign them to the builtin_users group.
This ensures they can access shared datasets via SMB.

Steps:

Go to Credentials → Users
Click Add

UserA
  Username: UserA
  SMB Access: [x]
  Groups: builtin_users
UserB
  Username: UserB
  SMB Access: [x]
  Groups: builtin_users

Create Datasets¶

Create Datasets

Create datasets to separate user home directories and shared data, using SMB-compatible ACL settings for easier permission management.

All datasets should use:

Dataset Preset: Generic
ACL Type: SMB/NFSv4
ACL Mode: Passthrough

Steps:

Go to Datasets
Select your pool
Click Add Dataset

Dataset	Purpose
`Vault/users`	Personal storage for users
`Vault/users/UserA`	Personal storage for UserA
`Vault/users/UserB`	Personal storage for UserB
`Vault/Shared`	Shared files between users

Create SMB Shares¶

Create SMB Shares

Create SMB shares for the users and Shared datasets.
Access to the shares is limited to members of the builtin_users group.
File-level access is then controlled by dataset ACLs.

Steps:

Go to Shares → SMB
Click Add

Name: Users
  Path: /mnt/Vault/users
  ACL Entries
    Who: Group
    User: builtin_users
    Permission: FULL
    Type: ALLOWED
Name: Shared
  Path: /mnt/Vault/Shared
  ACL Entries
    Who: Group
    User: builtin_users
    Permission: FULL
    Type: ALLOWED

Only users in builtin_users can see these shares. Actual access to files and folders is enforced by dataset ACLs. Users can access SMB shares using the following paths:

\\NAS_URL\Shared

\\NAS_URL\Users\UserA

\\NAS_URL\Users\UserB

Configure ACL¶

Configure Default ACL

ACLs (Access Control Lists) provide fine-grained control over access to files and folders.
They determine which users or groups can read, write, or modify data within each dataset, and ultimately enforce access rules beyond SMB share visibility.

Steps:

Go to Shares → SMB
Select the Shares
Edit Filesystem ACL

Name: Users
  Select a preset ACL: [x]
  Preset: NFS4_HOME
  Modify "everyone@" entry
    Who: everyone@
    ACL Type: Allow
    Permission Type: Basic
    Permissions: Read
  Apply permissions recursively: [x]
  Click on "Save Access Control List"

Name: Shared
  Select a preset ACL: [x]
  Preset: NFS4_HOME
  Remove "everyone@" entry
  Add "builtin_users" entry
    Who: Group
    Group: builtin_users
    ACL Type: Allow
    Permission Type: Basic
    Permissions: Modify
  Apply permissions recursively: [x]
  Click on "Save Access Control List"

Configure Users ACL

In this section, configure ACLs to ensure each user can only access their own dataset.
Additionally, add a read-only ACL entry for the apps user.
This allows TrueNAS applications (e.g. Duplicati) to access user data for backup purposes without modifying it.

Users not listed in the ACL are implicitly denied access — no explicit deny entry is needed.

Steps:

Go to Datasets → Vault → users
Edit Permissions

Name: UserA
  Add "UserA" entry
    Who: User
    User: UserA
    ACL Type: Allow
    Permissions Type: Basic
    Permissions: Modify
  Add "apps" entry
    Who: User
    User: apps
    ACL Type: Allow
    Permissions Type: Basic
    Permissions: Read
  [x] Apply permissions recursively
  Click on "Save Access Control List"

Name: UserB
  Add "UserB" entry
    Who: User
    User: UserB
    ACL Type: Allow
    Permissions Type: Basic
    Permissions: Modify
  Add "apps" entry
    Who: User
    User: apps
    ACL Type: Allow
    Permissions Type: Basic
    Permissions: Read
  [x] Apply permissions recursively
  Click on "Save Access Control List"

Automatic Backup with Duplicati¶

Duplicati is a backup application that provides smart retention, similar to Apple Time Machine.
The goal is to perform daily incremental backups of user datasets to a backup directory located on a separate SSD.

Retention Policy (Smart Retention):

1 backup per day for the last 7 days
1 backup per week for the last 4 weeks
1 backup per month for the last 12 months
At least one backup is always preserved

Important:
As long as a file exists in at least one retained backup version, it can be restored at any time.
Even if a file has not changed for months or years, it remains available through older backup versions kept by the retention policy.
A file is only permanently removed from backups once all versions containing it fall outside the retention window.

Create Backup Datasets¶

Create Backup Datasets

Create datasets on the backup SSD to store Duplicati data and user backups.

Backup
└── Duplicati
    ├── config
    ├── backup_userA
    └── backup_userB

Set the "apps" ACLs

Name: Duplicati
  Add "apps" entry
    Who: User
    User: apps
    ACL Type: Allow
    Permissions Type: Basic
    Permissions: Modify
  [x] Apply permissions recursively
  Click on "Save Access Control List"

Configure Duplicati¶

Configure Duplicati

Configure Duplicati to store its application data on the backup SSD instead of the default system location:

Apps → Configuration → Choose Pool → "SSD"

Also add the required mount paths:

/mnt/Vault/users → read-only access to source user data
/mnt/Backup/Duplicati → read/write access to store backup files

Duplicati Configuration
Timezone: 'Europe/Paris' timezone
Password: <set server password>
User and Group Configuration
User ID:  568
Group ID: 568
Network Configuration
WebUI Port: Publish port on the host for external access
Port Number: 30121
Storage Configuration
Data Storage
    Type: Host Path (Path that already exists on the system)
    Host Path: /mnt/Backup/Duplicati/config
    Automatic Permissions: [ ]
Source
    Type: Host Path (Path that already exists on the system)
    Read Only: [x]
    Mount Path: /mnt/Vault/users
    Host Path: /mnt/Vault/users
Destination
    Type: Host Path (Path that already exists on the system)
    Read Only: [ ]
    Mount Path: /mnt/Backup/Duplicati
    Host Path: /mnt/Backup/Duplicati

Note: Do not expose the Duplicati web UI to the internet, it should be accessible only via local network (don't open port 30121 on firewall/internet box).
User ID 568 is TrueNAS SCALE built-in apps user UID, shared by all app containers.

Configuration¶

General¶

Move System Dataset Off Vault

In TrueNAS, the System Dataset stores internal data such as logs, reporting metrics, and system state information required for proper operation. By default, TrueNAS stores system data inside your first created pool. So when you created Vault, TrueNAS automatically moved the system dataset there.

For better separation of system and user data, it is recommended to move it to the boot pool.

To change it:

Go to System → Advanced Settings → Storage → Configure
Set System Dataset Pool to boot-pool
Click Save

Note: Now vault is pure user data.

Activate the General Update Train

It is recommended to configure TrueNAS to use the General update train. The General train provides stable, well-tested releases with mature features. This reduces the risk of bugs and unexpected issues compared to newer or less-tested update channels.

System → Update Profile → General

SMART¶

SMART Quick Test (or short self-test) is a built-in diagnostic that performs a fast, basic health check of a hard drive using its S.M.A.R.T. system. It examines key components and a small portion of the disk surface, typically completing in a few minutes. It is useful for routine monitoring, but does not replace a full extended test.

Create SMART jobs

Process:

It starts a SMART short test on the disk and exits if it can’t start.
Then it waits (up to ~5 minutes) until the test finishes.
After that, it checks the latest test result.
It returns an error if the test failed, otherwise success.

To Add a Cron Job:

System → Advanced Settings → Cron Jobs

Run As User: root
Command: <smart-command>

Schedule
Presets: Daily
Minutes: 45
Hours: 23

Hide Standard Output: [ ]
Hide Standard Error:  [ ]
Enabled:              [x]

SMART COMMAND

Replace /dev/sda with your drive. Create one cron job per drive — for example, a second job with /dev/sdb for a two-drive setup.
To list all drives: ls /dev/sd*

/bin/sh -c 'DRIVE=/dev/sda; smartctl -t short "$DRIVE" >/dev/null 2>&1 || { echo "ERROR: could not start SMART short test on $DRIVE" >&2; exit 1; }; for i in $(seq 1 15); do smartctl -c "$DRIVE" | grep -q "Self-test routine in progress" || break; sleep 20; done; if smartctl -l selftest "$DRIVE" | awk '\''$1=="#" {print; exit}'\'' | grep -q "Completed without error"; then echo "OK: SMART short test passed on $DRIVE"; exit 0; else echo "ERROR: SMART short test failed on $DRIVE" >&2; exit 2; fi'

Scripts¶

Copy Data from External SMB Share

This procedure allows you to copy data from an external SMB share into a TrueNAS ZFS dataset using the command line.

# connect to TrueNAS via SSH
ssh truenas_admin@nas

# mount the external SMB share
mkdir smb_share
sudo mount -t cifs //URL/Share /home/truenas_admin/smb_share -o username=admin

# copy data to the ZFS dataset using rsync
rsync -avh --progress /home/truenas_admin/smb_share/Data/ /mnt/Data/

# unmount and clean up
sudo umount /home/truenas_admin/smb_share
rmdir smb_share

Find and remove duplicated files

To improve performance, duplicate detection is usually performed in two stages:

files are first grouped by size
hashes are calculated only for files with identical sizes

Since files with different sizes cannot be identical, this avoids reading and hashing every file.

Two versions of the script are available: the standalone .py for interactive use, and a headless variant embedded in the Docker Compose below for automated runs inside TrueNAS apps.

Feature	`Python Script`	`Docker / YAML version`
Interactive confirmation prompt	Yes	No — deletes immediately
Progress bar	Yes	No
CLI arguments (`--root`, `--report-file`)	Yes	No — hardcoded paths
Hash error logging	Yes	Silent

The Docker / YAML version:

scans and deletes duplicates of /mnt/Vault/users/UserA
keeps the first sorted file in each duplicate group
writes the report to /mnt/Vault/users/UserA/duplicates.csv

Create the application:

Apps → Discover Apps → ... → Install via YAML
Replace the path /mnt/Vault/users/UserA/Dir with your own target directory