TrueNAS SCALE Version Documentation
This content follows the TrueNAS SCALE 23.10 (Cobia) releases. Use the Product and Version selectors above to view content specific to different TrueNAS software or major version.

Adding SMB Shares

13 minute read.

Last Modified 2024-03-19 08:38 EDT

About Windows (SMB) Shares

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) usage is deprecated for security reasons.

As of SCALE 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 SCALE 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.

Adding an SMB share to your system involves several steps to add the share and get it working.

Set up a dataset for the new share.
Create local user accounts. You can also use directory services like Active Directory or LDAP to provide additional user accounts.
Modify the dataset ACL. After adding or modifying local users, edit the dataset permissions.
Create the SMB share. You can create a basic SMB share, or for more specific share types or feature requirements, use the Advanced Options instructions before saving the share.

After adding the share, start the service and mount it to your other system.

Before creating the SMB share, create the dataset you want the share to use for data storage.

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.

We recommend creating a new dataset with the Share Type set to SMB for the new SMB share.

TrueNAS creates the ZFS dataset with these settings:

ACL Mode set to Restricted The ACL Type influences the ACL Mode setting. When ACL Type is set to Inherit, you cannot change the ACL Mode setting. When ACL Type is set to NFSv4, you can change the ACL Mode to Restricted.
Case Sensitivity set to Insensitive

TrueNAS also applies a default access control list to the dataset. This default ACL is restrictive and only grants access to the dataset owner and group. You can modify the ACL later according to your use case.

Creating a Dataset

To create a dataset using the default settings, go to Datasets. Default settings include the settings datasets inherit from the parent dataset.

Select a dataset (root, parent, or child), then click Add Dataset.

Enter a value in Name.

Select either Sensitive or Insensitive from the Case Sensitivity dropdown.

Select the Share Type, then click Save. Options are Generic, Multiprotocol, SMB, or Apps.

You can create datasets optimized for SMB shares or with customized settings for your dataset use cases.

If you plan to deploy container applications, the system automatically creates the ix-applications dataset, but it is not used for application data storage. If you want to store data by application, create the dataset first, then deploy your application. When creating a dataset for an application, select App as the Share Type setting. This optimizes the dataset for use by an application.

Review the Share Type and Case Sensitivity options on the configuration screen before clicking Save. You cannot change these or the Name setting after clicking Save.

Creating Local User Accounts

Use Credentials > Local Users to add new users to your TrueNAS.

By default, all new local users are members of a built-in SMB group called builtin_users.

Click here for more information

For more information on the builtin_users group, go to Credentials > Local Users and click Toggle Built-In Users at the top right of the screen. Scroll down to the smbguest user and click on the name. Click Edit to view the Edit User screen. The Auxiliary Group field displays the builtin_user group.

You can use the group to grant access to all local users on the server or add more groups to fine-tune permissions to large numbers of users.

You cannot access SMB shares using the root user, TrueNAS built-in user accounts, or those without the smb flag.

Why not just allow anonymous access to the share?

Anonymous or guest access to the share is possible, but it is a security vulnerability. Major SMB client vendors are deprecating it, partly because signing and encryption are impossible for guest sessions.

What about LDAP users?

If you want LDAP server users to access the SMB share, go to Credentials > Directory Services. If you configured an LDAP server, select the server and click Edit to display the LDAP configuration screen. If not configured, click Configure LDAP to display the LDAP configuration screen. Click Advanced Options and select Samba Schema (DEPRECATED - see the help text).

Only enable LDAP authentication for the SMB share if you require it. Your LDAP server must have Samba attributes. Support for Samba Schema is officially deprecated in Samba 4.13. Samba Schema is no longer in Samba after 4.14. Users should begin upgrading legacy Samba domains to Samba AD domains.

Local TrueNAS user accounts can no longer access the share.

Tuning the Dataset ACL

After creating a dataset and accounts, you need to investigate your access requirements and adjust the dataset ACL to match. Many home users typically add a new ACL entry that grants FULL_CONTROL to the builtin_users group with the flags set to INHERIT.

Click here for instructions

To change or add permissions for the builtin_users group, go to Datasets:

Click on the name of the dataset you created for the SMB share to use.
Scroll down to the Permissions widget. Click Edit to open the Edit ACL screen.
Check the Access Control List to see if this user is on the list and has the correct permissions. If not, add this ACE item.
Figure 3: Edit ACL Permissions
a. Enter Group in the Who field or use the dropdown list to select Group.
b. Begin typing builtin_users in the Group field to display a filtered list of groups you can select from, then select builtin_users.
c. Verify Full Control displays in Permissions. If not, select it from the dropdown list.
d. Click Save Access Control List to add the ACE item or save changes.

If you want to allow users to move through directories within an SMB share without having read or write privileges, you must use the Traverse permission. Use Traverse if you intend to have nested groups within an SMB share with different access levels.

See Permissions for more information on editing dataset permissions.

You cannot access SMB shares with the root user. Always change SMB dataset ownership to the intended SMB user.

To create a basic Windows SMB share, go to Shares.

