How to Set Up a TrueNAS SMB Share: Users, ACLs & Apps

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.

Two notes before the steps. Recent releases have dropped the SCALE branding: the TrueNAS Documentation Hub now just says TrueNAS, versioned 24.10 through 26. It is the same Linux-based system and the same SMB workflow, so this guide applies whether the login screen says SCALE or not. And since 25.04 the UI also offers a share-first flow, where you start in Shares and create the dataset from inside the share form. The dataset-first order below is still the clearer way to think about it, because the layout decisions come first either way.

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. (A dataset is the right object for file sharing; if you are ever unsure whether you want a dataset or a raw block device, datasets vs zvols draws the line.)

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. The recordsize and compression tuning guide covers how to pick these per dataset.
• 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.

Two things the official share tutorial is firm about. First, TrueNAS will not let you create an SMB share at all until the system is either joined to Active Directory or has at least one local user with SMB access, so the user really does come first. Second, the flag has a trap in it: SMB Access (labelled Samba Authentication on some screens) has to be enabled at the moment the password is set. SMB keeps its own password hash and only writes it while that flag is on, so a user created without it signs in to the web UI fine and fails on the share forever. The fix is to tick the box and re-enter the same password.

Skip guest access. Per the 25.10 share documentation, guest access is restricted to the Legacy Share preset, which exists for shares migrated from older versions rather than for new ones. Every device that matters can store a credential.

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: the preset that sets the share’s defaults, and the names have changed across releases. Default Share is correct for almost everything. Time Machine Share (older builds: Multi-user time machine) advertises the share as a macOS backup target. Multi-protocol Share coordinates SMB with NFS access to the same data at a performance cost, which is only worth paying if a Linux client genuinely needs NFS to the same files; iSCSI vs NFS vs SMB works through that choice. Private Datasets Share replaces the old per-user home shares, and Legacy Share exists for migrated shares only.
• 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.

Two ACLs, and only one of them is usually the problem

Every SMB share carries two separate access-control layers, and conflating them is the single biggest source of “SMB is broken” threads:

• The share ACL (Edit Share ACL on the share row) gates the share itself. The default is Everyone / Full Control, which is fine: it means the share adds no restriction on top of the filesystem.
• The filesystem ACL (Edit Filesystem ACL) is the real permission set on the dataset, and it is where access is actually decided.

By default the filesystem ACL grants the builtin-users group, which every SMB-enabled local user belongs to, so out of the box every user created above can get in. To restrict a share, edit the filesystem ACL: narrow or remove the builtin-users entry and grant a specific group instead. For a dataset nested under other datasets, the documentation notes you also need Traverse on the parents, or users are denied before they ever reach the folder they have rights to.

If a client connects but gets “permission denied” opening the folder, it is the filesystem ACL. It is almost always the filesystem ACL.

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.

From Linux: sudo mount -t cifs //truenas/sharename /mnt/share -o username=alice, or the equivalent line in /etc/fstab with a credentials file.

Mapping a drive letter that survives reboots on Windows: net use Z: \\truenas\sharename /PERSISTENT:YES from a command prompt.

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.

Any current client negotiates SMB 3.1.1, supported since Windows 10 1607 and Windows Server 2016 per Microsoft’s SMB overview, which brings encryption and signing. There is no reason to enable SMB1 in 2026; TrueNAS 25.10 rejects SMB1 connections outright on shares that have auditing enabled.

The most common gotchas

“[EINVAL] sharingsmb_create.path_local: SMB shares containing the apps dataset are not permitted.” TrueNAS refuses to create an SMB share whose path is at or inside the apps (ix-applications) dataset, because that dataset holds container and app state that must never be reachable over SMB. Point the share at an ordinary data dataset instead: create a dedicated dataset such as tank/media, keep your files there, and share that path. If the goal was to let an app reach files on the share, do the reverse of sharing the apps dataset: keep the share on the data dataset and grant the app user filesystem access to it, as covered at the end of this guide.

“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.

Auxiliary parameters pasted from a forum post. The TrueNAS SMB server is Samba, and the share’s advanced options include a box that accepts raw smb.conf directives. Most decade-old snippets (looking at you, strict sync = no) solve problems that no longer exist and create ones that do, and an unsupported parameter is yours to own when an update changes its behaviour. Leave the box empty unless the documentation told you to fill it.

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.

Keep it off the internet

Never port-forward 445. An SMB share reachable from the open internet is a standing invitation: credential-stuffing bots and ransomware crews scan for it continuously, and it is a recurring theme in the breach write-ups aggregated at TechSentinel. Remote access belongs on a VPN or an overlay network, where the share is only reachable from inside it.

Because ransomware that lands on a client PC can encrypt everything the mapped drive can write to, ZFS snapshots are the undo button: a snapshot schedule on every SMB dataset, replicated somewhere the client cannot reach. The snapshot and replication strategy guide covers the schedule that turns that recovery into a ten-minute job instead of a total loss.

Where to go from here

• For a NAS that also serves Linux clients or VMs, NFS is sometimes a better fit than SMB. iSCSI vs NFS vs SMB on TrueNAS maps each protocol to the client and workload it suits best.
• 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. The TrueNAS SCALE apps guide covers laying out those app datasets cleanly.

See also

• Docker homelab tutorials
• homelab firewall guide

Related across the network

• OpenMediaVault Slow SMB Transfers: How to Fix — openmediavaultlab.com
• TrueNAS k3s Is Gone: Moving Apps to Docker — truenashub.com