Windows Shares (SMB)
22 minute read.
When creating a share, do not attempt to set up the root or pool-level dataset for the share. Instead, create a new dataset under the pool-level dataset for the share. Setting up a share using the root dataset leads to storage configuration issues.
SMB (also known as CIFS) is the native file-sharing system in Windows. SMB shares can connect to most operating systems, including Windows, Mac OS, and Linux. TrueNAS can use SMB to share files among single or multiple users or devices.
SMB supports a wide range of permissions, security settings, and advanced permissions (ACLs) on Windows and other systems, as well as Windows Alternate Streams and Extended Metadata. SMB is suitable for managing and administering large or small pools of data.
TrueNAS uses Samba to provide SMB services. The SMB protocol has multiple versions. During the SMB session negotiation, a typical SMB client can negotiate the highest supported SMB protocol. Industry-wide, SMB1 protocol (sometimes referred to as NT1) use is deprecated for security reasons.
As of TrueNAS 22.12 (Bluefin) and later, TrueNAS does not support SMB client operating systems that are labeled by their vendor as End of Life or End of Support. This means MS-DOS (including Windows 98) clients, among others, cannot connect to TrueNAS SMB servers.
The upstream Samba project that TrueNAS uses for SMB features notes in the 4.11 release that the SMB1 protocol is deprecated and warns portions of the protocol might be further removed in future releases. Administrators should work to phase out any clients using the SMB1 protocol from their environments.
However, most SMB clients support SMB 2 or 3 protocols even when they are not the default.
Legacy SMB clients rely on NetBIOS name resolution to discover SMB servers on a network. TrueNAS disables the NetBIOS name server (nmbd) by default. Enable it on the Network > Global Settings screen if this functionality is required.
Mac OS clients use mDNS to discover SMB servers present on the network. TrueNAS enables the mDNS server (avahi) by default.
Windows clients use WS-Discovery to discover the presence of an SMB server. You can disable network discovery by default depending on the Windows client version.
Discoverability through broadcast protocols is a convenience feature and is not required to access an SMB server.
TrueNAS has implemented administrator roles to align with FIPS-compliant encryption and security hardening standards. The Sharing Admin role allows the user to create new shares and datasets, modify the dataset ACL permissions, and start/restart the sharing service, but does not permit the user to modify users or grant the sharing administrator role to new or existing users.
Full Admin users retain full access control over shares and creating/modifying user accounts.
Verify your Active Directory connections are working and error-free before adding an SMB share. When an SMB share is configured but not working or is in an error state, AD cannot bind, and TrueNAS cannot start the SMB service.
Creating an SMB share on your system requires adding the share and then getting it working.
Create the SMB share user account.
You can manually add user accounts or use directory services like Active Directory or LDAP to provide additional user accounts. If setting up an external SMB share, we recommend using Active Directory or LDAP, or at a minimum, synchronizing the user accounts between systems.
Create the SMB share and dataset.
You can create a basic SMB share or a more specific share type with specific feature requirements from the Add SMB screen using the Advanced Options instructions before saving the share.
The Add Dataset and the Add SMB share screens allow TrueNAS to create a dataset and SMB share from that screen. Use either option to create a basic SMB share.
When creating an SMB share that requires customization or is intended for a specific purpose, such as working with Veeam Backup & Restore immutability or a repository for block or fast cloning (requires an Enterprise license), use the Add SMB screen Purpose presets to create the share and dataset for these special SMB shares. For more information on Veeam SMB shares, refer to the Solutions > Integrations Veeam and Veeam Immutability guides.
When setting up multi-protocol (SMB and NFS) shares, refer to the Multiprotocol Shares tutorial for configuration instructions.
This article provides instructions on adding a dataset while adding the share using the Add SMB screen
After adding or modifying the user account for the share, edit the dataset permissions.
Start the service and mount the share to your other system.
TrueNAS must be joined to Active Directory or have at least one local SMB user before creating an SMB share. When creating an SMB user, ensure that Samba Authentication is enabled. You cannot access SMB shares using the root user, TrueNAS built-in user accounts, or those without Samba Authentication selected.
To add or edit users, go to Credentials > Users, then add or edit an existing user to create the SMB share user(s). Click Add to create a new user or as many new user accounts as needed. Joining TrueNAS to Active Directory creates the user accounts.
Enter the values in each required field, verify SMB User is selected, then click Save. For more information on the fields and adding users, see Creating User Accounts.
By default, all new users are members of a built-in group called builtin_users. You can use a group to grant access to all users on the server or add more groups to fine-tune permissions for large numbers of users.
You can create an SMB share while creating a dataset on the Add Dataset screen or create a dataset and the share using the Add SMB share screen. This article covers adding the dataset using the Add SMB share screen.
It is best practice to use a dataset instead of a full pool for SMB and/or NFS shares. Sharing an entire pool makes it more difficult to later restrict access if needed.
Before you begin this procedure, if you want to organize the SMB share dataset under a parent dataset (for example, under smb-shares), create that dataset so you can select it as the parent in step 2 below.
To create a basic Windows SMB share and a dataset, go to Shares, then click Add on the Windows Shares (SMB) widget to open the Add Share screen.
Enter or browse to select the SMB share mount path (parent dataset where you want to add a dataset for this share). The blank Path field populates with the path selected in the file browser field directly below it. The Path file browser field is the directory tree on the local file system that TrueNAS exports over the SMB protocol.
Click Create Dataset. Enter a name for the dataset in the Create Dataset dialog, and then click Create. The system creates the new dataset and populates the Name field with the dataset name.
The value entered in Name becomes the dataset and share name. It forms part of the share pathname when SMB clients perform an SMB tree connect. Because of how the SMB protocol uses the name, it must be less than or equal to 80 characters. Do not use invalid characters as specified in Microsoft documentation MS-FSCC section 2.1.6.
If you change the name, follow the naming conventions for:
Select a share type on the Purpose dropdown list. The share type selected locks or unlocks the pre-determined Advanced Options settings for the share.
To retain control over all the share Advanced Options settings, select Default Share.
To create a multi-protocol share (NFSv4/SMB), select Multi-protocol Share. This adds the share to the SMB and NFS widgets on the main Shares screen.
To create an alternative to home shares, select Private Datasets Share. See Setting Up SMB Home Shares for more information on replacing this legacy feature with private SMB shares and datasets.
If creating an external share, select External Share, enter the full domain name or IP address, and the share name. Separate the server and share name with the
\characters. Example: 192.168.0.200\SHARE in Remote Path.(Optional) Enter a Description to help explain the purpose or details on how the share is used. For example, if for an external share, enter external share in the field. The description entered shows in the SMB table on the SMB screen and the Windows (SMB) Share widget.
Select Enabled to allow sharing of this path when the SMB service is activated. Leave the checkbox cleared to disable the share without deleting the configuration.
(Optional) Click Advanced Options to show additional configuration settings. Click to configure other advanced settings such as access, audit logging, or settings specific to the type of share selected in Purpose.
Click Save to create the share and add it to the Shares > Windows (SMB) Shares list.
Start or restart the SMB service when prompted.
A basic SMB share does not need to use the Advanced Options settings, but if you set Purpose to Time Machine Share, Time Locked Share, or Private Dataset Share, or External, click Advanced Options to finish customizing the SMB share settings.
See SMB Shares Screens for all settings and other possible use cases.
There are two levels to set SMB share permissions: at the share or for the dataset associated with the share. See Managing SMB Shares for more information on these options.
See Permissions for more information on dataset permissions.
You cannot access SMB shares with the root user. Change the SMB dataset ownership to the admin user (Full Admin user).
Using the Edit Share ACL option configures the permissions for just the share, but not the dataset the share uses. The permissions apply at the SMB share level for the selected share. They do not apply to other file sharing protocol clients, other SMB shares that export the same share path (i.e., /poolname/shares specified in Path), or to the dataset the share uses.
After creating the share and dataset, modify the share permissions to grant user or group access.
Click on Edit Share ACL to open the Edit Share ACL screen to modify permissions at the share level.
Select either User in Who, then the user name in User, and then set the permission level using Permissions and Type.
(Optional) Click Add then select Group, the group name, and then set the group permissions.
Click Save.
See Permissions for more information on setting user and group settings.
You cannot access SMB shares with the root user. Change the SMB dataset ownership to the admin user (Full Admin user).
To configure share owner, user and group permissions for the dataset Access Control List (ACL), use the Edit Filesystem ACL option. This modifies the ACL entry for the SMB share the path (defined in Path) at the dataset level. To customize permissions, add Access Control Entries (ACEs) for users or groups.
To access the dataset (filesystem) permissions, click on the dropdown list to the right of each share then on Edit Filesystem ACL to open the Edit ACL screen for the dataset associated with the share. You can also go to Datasets, select the dataset (same name as the share), then click Edit on the Permissions widget to open the Edit ACL screen.
Samba Authentication selected by default when SMB share users are created or added to TrueNAS manually or through a directory service, and these users are automatically added to the builtin-users group. Users in this group can add or modify files and directories in the share.
The share dataset ACL includes an ACE for the builtin-users group, and the @owner and @group are set to root by default. Change the @owner and @group values to the admin (Full admin) user and click Apply under each.
To restrict or grant additional file permissions for some or all share users, do not modify the builtin-users group entry. Best practice is to create a new group for the share users that need different permissions, reassign these users to the new group and remove them from builtin-users group. Next, edit the ACL by adding a new ACE entry for the new group, and then modify the permissions of that group.
Private dataset (home share) users can modify the builtin-users group ACE entry to grant FULL_CONTROL
If you need to restrict or increase permissions for some share users, create a new group and add an ACE entry with the modified permissions.
To change permissions for the builtin_users group, go to Datasets, select the share dataset, and scroll down to the Permissions widget.
Click Edit to open the Edit ACL screen. Locate the ACE entry for the builtin-users group and click on it.
Check the Access Control List area to see the if the permissions are correct.
Enter or select Group in the Who field.
Begin typing builtin_users in the Group field until it displays, then click on it to populate the field.
Select Basic in the Permissions area then select the level of access you want to assign in the Permissions field. For more granular control, select Advanced then select on each permission option to include.
Click Save Access Control List to add the ACE item or save changes.
To change the permission level for some share users, add a new group, reassign the user(s) to the new group, then modify the share dataset ACL to include this new group and the desired permissions.
Go to Groups, click Add and create the new group.
Go to Users, select a user, click Edit, remove the builtin-user entry from Auxiliary Groups and add the new group. Click Save. Repeat this step for each user or change the group assignment in the directory server to the new group.
Edit the filesystem (dataset) permissions. Use one of the methods to access the Edit ACL screen for the share dataset.
Add a new ACE entry for the new group. Click Add Item.
Select Group in the Who field, type the name into the Group field, then set the permission level.
Select Basic in the Permissions area then select the level of access you want to assign in the Permissions field. For more granular control, select Advanced then select on each permission option to include.
Click Save Access Control List.
If restricting this group to read only and the share dataset is nested under parent datasets, go to each parent dataset, edit the ACL. Add an ACE entry for the new group, and select Traverse. Keep the parent dataset permission set to either Full_Control or MODIFY but select Traverse.
If a share dataset is nested under other datasets (parents), you must add the ACL Traverse permission at the parent dataset level(s) to allow read-only users to move through directories within an SMB share.
After adding the group and assigning it to the user(s), next modify the dataset ACLs for each dataset in the path (parent datasets and the share dateset).
Add the new group to the share ACL. Use one of the methods to access the Edit ACL screen for the share dataset.
Add a new ACE entry for the new group. Click Add Item to create an ACE for the new group.
Select Group in the Who field, type the name into the Group field, then set the permission level.
Click Save Access Control List.
Return to the Datasets screen, locate the parent dataset for the share dataset, use one of the methods to access the Edit ACL screen for the parent dataset.
Add a new ACE entry for the new group. Click Add Item to create an ACE for the new group.
Select Group in the Who field, type the name into the Group field, then select Traverse.
Click Save Access Control List.
Repeat for each parent dataset in the path. This allows the restricted share group to navigate through the directories in the path to the share dataset.
To connect to an SMB share, start the SMB service.
After adding a new share, TrueNAS prompts you to start or restart the SMB service.
You can also start the service from the Windows (SMB) Share widget or on the System > Services screen from the SMB service row.
From the Sharing screen, click on the Windows (SMB) Shares to display the service options, which are Turn Off Service if the service is running or Turn On Service if the service is not running.
Each SMB share on the list also has a toggle to enable or disable the service for that share.
To make SMB share available on the network, go to System > Services and click the SMB toggle. Set Start Automatically if you want the service to activate when TrueNAS boots.
Configure the SMB service by clicking Config Service from the dropdown menu on the Windows (SMB) Shares widget header or by clicking edit on the Services screen. Unless you need a specific setting or are configuring a unique network environment, we recommend using the default settings.
The instructions in this section cover mounting the SMB share on a system with the following operating systems.
External SMB shares are essentially redirects to shares on other systems. Administrators might want to use this when managing multiple TrueNAS systems with SMB shares, and if they do not want to keep track of which shares are on which boxes for clients. This feature allows admins to see and connect to any TrueNAS system with external shares active.
Create the SMB share on another TrueNAS remote server (for example, system1), as described in Adding an SMB Share above.
We recommend using Active Directory or LDAP when creating user accounts, but at a minimum, synchronize user accounts between the system with the share (system1) and on the TrueNAS system where you set up the external share (for example, system2).
On system2 (the local system), select External Share, enter the full domain name or IP address, and the share name.
Separate the server and share name with the \ character. Example: 192.168.0.200\SHARE in Remote Path.
Click Save to add the share.
Repeat the system2 instructions above on system1 to see the SMB shares on each system.
Repeat for each TrueNAS system with SMB shares to add as an external share.
When setting up an external share between TrueNAS systems that are on different releases, for example, one system is on 25.04 and the other is on the latest release of 25.10, follow the external share instructions for each release.
Set the TrueNAS 25.04 system SMB Purpose to the default preset, leave the default settings associated with this share as is, and then enter the redirect path to share on the 25.10 system as EXTERNAL:ipaddress\sharename in the Path field. For example, EXTERNAL:10.220.3.33\testshare2. Be aware, changing the path also changes the SMB share name. Verify the share name is set to the desired or existing share name and not renamed to the redirect string in Path.
Set the TrueNAS 25.10 system SMB Purpose to External Share, and then enter the path to the share on the 25.04 system as ipaddress*sharename* in the Remote Path field. For example, 10.220.1.34*testshare*.
Add descriptions to each share that identify the purpose of the share. The description shows on the Windows (SMB) Shares widget and the SMB screen.
Save changes made to the share.