Adding SMB Shares
15 minute read.Last Modified 2023-11-27 10:04 EST
As of SCALE 22.12 (Bluefin), MS-DOS SMB1 clients cannot connect to TrueNAS SCALE Bluefin. TrueNAS SCALE SMB does not support End-of-Life (EoL) Windows clients, including MS-DOS.
The Samba project, which TrueNAS SCALE uses to provide SMB sharing features, has deprecated the SMB1 protocol for security concerns. The Samba 4.16 release notes announced that they deprecated and disabled the whole SMB1 protocol as of 4.11. If needed, for security purposes or code maintenance, Samba continues to remove older protocol commands and unused dialects or those that are replaced in more modern SMB1 versions.
TrueNAS now uses Samba 4.17. TrueNAS still has SMB1 protocol support but:
- MS-DOS-based SMB clients cannot connect to TrueNAS SCALE Bluefin.
- MS-DOS-based SMB clients are no longer able to connect to any TrueNAS servers.
- SMB clients determined to be end-of-life (EOL) by their vendor are not supported.
Administrators should work to phase out any clients using the SMB1 protocol from their environments.
Client systems that can only use the SMB1 protocol for SMB shares are no longer capable of connecting to SMB shares created in TrueNAS SCALE 22.12 or later.
Refer to Samba release notes for more information.
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. 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 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.
Modify the dataset permissions. After adding or modifying the user account for the share, edit the dataset permissions.
Before creating the SMB share, create the dataset for 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 SMB shares.
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.
Use Credentials > Local Users to add or edit the SMB share user(s).
By default, all new local users are members of a built-in SMB group called builtin_users. 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.
After creating a dataset and share user account(s), 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.
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 Add on the Windows Shares (SMB) widget. The Add SMB configuration screen displays the Basic Options settings.
Enter or browse to select SMB share dataset to populate the Path field, then enter or verify the name auto-filled in 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:
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.
(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.
(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.
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.
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.
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) Sharesto 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 Settings > 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 thedropdown menu on the Shares screen 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 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.
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.