Setting Up SMB Home Shares

SMB Home Shares are a legacy feature for organizations looking to maintain existing SMB configurations. They are not recommended for new deployments.

Future TrueNAS SCALE releases can introduce instability or require configuration changes affecting this legacy feature.

TrueNAS offers the Use as Home Share option, found in the Add SMB and Edit SMB screen Advanced Options settings in the Other Options section, for organizations or SMEs that want to use a single SMB share to provide a personal directory to every user account.

With home shares, each user is given a personal home directory when connecting to the share. These home directories are not accessible by other users. You can use only one share as the home share, but you can create as many non-home shares as you need or want.

Creating an SMB home share requires configuring the system storage and joining Active Directory.

Go to Credentials > Local Users and click Add. Create a new user name and password.

By default, the user Home Directory title comes from the user account name and is added as a new subdirectory of Home_Share_Dataset.

If existing users require access to the home share, go to Credentials > Local Users and edit an existing account.

Adjust the user home directory to the appropriate dataset and give it a name to create its own directory.

SCALE 24.04 changes the default user home directory location from /nonexistent to /var/empty. This new directory is an immutable directory shared by service accounts and accounts that should not have a full home directory.

Existing users with an SMB Home Share who upgrade to 24.04 can experience disruptions to the following services:

• SMB shares
• SSH
• Shell access

Users with an SMB Home Share should review local user accounts for any with home directories set to /nonexistent. Update the home directory path to /var/empty for all affected accounts. Accounts with an existing home directory other than /nonexistent do not need to be modified.

Why the change?

TrueNAS uses the pam_mkhomdir PAM module in the pam_open_session configuration file to automatically create user home directories if they do not exist. pam_mkhomedir returns PAM_PERM_DENIED if it fails to create a home directory for a user, which eventually turns into a pam_open_session() failure. This does not impact other PAM API calls, for example, pam_authenticate().

TrueNAS SCALE does not include the customized version of pam_mkhomedir used in TrueNAS CORE that specifically avoided trying to create the /nonexistent directory. This led to some circumstances where users could create the /nonexistent directory on SCALE versions before 24.04.

Starting in SCALE 24.04 (Dragonfish), the root filesystem of TrueNAS is read-only, which prevents pam_mkhomdir from creating the /nonexistent directory in cases where it previously did. This results in a permissions error if pam_open_session() is called by an application for a user account that has Home Directory set to /nonexistent.

You can use Active Directory or LDAP to create share users.

If not already created, add a pool, then join Active Directory.

Go to Storage and create a pool.

Next, set up the Active Directory that you want to share resources with over your network.

You can either add the share when you create the dataset for the share on the Add Dataset screen, or create the dataset when you add the share on the Add SMB screen. If you want to customize the dataset, use the Add Dataset screen.

To create a basic dataset, go to Datasets. Default settings include those inherited from the parent dataset.

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

Enter a value in Name.

Select the Dataset Preset option you want to use. Options are:

• Generic for non-SMB share datasets such as iSCSI and NFS share datasets or datasets not associated with application storage.
• Multiprotocol for datasets optimized for SMB and NFS multi-mode shares or to create a dataset for NFS shares.
• SMB for datasets optimized for SMB shares.
• Apps for datasets optimized for application storage.

Generic sets ACL permissions equivalent to Unix permissions 755, granting the owner full control and the group and other users read and execute privileges.

SMB, Apps, and Multiprotocol inherit ACL permissions based on the parent dataset. If there is no ACL to inherit, one is calculated granting full control to the owner@, group@, members of the builtin_administrators group, and domain administrators. Modify control is granted to other members of the builtin_users group and directory services domain users.

Apps includes an additional entry granting modify control to group 568 (Apps).

ACL Settings for Dataset Presets

	ACL Type	ACL Mode	Case Sensitivity	Enable atime
Generic	POSIX	n/a	Sensitive	Inherit
SMB	NFSv4	Restricted	Insensitive	On
Apps	NFSv4	Passthrough	Sensitive	Off
Multiprotocol	NFSv4	Passthrough	Sensitive	Off

If creating an SMB or multi-protocol (SMB and NFS) share the dataset name value auto-populates the share name field with the dataset name.

If you plan to deploy container applications, the system automatically creates the ix-applications dataset, but this dataset is not used for application data storage. If you want to store data by application, create the dataset(s) first, then deploy your application. When creating a dataset for an application, select Apps as the Dataset Preset. This optimizes the dataset for use by an application.

If you want to configure advanced setting options, click Advanced Options. For the Sync option, we recommend production systems with critical data use the default Standard choice or increase to Always. Choosing Disabled is only suitable in situations where data loss from system crashes or power loss is acceptable.

Select either Sensitive or Insensitive from the Case Sensitivity dropdown. The Case Sensitivity setting is found under Advanced Options and is not editable after saving the dataset.

Click Save.

Review the Dataset Preset and Case Sensitivity under Advanced Options on the Add Dataset screen before clicking Save. You cannot change these or the Name setting after clicking Save.

To use the Add SMB screen, Click Add on the Windows (SMB) Shares widget to open the screen.

Set the Path to the existing dataset created for the share, or to where you want to add the dataset, then click Create Dataset.

Enter a name for the dataset and click Create Dataset. The dataset name populates the share Name field and updates the Path automatically. The dataset name becomes the share name. Leave this as the default. If you change the name follow the naming conventions for:

• Files and directories
• Share names

Set the Purpose to No presets, then click Advanced Options. Scroll down to Other Options and set Use as Home Share. Click Save.

Enable the SMB service when prompted to make the share available on your network.

After saving the dataset, set the permissions.

After creating the share and dataset, you can edit permissions using either the Edit option on the Permissions widget for the dataset or use the Edit Filesystem ACL option for the share on the Windows (SMB) Share widget to open the ACL edit screen for the share dataset. See SMB Shares for more information on editing the share dataset permissions.

Click on the new dataset. Scroll down to the Permissions widget and click Edit.

Click the Owner dropdown and select the owner, then repeat for Group. Change the owning group to your Active Directory domain admins. Select Apply Owner and Apply Group.

Click Use an ACL Preset and choose NFS4_HOME. Then, click Continue.

After adding the user accounts and configuring permissions, users can log in to the share and see a folder matching their user name.