Setting Up SMB Shares on TrueNAS SCALE

SMB is the most common reason people buy a NAS. Windows and macOS both speak it natively; iOS and Android have decent third-party clients; and most home applications can write to an SMB share. Getting it right on TrueNAS SCALE takes about fifteen minutes once you know the steps. Getting it wrong creates permission errors that look mysterious for an afternoon.

This guide walks through a clean SMB setup that will not bite you later.

Dataset structure first

Resist the temptation to share tank directly. Build the dataset structure first, then layer SMB shares on top of individual datasets. This gives you per-dataset snapshot schedules, quotas, compression settings, and permissions.

A reasonable starting layout:

tank/
├── users/
│   ├── alice/
│   ├── bob/
│   └── shared/
├── media/
│   ├── movies/
│   ├── tv/
│   └── music/
└── apps/
    └── (created by app installer, do not share)

Each entry above is a dataset, not just a directory. Create them via the TrueNAS web UI at Datasets → Add Dataset.

Per-dataset settings to consider at creation time:

• Compression: lz4 for almost everything. Always-on, near-zero CPU cost, and gracefully passes through already-compressed data.
• Record size: 128K (default) for most. Bump to 1M for media if your average file is multi-gigabyte; the lower record-size overhead helps sequential throughput. Do not change recordsize after data is written — it only applies to new writes.
• ACL Type: Choose NFSv4 ACLs for SMB-shared datasets. POSIX ACLs work for NFS but cause confusion when mixed with SMB.
• Case Sensitivity: Insensitive for SMB datasets that need to play well with Windows and macOS clients. Most TrueNAS guides recommend this.

Create a user and a group

Avoid using root for SMB authentication. Create dedicated users.

1. Go to Credentials → Local Users → Add.
2. For each person who needs access (e.g., alice), create a user.
3. Set a SMB-compatible password (the UI will prompt). Disable shell access if the user does not need it.
4. Optionally, create a group at Credentials → Local Groups → Add for households or families. family is a fine name.

For shared datasets like tank/users/shared, the group is your friend: you grant the group write access, then add household users to the group.

Set ownership and permissions

On the dataset, set ownership to the user (or group) who should own its contents. Go to Datasets → select dataset → Edit Permissions.

For a personal dataset like tank/users/alice:

• Owner User: alice
• Owner Group: alice (the group automatically created with the user)
• ACL: Use the “Home” preset for an individual user dataset.

For a shared dataset like tank/users/shared:

• Owner User: root (or any admin user)
• Owner Group: family
• ACL: Use the “Multi-User Home” preset, then customize to grant the family group read/write on the dataset.

Recurse the permissions when prompted, so existing files and directories adopt the new ACL.

Enable the SMB service

Go to System Settings → Services.

Find SMB, enable the “Start Automatically” toggle, and start the service. Click the pencil icon to configure it:

• NetBIOS Name: something distinctive (TRUENAS, your hostname, whatever).
• Workgroup: WORKGROUP is the default and is fine for most homes. Change only if you have a domain or specific reason.
• Enable Apple SMB2/3 Protocol Extensions: turn ON if you have macOS clients. This enables Spotlight indexing and resource fork handling.
• Description: appears in network browse lists. Optional.

Create the SMB share

Go to Shares → Windows Shares (SMB) → Add.

• Path: point at the dataset (e.g., /mnt/tank/users/alice).
• Name: the share name as it appears to clients. Convention: lowercase, no spaces (alice, shared, movies).
• Purpose: Default Share for most use cases. Multi-user time machine for a Time Machine target. Private SMB Share for a strictly user-only space.
• Enable ACL: ON (so the ACL you set at the dataset level is enforced).
• Hosts Allow / Deny: leave blank unless you have a specific network policy.

Save and refresh. The share is live.

Connect from a client

From Windows 11: in Explorer’s address bar, type \\<truenas-ip>\<share-name>. You will be prompted for credentials — use the TrueNAS local user account.

From macOS: Finder → Go → Connect to Server → smb://<truenas-ip>/<share-name>. Save credentials in Keychain for persistence.

From iOS / iPadOS: Files app → Browse → Connect to Server → enter the SMB URL.

From Android: use a SMB-aware app like Solid Explorer or Cx File Explorer.

If clients cannot find the server by hostname, use the IP. mDNS / NetBIOS discovery is unreliable across modern routers and is not worth debugging unless you have a specific reason to.

The most common gotchas

“Operation not permitted” or “Access denied” after a clean setup. The dataset ACL is set correctly but the SMB share is using the dataset path’s UNIX permissions instead of ACLs, or vice versa. Open the share, confirm Enable ACL is ON, and re-recurse permissions from the dataset edit dialog.

Permissions look right but new files appear with wrong ownership. This is an inheritance issue. On the dataset’s ACL, ensure the Inherit flag is set on the parent ACL entry so newly created files and folders inherit ownership and ACLs. Recurse permissions one more time after toggling.

macOS asks for credentials every time despite “Remember Password.” Keychain is corrupted or there is a mismatch between the saved username and the actual SMB user. Open Keychain Access, search for the NAS hostname, delete the entry, and reconnect — re-save credentials cleanly.

Time Machine cannot find the share. TrueNAS exposes Time Machine support through a specific share Purpose. Re-create the share with Multi-user time machine selected. Set a quota on the dataset so Time Machine does not consume the entire pool.

Slow large-file transfers from Windows. Disable the SMB Signing requirement on Windows if you are on a home LAN (Group Policy → Computer Configuration → Windows Settings → Local Policies → Security Options → Microsoft network client: Digitally sign communications (always) → Disabled). Re-enable on untrusted networks.

SMB sees the share but won’t let you write. Almost always an ACL issue. From the TrueNAS shell:

zfs get aclmode,aclinherit,acltype tank/users/alice

For SMB-shared datasets, you want aclmode=restricted (or passthrough), aclinherit=passthrough, acltype=nfsv4. Adjust via the dataset Edit dialog rather than the shell.

Where to go from here

• For a NAS that also serves Linux clients or VMs, NFS is sometimes a better fit than SMB. We will cover NFS setup in a separate guide.
• If you are running TrueNAS apps that need access to media on the share, configure the app dataset’s permissions to grant the app user read access — apps do not authenticate over SMB, they read the underlying filesystem directly.
• See TrueNAS Snapshot and Replication Strategy to set up snapshots on the datasets you just shared.