TrueNAS SCALETrueNAS Nightly Development Documentation
This content follows experimental nightly development software. Pre-release software is intended for testing purposes only.
Use the Product and Version selectors above to view content specific to a stable software release.

Windows Shares (SMB)

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.

Sharing Administrator Access

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

How do I add an SMB Share?

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

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

  2. Create the SMB share and dataset. 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.

    You can create the dataset and share on the Add Dataset screen or create the share and dataset on the Add SMB Share screen. The procedure in this article provides the instructions to add the dataset while adding the share.

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

Creating SMB Share User Accounts

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 users or edit users, go to Credentials > Users to add or edit the SMB share user(s). Click Add to create a new or as many new user accounts as you need.

Enter the values in each required field, verify Samba Authentication 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.

Why not just allow anonymous access to the share? Anonymous or guest access to the share is possible, but it is a security vulnerability and not recommended for Enterprise or systems with more than one SMB share administrator account. Using a guest account also increases the likelihood of unauthorized users gaining access to your data. Major SMB client vendors are deprecating it, partly because signing and encryption are impossible for guest sessions.
What about LDAP users?
Support for LDAP Samba Schema is deprecated in TrueNAS 22.02 (Angelfish) and removed in 24.10 (Electric Eel). Migrate legacy Samba domains to Active Directory before upgrading to 24.10 or later.

Adding an SMB Share and Dataset

You can create an SMB share while creating a dataset on the Add Dataset screen or create the dataset while creating 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.
What are ZFS dataset setting defaults?

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.

To create a basic Windows SMB share and a dataset, go to Shares and click Add on the Windows Shares (SMB) widget to open the Add Share screen.

Add SMB Basic Options
Figure 1: Add SMB Basic Options
  1. Enter or browse to select 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.

    Browsing to select a path

    Click the arrow to the left of the folder icon to expand that folder and show any child datasets and directories. A solid folder icon shows for datasets and an outlined folder for directories. A selected dataset or directory folder and name shows in blue.

  2. Click Create Dataset. Enter the name for the share dataset in the Create Dataset dialog, then click Create. The system creates the new dataset.

    Name becomes the dataset name entered and is the SMB 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. It cannot have 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 hostname 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.

  3. (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 or Default share parameters.

  4. (Optional) Enter a Description to help explain the share purpose.

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

  6. (Optional) Click Advanced Options to configure audit logging or other advanced configuration settings such as changing Case Sensitivity.

  7. Click Save to create the share and add it to the Shares > Windows (SMB) Shares list.

Enable the SMB service when prompted.

Configuring Share Advanced Options Settings

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.

Setting Up Guest Access

If you want to allow guest access to the share, select Allow Guest Access. 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.

If setting up guest access with read only permissions, see the information in Adding a New Share Group. If the share is nested under parent datasets, see Using the Traverse Permission.

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.

Use the Hosts Allow field to enter a list of allowed hostnames or IP addresses. Separate entries by pressing Enter.

Entering values in the Host Allow restricts access to only the addresses entered into this list! You can break UI access for all other IP or host name entries by using this list.

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:

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

Enabling SMB Audit Logging To enable SMB audit logging, from either the Add SMB or Edit SMB screens, click Advanced Options, scroll down to Audit Logging and select Enable.

Enabling ACL Support

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.

Tuning ACLs for SMB Shares

There are two levels to set SMB share permissions, at the share or for the dataset associated for with the share. See Managing SMB Shares for more information on these options.

See Permissions for more information on dataset permissions.

Tuning the Share ACL

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

Tuning the Dataset (Filesystem) Permissions

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

Changing the built-in-user Group Permissions

To change permissions for the builtin_users group, go to Datasets, select the share dataset, and scroll down to the Permissions widget.

  1. Click Edit to open the Edit ACL screen. Locate the ACE entry for the builtin-users group and click on it.

  2. Check the Access Control List area to see the if the permissions are correct.

  3. Enter or select Group in the Who field.

  4. Begin typing builtin_users in the Group field until it displays, then click on it to populate the field.

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

  6. Click Save Access Control List to add the ACE item or save changes.

Adding a New Share Group

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.

  1. Go to Groups, click Add and create the new group.

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

  3. Edit the filesystem (dataset) permissions. Use one of the methods to access the Edit ACL screen for the share dataset.

  4. Add a new ACE entry for the new group. Click Add Item.

  5. Select Group in the Who field, type the name into the Group field, then set the permission level.

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

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

Using the Traverse Permission

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

  1. Add the new group to the share ACL. Use one of the methods to access the Edit ACL screen for the share dataset.

  2. Add a new ACE entry for the new group. Click Add Item to create an ACE for the new group.

  3. Select Group in the Who field, type the name into the Group field, then set the permission level.

  4. Click Save Access Control List.

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

  6. Add a new ACE entry for the new group. Click Add Item to create an ACE for the new group.

  7. Select Group in the Who field, type the name into the Group field, then select Traverse.

  8. Click Save Access Control List.

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

Starting the SMB Service

To connect to an SMB share, you must start the related system service.

After adding a new share the system 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.

Starting the Service Using the Windows SMB Share

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.

SMB Service Options
Figure 5: SMB Service Options

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 > Services and click the toggle for SMB. Set Start Automatically if you want the service to activate when TrueNAS boots.

Configuring the SMB Service

Configure the SMB service by clicking Config Service from the more_vert dropdown menu on the Windows (SMB) Shares widget header 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.

Mounting the SMB Share

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.

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

To permanently mount the SMB share in Windows, map a drive letter in the computer for the user to the TrueNAS SCALE IP and share name. Select a drive letter from the bottom of the alphabet rather than from the top to avoid assigning a drive dedicated to some other device. The example below uses Z. Open the command line and run the following command with the appropriate drive letter, TrueNAS system name or IP address, and the share name.

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

Where:

  • Z is the drive letter to map to TrueNAS and the share
  • TrueNAS_name is either the hostname or system IP address
  • share_name is the name given to the SMB share

To temporarily connect to a share, you can open a Windows File Explorer window, type \\TrueNAS_name\share_name then enter the user credentials you want to authenticate with to connect to the share. Windows remembers the user credentials so each time you connect it uses the same authentication credentials unless you reboot the system, then you are prompted to enter the authentication credentials again.

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.

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.

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

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

Setting up an External SMB Share

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 don’t want to keep track of which shares live on which boxes for clients. This feature allows admins to connect to any of the TrueNAS systems with external shares set up and see them all.

Create the SMB share on another SCALE 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 SCALE system where you set up the external share (for example, system2).

On system2, enter the hostname or IP address of the system hosting the SMB share (system1) and the name given 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.

Set Up Another External SMB Share
Figure 6: Set Up Another External SMB Share

Repeat for each SCALE system with SMB shares you want added 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.

SMB Shares Contents

These tutorials describe creating and managing various specific configurations of SMB shares.