Click on Windows Shares (SMB) to select it and then click Add. The Add SMB configuration screen displays the Basic Options settings.
Figure 4: Add SMB Basic Options
Enter the SMB share Path and Name.
The Path is the directory tree on the local file system that TrueNAS exports over the SMB protocol.
The Name is the SMB share name, which 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. It cannot have invalid characters as specified in Microsoft documentation MS-FSCC section 2.1.6. If you do not enter a name, the share name becomes the last component of the path. If you change the name, follow the naming conventions for:
- Files and directories
- Share names
(Optional) Select a preset from the Purpose dropdown list to apply and lock or unlock pre-determined Advanced Options settings for the share. To retain control over all the share Advanced Options settings, select No presets.
(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 if you want to disable the share without deleting the configuration.
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, you do not need to use the Advanced Options settings, 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, but for all settings, see SMB Shares Screens.

Enabling ACL Support

To add ACL support to the share, select Enable ACL, and then see Managing SMB Shares for more on configuring permissions for the share and the file system.

Setting Up Guest Access

If you want to allow guest access to the share, select Allow Guest Access.

Click here for more information

The privileges are the same as the guest account. Windows 10 version 1709 and Windows Server version 1903 disable guest access by default. Additional client-side configuration is required to provide guest access to these clients.

MacOS clients: Attempting to connect as a user that does not exist in TrueNAS does not automatically connect as the guest account.
Connect As: Guest Specifically choose this option in macOS to log in as the guest account. See the Apple documentation for more details.

Setting Up Read or Write Access

To prohibit writes to the share, select Export Read-Only.

To restrict share visibility to users with read or write access to the share, select Access Based Share Enumeration. See the smb.conf manual page.

Setting Up Host Allow and Host Deny

Use the Host Allow and Host Deny options to allow or deny specific host names and IP addresses.

Click here for more information

Use the Hosts Allow field to enter a list of allowed hostnames or IP addresses. Separate entries by pressing Enter. You can find a more detailed description with examples here. Use the Hosts Deny field to enter a list of denied hostnames or IP addresses. Separate entries by pressing Enter.

Hosts Allow and Hosts Deny work together to produce different situations:

If neither Hosts Allow nor Hosts Deny contains an entry, any host can access the SMB share.
If you create a Hosts Allow list, but no Hosts Deny list, the share only allows hosts on the Hosts Allow list.
If you create a Hosts Deny list, but no Hosts Allow list, the share allows all hosts not on the Hosts Deny list.
If you create both a Hosts Allow and Hosts Deny list, the share allows all hosts on the Hosts Allow list. The share also allows hosts not on the Hosts Allow or Hosts Deny list.

Apple Filing Protocol (AFP) Compatibility

AFP shares are deprecated and not available in SCALE. To customize your SMB share to work with a migrated AFP share or with your MacOS, use the Advanced Options settings provided for these use cases.

Click here for more information

Time Machine enables Apple Time Machine backups on this share.

Legacy AFP Compatibility controls how the SMB share reads and writes data. Leave unset for the share to behave like a standard SMB share. Only set this when the share originated as an AFP sharing configuration. Pure SMB shares or macOS SMB clients do not require legacy compatibility.

Use Apple-style Character Encoding converts NTFS illegal characters in the same manner as MacOS SMB clients. By default, Samba uses a hashing algorithm for NTFS illegal characters.

Starting the SMB Service

To connect to an SMB share, you must start the related system service. You can start the service from the Windows SMB Share header on the Sharing screen or in System Settings > Services.

From the Sharing screen, click on the Windows (SMB) Shares more_vert 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.

Starting the Service Using System Settings

To make SMB share available on the network, go to System Settings > Services and click the toggle for SMB. Set Start Automatically if you want the service to activate when TrueNAS boots.

Service Configuration

Configure the SMB service by clicking Config Service from the more_vert dropdown menu on the Shares screen or by clicking 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.

Mounting on a Linux System

Verify that your Linux distribution has the required CIFS packages installed.

Click here for more information

Create a mount point: sudo mkdir /mnt/smb_share.

Mount the volume. sudo mount -t cifs //computer_name/share_name /mnt/smb_share.

If your share requires user credentials, add the switch -o username= with your username after cifs and before the share address.

Mounting on a Windows System

Have the information on the Windows drive letter, computer name, and share name ready before you start.

Click here for more information

To mount the SMB share to a drive letter on Windows, open the command line and run the following command with the appropriate drive letter, computer name, and share name.

net use Z: \\computer_name\share_name /PERSISTENT:YES

Mounting on an Apple System

Have the user name and password for the user assigned to the pool or for the guest if the share has guest access ready before you begin.

Click here for more information

Open Finder > Go > Connect To Server Enter the SMB address: smb://192.168.1.111.

Input the username and password for the user assigned to that pool or guest if the share has guest access.

Mounting on a FreeBSD System

Mounting on a FreeBSD system involves creating the mount point, then mounting the volume.

Click here for more information

Create a mount point: sudo mkdir /mnt/smb_share.

Mount the volume. sudo mount_smbfs -I computer_name\share_name /mnt/smb_share.

Adding SMB Shares