Windows Shares (SMB)
23 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, MacOS, 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. An SMB client typically negotiates the highest supported SMB protocol during SMB session negotiation. 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 not 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 you require this functionality.
MacOS 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 SMB servers, but 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 further 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 to start/restart the sharing service, but does not permit the user to modify users to 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 Active Directory connections are working and error-free before adding an SMB share. If configured but not working or in an error state, AD cannot bind and prevents starting the SMB service.
Creating an SMB share on your system involves several steps to add the share and get it working.
Create the SMB share user account. You can also 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 for more specific share types or feature requirements from the Add SMB screen using the Advanced Options instructions before saving the share.
TrueNAS allows creating the dataset and share at the same time from either the Add Dataset screen or the Add SMB share screen. Use either option to create a basic SMB share, but when customizing share use the Add SMB screen presets and advanced options to create the share and dataset. The procedure in this article provides the instructions to add the dataset while adding the share using the Add SMB screen.
Modify the share permissions. After adding or modifying the user account for the share, edit the dataset permissions.
After adding the share, start the service and mount it 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 to add or edit the SMB share user(s). Click Add to create a new user or as many new user accounts as needed. If joined to Active Directory, it can create the TrueNAS 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 the dataset and the share on the Add SMB Share screen. This article covers adding the dataset on 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.
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) to populate the Path field. The Path is the directory tree on the local file system that TrueNAS exports over the SMB protocol.
Click Create Dataset. Enter the name for the share and dataset in the Create Dataset dialog, then click Create. The system creates the new dataset and the share and populates the Name field with the dataset name.
The value entered in Name becomes the dataset and share name. This 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:
If creating an external SMB share, enter the host name or IP address of the system hosting the SMB share and the name of the share on that system. Enter as EXTERNAL:ip address\sharename in Path, then change Name to EXTERNAL with no special characters.
Select a preset from the Purpose dropdown list to apply. The preset selected locks or unlocks the pre-determined Advanced Options settings for the share.
To retain control over all the share Advanced Options settings, select No presets or Default share parameters.
To create a multi-protocol share (NFSv4/SMB), select Multi-protocol (NFSv4/SMB) 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 SMB Datasets and Shares. See Setting Up SMB Home Shares for more information on replacing this legacy feature with private SMB shares and datasets.
(Optional) Enter a Description to help explain the share purpose.
Select Enabled to allow sharing of this path when the SMB service is activated. Leave it cleared to disable the share without deleting the configuration.
(Optional) Click Advanced Options to configure audit logging or other advanced configuration settings such as changing Case Sensitivity.
Click Save to create the share and add it to the Shares > Windows (SMB) Shares list.
Enable the SMB service when prompted.
For a basic SMB share, using the Advanced Options settings is not required, but if you set Purpose to No Presets, click Advanced Options to finish customizing the SMB share for your use case.
The following are possible use cases. See SMB Shares Screens for all settings and other possible use cases.
To add ACL support to the share, select Enable ACL under Advanced Options on either the Add SMB or Edit SMB screens. See Managing SMB Shares for more on configuring permissions for the share and the file system.
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 icon to open the Edit Share ACL screen if you want 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, either click the «span class=“material-icons”>security> Edit Filesystem ACL icon on the share row to open the Edit ACL screen for the dataset the share uses. You can also go to Datasets, select the dataset the share uses (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.
Home 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 either 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 toggle for SMB. 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 connect to any of the TrueNAS systems with external shares set up, and to see them all.
Create the SMB share on another TrueNAS 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, enter the host name or IP address of the system hosting the SMB share (system1) and the name given to the share on that system as EXTERNAL:ip address\sharename in Path, then change Name to EXTERNAL with no special characters.
Leave Purpose set to Default share parameters, leave Enabled selected, then click Save to add the share redirect.
Repeat the system2 instructions above to add an external redirect (share) on system1 to see the SMB shares of each system.
Repeat for each TrueNAS system with SMB shares to add as an external redirect. Change the auto-populated name to EXTERNAL2 or something to distinguish it from the SMB shares on the local system (system1 in this case) and any other external shares added.