diff --git a/content/SCALE/SCALETutorials/Shares/SMB/AddSMBHomeShare.md b/content/SCALE/SCALETutorials/Shares/SMB/AddSMBHomeShare.md index 81c8117005..6bd2b01cd5 100644 --- a/content/SCALE/SCALETutorials/Shares/SMB/AddSMBHomeShare.md +++ b/content/SCALE/SCALETutorials/Shares/SMB/AddSMBHomeShare.md @@ -1,6 +1,6 @@ --- title: "Setting Up SMB Home Shares" -description: "Provides instructions to set up SMB home shares." +description: "Provides instructions on setting up private SMB datasets and shares as an alternative to legacy SMB home shares." weight: 40 aliases: tags: @@ -14,103 +14,159 @@ They are not recommended for new deployments. Future TrueNAS SCALE releases can introduce instability or require configuration changes affecting this legacy feature. {{< /hint >}} -## Setting Up SMB Home Shares -The **Use as Home Share** option, found in the **Add SMB** and **Edit SMB** screen **Advanced Options** settings in the **Other Options** section, is an available option for organizations or SMEs that want to use a single SMB share to provide a personal directory to every user account. +## Replacing SMB Home Shares +TrueNAS does not recommend setting up home shares with the **Use as Home Share** option, found in the **Add SMB** and **Edit SMB** screen **Advanced Options** settings, in the **Other Options** section. +This option is for organizations still using the legacy home shares option of adding a single SMB share to provide a personal directory for every user account. -With home shares, each user is given a personal home directory when connecting to the share. +Users wanting to create the equivalent of home shares should use the intructions in the [Adding Private SMB Datasets and Shares](#adding-private-smb-datasets-and-shares) section below for the recommended method for creating private shares and datasets. + +The legacy home shares provide each user 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. - Other options for configuring individual user directories include: * Configure a single share on the TrueNAS and provision individual user directories on the client OS. * Create a single SMB share and configure the ACL so that users can create individual directories on the share that inherit write access for the user and grant read access the administrator. -* Create an SMB share using the **Private SMB datasets and shares** preset that can create per-user datasets under the umbrella of a single share when users access the share. +* Create an SMB share using the **Private SMB datasets and shares** preset; and then create per-user datasets under the umbrella of a single share when users access the share. Creating an SMB home share requires configuring the system storage and provisioning users or joining Active Directory. -### Adding Local Share Users -Go to **Credentials > Users** and click **Add**. -Create a new user name and password. +## Adding Private SMB Datasets and Shares +This option allows creating private share and datasets for the users that require the equivalent of the legacy home share. +It is not intended for every user on the system. +Setting up private SMB shares and datasets prevents the system from showing these to all users with access to the root level of the share. +Examples of private SMB shares are those for backups, system configuration, and users or departments that need to keep information private from other users. -By default, the user **Home Directory** title comes from the user account name and is added as a new subdirectory of **Home_Share_Dataset**. +Before setting up SMB shares check system alerts to verify there are no errors related to connections to Active Directory. +Resolve any issues with Active Directory before proceeding. If Active Directory cannot bind with TrueNAS you cannot start the SMB service after making changes. -![AddUserDirPermsAuthSettings](/images/SCALE/Credentials/AddUserDirPermsAuthSettings.png "Add User Directories, Permissions and Authentication Settings") +To add private shares and datasets for users that require home directories: -If existing users require access to the home share, go to **Credentials > Users** and edit an existing account. +1. Create the share using the **Private SMB Datasets and Shares** preset. -Adjust the user home directory to the appropriate dataset and give it a name to create its own directory. +2. Configure the share dataset ACL to use the **NFSv4_HOME** preset. -{{< hint type="important" title="Home Directory Known Impacts" >}} -{{< include file="/static/includes/24.04HomeDirectory.md" >}} +3. Create users either manually or through Active Directory. -{{< expand "Why the change?" "v" >}} -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()`. +### Creating the Share and Dataset -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. +{{< include file="/static/includes/LocalSMBUser.md" >}} -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**. -{{< /expand >}} -{{< /hint >}} +You can use an existing dataset for the share or create a new dataset. +You can either add a share when you [create the dataset]({{< relref "DatasetsSCALE.md" >}}) for the share on the **Add Dataset** screen, or create the dataset when you add the share on the **Add SMB** screen. +If creating a simple SMB share and dataset use either method, or if customizing the dataset, use the [**Add Dataset** screen]({{< relref "DatasetsSCALE.md" >}}) to access dataset advanced setting options. +To configure a customized SMB share, use the **Add SMB** share option that provides access to the advanced setting options for shares. +This procedure covers creating the share and dataset from the **Add Share** screen. +To create an alternative to the legacy SMB home share: -### Adding Share Users with Directory Services +1. Go to **Shares**, click **Add** on the **Windows (SMB) Shares** widget to open the **Add SMB** screen. -You can use Active Directory or LDAP to create share users. + If you created the dataset already, you can add the share with the correct share preset on this screen. + If you are creating the share and dataset together you can create both using the correct share preset on this screen. -If not already created, add a pool, then join Active Directory. +2. Browse to or enter the location of an existing dataset or path to where you want to create the dataset to populate the **Path** for the share. + To add a dataset, click **Create Dataset**, enter a name for the dataset, then click **Create Dataset**. + For example, creating a share and dataset named *private*. + + {{< trueimage src="/images/SCALE/Shares/AddPrivateSMBShare.png" alt="Set the Share Path" id="Set the Share Path" >}} -Go to **Storage** and [create a pool]({{< relref "CreatePoolWizard.md" >}}). + Follow naming conventions for: + * [Files and directories](https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file#naming-conventions) + * [Share names](https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-fscc/dc9978d7-6299-4c5a-a22d-a039cdc716ea) -Next, [set up the Active Directory]({{< relref "/SCALE/SCALETutorials/credentials/directoryservices/configadscale.md" >}}) that you want to share resources with over your network. + By default, the dataset name populates the share **Name** field and becomes the share name. The share and dataset must have the same name. It also updates the **Path** automatically. -### Creating the Share and Dataset - -{{< include file="/static/includes/LocalSMBUser.md" >}} +3. Set **Purpose** to the **Private SMB Dataset and Share** preset and click **Advanced Options** to show the additional settings. + Configure the options you want to use. -You can either add the share when you [create the dataset]({{< relref "DatasetsSCALE.md" >}}) 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. + {{< trueimage src="/images/SCALE/Shares/AddPrivateSMBShareAdvancedOptions.png" alt="Add Share Advanced Options" id="Add Share Advanced Options" >}} -{{< include file="/static/includes/CreateDatasetSCALE.md" >}} +4. (Optional) Select Enable for audit logging. + +5. Scroll down to **Other Options** and select **Export Recycle Bin** to allow moving files deleted in the share to a recycle bin in that dataset. + Files are renamed to a per-user subdirectory within .recycle directory at the root of the SMB share if the path is the same dataset as the share. + If the dataset has nested dataset, the directory is at the root of the current dataset. If this is the case, there is not automatic deletion based on file size. -To use the **Add SMB** screen, Click **Add** on the **Windows (SMB) Shares** widget to open the screen. +6. Click **Save**. -Set the **Path** to the existing dataset created for the share, or to where you want to add the dataset, then click **Create Dataset**. +7. Enable or restart the **SMB** service when prompted and make the share available on your network. -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](https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file#naming-conventions) -* [Share names](https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-fscc/dc9978d7-6299-4c5a-a22d-a039cdc716ea) +After saving the dataset and if not already set for the dataset, set the ACL permissions. -Set the **Purpose** to **No presets**, then click **Advanced Options**. -Scroll down to **Other Options** and set **Use as Home Share**. -Click **Save**. +### Setting Dataset ACL Permissions +After creating the share and dataset, edit ACL permissions. +You can access the **Edit ACL** screen either from the **Datasets** or the **Shares** screens. -Enable the **SMB** service when prompted to make the share available on your network. +If starting on the **Datasets** screen, select the dataset row, then click **Edit** on the **Permissions** widget to open the **Edit ACL** screen. +See [Setting Up Permissions]({{< relref "PermissionsSCALE.md" >}}) for more information on editing dataset permissions. -After saving the dataset, set the permissions. +If starting on the **Shares** screen, select the share on the **Windows (SMB) Share** widget, then click **Edit Filesystem ACL** to open the **Edit ACL** screen. +Select the option to edit the file system ACL not the share permissions. +See [SMB Shares]({{< relref "ManageSMBShares.md" >}}) for detailed information on editing the share dataset permissions. -### Setting Dataset 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]({{< relref "ManageSMBShares.md" >}}) for more information on editing the share dataset permissions. +To set the permission for the private dataset and share, the home share alternative scenario, select the **HOME** (if a POSIX ACL) or **NSFv4_HOME** (for NFSv4 ACL) preset option to correctly configure dataset permissions. -Click on the new dataset. Scroll down to the **Permissions** widget and click **Edit**. +Click the **Owner** dropdown and select the administration user with full control, then repeat for **Group**. +You can set the owning group to your Active Directory domain admins. Click **Apply Owner** and **Apply Group**. -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**. +{{< trueimage src="/images/SCALE/Shares/SetACLPresetForPrivateDataset.png" alt="Add Dataset ACL Permissions" id="Add Dataset ACL Permissions" >}} ![GroupDomainAdminsSCALE](/images/SCALE/Datasets/GroupDomainAdmins.png "Set the owning group to Domain Admins") -Click **Use an ACL Preset** and choose **NFS4_HOME**. -Then, click **Continue**. +Next, click **Use Preset** and choose **NFS4_HOME**. If the dataset has a POSIX ACL the preset is **HOME**. +Click **Continue**, then click **Save Access Control List**. -![StoragePoolsOptionsEditPermissionsACLPresetHomeSCALE](/images/SCALE/Datasets/StoragePoolsOptionsEditPermissionsACLPresetHome.png "Set the Home ACL Preset") - -After adding the user accounts and configuring permissions, users can log in to the share and see a folder matching their user name. +Next, add the users that need a private dataset and share. {{< include file="/static/includes/SMBShareMSDOSalert.md" >}} + +### Adding Local Share Users +Go to **Credentials > Users** and click **Add**. +Create a new user name and password. For home directories, make the username all lowercase. + +Add and configure permissions for the user the private share is for to allow log in access to the share and the ability see a folder matching their username. + +By default, the user **Home Directory** is set to **/var/empty**. +You must change this to the path for the new parent dataset created for home directories. +Select the path **/mnt/*poolname*/*datasetname*/*username*** where *poolname* is the name of the pool where you added the share dataset, *datasetname* is the name of the dataset associated with the share, and *username* is the username (all lowercase) and is also the name of the home directory for that username. +Select **Create Home Directory**. + +{{< trueimage src="/images/SCALE/Shares/SetUserHomeDirectoryToPrivate.png" alt="Add User Home Directory for Private Dataset" id="Add User Home Directory for Private Dataset" >}} + +Click **Save**. TrueNAS adds the user and creates the home directory for the user. + +If existing users require access to a home share, go to **Credentials > Users**, select the user, click **Edit** and add the home directory as described above. + +{{< hint type="important" title="Home Directory Known Impacts" >}} +{{< include file="/static/includes/24.04HomeDirectory.md" >}} + +{{< expand "Why the change?" "v" >}} +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 does not include the customized version of `pam_mkhomedir` used in TrueNAS 13.0 and earlier or 13.3 releases. +This version of `pam_mkhomedir` specifically avoided trying to create the `/nonexistent` directory. +This led to some circumstances where users could create the `/nonexistent` directory on TrueNAS versions before 24.04. + +Starting in TrueNAS 24.04 (Dragonfish), the root file system 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**. +{{< /expand >}} +{{< /hint >}} + +### Adding Share Users with Directory Services +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]({{< relref "CreatePoolWizard.md" >}}). + +Next, [set up the Active Directory]({{< relref "/SCALE/SCALETutorials/credentials/directoryservices/configadscale.md" >}}) that you want to share resources with over your network. + + +When creating the share for this dataset, use the **SMB** preset for the dataset but do not add the share from the **Add Dataset** screen. + +Do not share the root directory! + +Go to **Shares** and follow the instructions listed above using the **Private SMB Dataset and Share** preset, and then modifying the file system permissions of the dataset to use the **NFSv4_HOME** ACL preset. diff --git a/content/SCALE/SCALETutorials/Shares/SMB/_index.md b/content/SCALE/SCALETutorials/Shares/SMB/_index.md index a69385e9f8..ee30adccad 100644 --- a/content/SCALE/SCALETutorials/Shares/SMB/_index.md +++ b/content/SCALE/SCALETutorials/Shares/SMB/_index.md @@ -12,8 +12,8 @@ tags: - shares --- -## About Windows (SMB) Shares +## 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. @@ -46,6 +46,11 @@ Discoverability through broadcast protocols is a convenience feature and is not ## How do I add an SMB Share? +{{< hint type="info" title="Active Directory and SMB Service" >}} +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. +{{< /hint >}} + 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](#creating-the-smb-share-user-account). @@ -55,8 +60,9 @@ Creating an SMB share to your system involves several steps to add the share and 2. [Create the SMB share and dataset](#adding-an-smb-share-and-dataset). You can create a basic SMB share, or for more specific share types or feature requirements, use the [Advanced Options](#configuring-share-advanced-options-settings) 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. + 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 presets use the **Add SMB** screen 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. 3. [Modify the share permissions](#tuning-the-dataset-acl). After adding or modifying the user account for the share, edit the dataset permissions. @@ -68,7 +74,8 @@ After adding the share, [start the service](#starting-the-smb-service) and [moun {{< include file="/static/includes/LocalSMBUser.md" >}} 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. +Click **Add** to create a new or as many new user accounts as needed. +If joined to Active Directory, Active Directory can create the TrueNAS accounts. 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]({{< relref "ManageLocalUsersScale.md" >}}). @@ -89,7 +96,6 @@ Migrate legacy Samba domains to Active Directory before upgrading to 24.10 or la {{< /expand >}} ## Adding an SMB Share and Dataset - You can create an SMB share while [creating a dataset on the **Add Dataset** screen]({{< relref "DatasetsSCALE.md" >}}) 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. @@ -103,6 +109,7 @@ 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. @@ -110,7 +117,7 @@ This default ACL is restrictive and only grants access to the dataset owner and You can modify the ACL later according to your use case. {{< /expand >}} -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. +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. {{< trueimage src="/images/SCALE/Shares/AddShareBasicOptions.png" alt="Add SMB Basic Options" id="Add SMB Basic Options" >}} @@ -125,7 +132,7 @@ To create a basic Windows SMB share and a dataset, go to **Shares** and click ** **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. + 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: * [Files and directories](https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file#naming-conventions) @@ -134,13 +141,20 @@ To create a basic Windows SMB share and a dataset, go to **Shares** and click ** 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. +3. (Optional) Select a preset from the **Purpose** dropdown list to apply. + The preset selected locks 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**. + To create an alternative to Home Shares, select **Private SMB Datasets and Shares**. + See [Setting Up SMB Home Shares]({{< relref "AddSMBHomeShare.md" >}}) for more information on replacing this legacy feature with private SMB shares and datasets. + + {{< expand "SMP Purpose Options" "v" >}} + {{< include file="/static/includes/SMBPurposePresets.md" >}} + {{< /expand >}} 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. + Leave it cleared 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**. @@ -149,23 +163,25 @@ To create a basic Windows SMB share and a dataset, go to **Shares** and click ** Enable the SMB service when prompted. ### Configuring Share Advanced Options Settings +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. -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]({{< relref "SMBSharesScreens.md" >}}). +The following are possible use cases. See [SMB Shares Screens]({{< relref "SMBSharesScreens.md" >}}) for all settings and other possible use cases. {{< expand "Setting Up Guest Access" "v" >}} -If you want to allow guest access to the share, select **Allow Guest Access**. +**Not a recommended configuration and adds security vulnerabilities!** + +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. +* **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](https://support.apple.com/guide/mac-help/connect-mac-shared-computers-servers-mchlp1140/mac) for more details. -If setting up guest access with read only permissions, see the information in [Adding a New Share Group](#adding-a-new-share-group). If the share is nested under parent datasets, see [Using the Traverse Permission](#using-the-traverse-permission). +If setting up guest access with read only permissions, see the information in [Adding a New Share Group](#adding-a-new-share-group). +If the share is nested under parent datasets, see [Using the Traverse Permission](#using-the-traverse-permission). {{< /expand >}} {{< expand "Setting Up Read or Write Access" "v" >}} To prohibit writes to the share, select **Export Read-Only**. @@ -176,23 +192,24 @@ See the [smb.conf](https://www.samba.org/samba/docs/current/man-html/smb.conf.5. {{< expand "Setting Up Host Allow and Host Deny" "v" >}} 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. +Use the **Hosts Allow** field to enter a list of allowed host names or IP addresses. Separate entries by pressing Enter. {{< hint type="Warning" title="Setting Host Allow" >}} 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. {{< /hint >}} You can find a more detailed description with examples [here](https://www.samba.org/samba/docs/current/man-html/smb.conf.5.html#HOSTSALLOW). -Use the **Hosts Deny** field to enter a list of denied hostnames or IP addresses. Separate entries by pressing Enter. +Use the **Hosts Deny** field to enter a list of denied host names 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. +* Leaving both **Hosts Allow** and **Hosts Deny** free of entries allows any host to access the SMB share. +* Adding entries to the **Hosts Allow** list but not the **Hosts Deny** list allows only the hosts on the **Hosts Allow** list to access the share. +* Adding entries to the **Hosts Deny** list but not **Hosts Allow** list allows all hosts not on the **Hosts Deny** list to access the share. +* Adding entries to both a **Hosts Allow** and **Hosts Deny** list allows all hosts on the **Hosts Allow** list to access the share, and also allows hosts not on the **Hosts Allow** or **Hosts Deny** list to access the share. {{< /expand >}} {{< expand "Apple Filing Protocol (AFP) Compatibility" "v" >}} -AFP shares are deprecated and not available in SCALE. +AFP shares are deprecated and not available in TrueNAS. + 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](https://support.apple.com/en-us/HT201250) backups on this share. @@ -205,17 +222,21 @@ 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. {{< /expand >}} +{{< expand "Private SMB Datasets and Shares" "v" >}} +Use to set up an alternative to the legacy Home Shares function. + +Allow adding private datasets and shares for individual users. Useful as an alternate way to creating home shares for individual users. +See [Setting Up SMB Home Shares]({{< relref "AddSMBHomeShare.md" >}}) for more information. +{{< /expand >}} {{< expand "Enabling SMB Audit Logging" "v" >}} 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**. {{< /expand >}} ### 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]({{< relref "ManageSMBShares.md" >}}) 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]({{< relref "ManageSMBShares.md" >}}) for more information on these options. @@ -242,15 +263,13 @@ See [Permissions]({{< relref "PermissionsScale.md" >}}) for more information on {{< include file="/static/includes/UsingTraversePermission.md" >}} ## Starting the SMB Service +To connect to an SMB share, start 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. +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. ### 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. {{< trueimage src="/images/SCALE/Shares/SMBShareOptions.png" alt="SMB Service Options" id="SMB Service Options" >}} @@ -258,50 +277,48 @@ From the **Sharing** screen, click on the **Windows (SMB) Shares** 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. {{< expand "Mounting on a Linux System" "v" >}} Verify that your Linux distribution has the required CIFS packages installed. -Create a mount point: `sudo mkdir /mnt/smb_share`. +Create a mount point with the `sudo mkdir /mnt/smb_share` command. -Mount the volume. `sudo mount -t cifs //computer_name/share_name /mnt/smb_share`. +Mount the volume with the `sudo mount -t cifs //computer_name/share_name /mnt/smb_share` command. -If your share requires user credentials, add the switch `-o username=` with your username after `cifs` and before the share address. +If your share requires user credentials, add the switch `-o username=` with the username after `cifs` and before the share address. {{< /expand >}} {{< expand "Mounting on a Windows System" "V" >}} -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. +To permanently mount the SMB share in Windows, map a drive letter in the computer for the user to the TrueNAS 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 +* *TrueNAS_name* is either the host name 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. +To temporarily connect to a share, open a Windows File Explorer window, type \\TrueNAS_name\share_name and then enter the user credentials 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. {{< /expand >}} {{< expand "Mounting on an Apple System" "v" >}} - -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. +Have the username 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`. +Enter the SMB address as follows: 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. {{< /expand >}} @@ -309,22 +326,21 @@ Input the username and password for the user assigned to that pool or guest if t {{< expand "Mounting on a FreeBSD System" "v" >}} Mounting on a FreeBSD system involves creating the mount point, then mounting the volume. -Create a mount point: `sudo mkdir /mnt/smb_share`. +Create a mount point using the `sudo mkdir /mnt/smb_share` command. -Mount the volume. `sudo mount_smbfs -I computer_name\share_name /mnt/smb_share`. +Mount the volume using the `sudo mount_smbfs -I computer_name\share_name /mnt/smb_share` command. {{< /expand >}} ## 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. +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 live 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 SCALE server (for example, *system1*), as described in [Adding an SMB Share](#adding-an-smb-share) above. +Create the SMB share on another TrueNAS server (for example, *system1*), as described in [Adding an SMB Share](#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*). +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 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. +On *system2*, enter the host name 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. @@ -332,7 +348,7 @@ Repeat the *system2* instructions above to add an external redirect (share) on * {{< trueimage src="/images/SCALE/Shares/SetUpExternalSMBShare.png" alt="Set Up Another External SMB Share" id="Set Up Another External SMB Share" >}} -Repeat for each SCALE system with SMB shares you want added as an external redirect. +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.
diff --git a/content/SCALE/SCALEUIReference/Shares/SMBSharesScreens.md b/content/SCALE/SCALEUIReference/Shares/SMBSharesScreens.md index 62228b3c35..c7f0646381 100644 --- a/content/SCALE/SCALEUIReference/Shares/SMBSharesScreens.md +++ b/content/SCALE/SCALEUIReference/Shares/SMBSharesScreens.md @@ -103,17 +103,7 @@ The **Basic Options** settings in this section also display in the **Advanced Op #### Purpose Setting Options This table details the options found on the **Purpose** dropdown list. -{{< truetable >}} -| Setting | Description | -|---------|-------------| -| **No presets** | Select to retain control over all **Advanced Options** settings. This option gives users the flexibility to manually configure SMB parameters. | -| **Default share parameters** | The default option when you open the **Add SMB** screen and to use for any basic SMB share. These settings provide a baseline configuration that ensures compatibility and functionality, and allow users to set up shares with commonly implemented options and behaviors. | -| **Basic time machine share** | Select to set up a basic time machine share. This provides a centralized location for users to store and manage system backups. | -| **Multi-User time machine** | Select to set up a multi-user time machine share. This option allows multiple users to use TrueNAS as a centralized backup solution while simultaneously ensuring that each backup users make are kept separate and secure from one another. | -| **Multi-Protocol (NFSv3/SMB) shares**| Select for multi-protocol (NFSv3/SMB) shares. Choosing this option allows NFS and SMB users to access TrueNAS at the same time. | -| **Private SMB Datasets and Shares** | Select to use private SMB datasets and shares. This setting enables users to personlize storage management and access control while maintaining data confidentiality. | -| **SMB WORM. Files become read-only via SMB after 5 minutes** | The **SMB WORM** preset only impacts writes over the SMB protocol. Before deploying this option in a production environment, determine whether the feature meets your requirements. Employing this option, ensures data written to the share cannot be modified or deleted, thus increasing overall data integrity and security. | -{{< /truetable >}} +{{< include file="/static/includes/SMBPurposePresets.md" >}} ### Advanced Options Settings Click **Advanced Options** to display settings made available or locked based on the option selected in **Purpose**. @@ -166,6 +156,7 @@ The **Other Options** settings include improving Apple software compatibility, Z | **Enable SMB2/3 Durable Handles** | Select to allow using open file handles that can withstand short disconnections. Support for POSIX byte-range locks in Samba is also disabled. We do not recommend this option when configuring multi-protocol or local access to files. | | **Enable FSRVP** | Select to enable support for the File Server Remote VSS Protocol ([FSVRP](https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-fsrvp/dae107ec-8198-4778-a950-faa7edad125b)). This protocol allows remote procedure call (RPC) clients to manage snapshots for a specific SMB share. The share path must be a dataset mount point. Snapshots have the prefix `fss-` followed by a snapshot creation timestamp. A snapshot must have this prefix for an RPC user to delete it. | | **Path Suffix** | Appends a suffix to the share connection path. Use to provide individualized shares on a per-user, per-computer, or per-IP address basis. Suffixes can contain a macro. See the [smb.conf](https://www.samba.org/samba/docs/current/man-html/smb.conf.5.html) manual page for a list of supported macros. The connect path must be preset before a client connects. | +| **Additional Parameters String** | Shows a string of parameters associated with the share preset selected, or if no preset, enter additional smb4.conf parameters not covered by the TrueNAS API. | {{< /truetable >}} #### Advanced Options Presets @@ -220,7 +211,7 @@ These settings configure new ACL entries for the selected SMB share and apply th ## Edit Filesystem ACL Screen The **Edit Filesystem ACL** option opens the **Edit ACL** screen for the dataset the share uses. -See [**Edit ACL Screen]({{< relref "EditACLScreens.md" >}}) more information on the settings found on this screen. +See [**Edit ACL Screen**]({{< relref "EditACLScreens.md" >}}) more information on the settings found on this screen. {{< trueimage src="/images/SCALE/Shares/SMBACLEditor.png" alt="SMB ACL Editor" id="SMB ACL Editor" >}} @@ -246,4 +237,4 @@ Click **Sharing** or **SBM** on the top breadcrumb to open the selected screen. The breadcrumb displays when you access the SMB Status screen from the **System > Services SMB** row. -{{< include file="/static/includes/addcolumnorganizer.md" >}} +{{< include file="/static/includes/addcolumnorganizer.md" >}} \ No newline at end of file diff --git a/static/images/SCALE/Shares/AddPrivateSMBShare.png b/static/images/SCALE/Shares/AddPrivateSMBShare.png new file mode 100644 index 0000000000..d8bbe6a057 Binary files /dev/null and b/static/images/SCALE/Shares/AddPrivateSMBShare.png differ diff --git a/static/images/SCALE/Shares/AddPrivateSMBShareAdvancedOptions.png b/static/images/SCALE/Shares/AddPrivateSMBShareAdvancedOptions.png new file mode 100644 index 0000000000..d16bc15b8a Binary files /dev/null and b/static/images/SCALE/Shares/AddPrivateSMBShareAdvancedOptions.png differ diff --git a/static/images/SCALE/Shares/AddSMBAdvancedOtherSettings.png b/static/images/SCALE/Shares/AddSMBAdvancedOtherSettings.png index d96af521a5..1b91954f8e 100644 Binary files a/static/images/SCALE/Shares/AddSMBAdvancedOtherSettings.png and b/static/images/SCALE/Shares/AddSMBAdvancedOtherSettings.png differ diff --git a/static/images/SCALE/Shares/SetACLPresetForPrivateDataset.png b/static/images/SCALE/Shares/SetACLPresetForPrivateDataset.png new file mode 100644 index 0000000000..5981e5b42f Binary files /dev/null and b/static/images/SCALE/Shares/SetACLPresetForPrivateDataset.png differ diff --git a/static/images/SCALE/Shares/SetUserHomeDirectoryToPrivate.png b/static/images/SCALE/Shares/SetUserHomeDirectoryToPrivate.png new file mode 100644 index 0000000000..0e9af65da6 Binary files /dev/null and b/static/images/SCALE/Shares/SetUserHomeDirectoryToPrivate.png differ diff --git a/static/includes/ChangeBuiltin-UserACL.md b/static/includes/ChangeBuiltin-UserACL.md index 0db83b33ee..0a180c66ed 100644 --- a/static/includes/ChangeBuiltin-UserACL.md +++ b/static/includes/ChangeBuiltin-UserACL.md @@ -16,5 +16,4 @@ To change permissions for the **builtin_users** group, go to **Datasets**, selec 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. -7. \ No newline at end of file +6. Click **Save Access Control List** to add the ACE item or save changes. \ No newline at end of file diff --git a/static/includes/SMBPurposePresets.md b/static/includes/SMBPurposePresets.md new file mode 100644 index 0000000000..65bf496e4c --- /dev/null +++ b/static/includes/SMBPurposePresets.md @@ -0,0 +1,13 @@ + + +{{< truetable >}} +| Setting | Description | +|---------|-------------| +| **No presets** | Select to retain control over all **Advanced Options** settings. This option gives users the flexibility to manually configure SMB parameters. | +| **Default share parameters** | The default option when you open the **Add SMB** screen and to use for any basic SMB share. These settings provide a baseline configuration that ensures compatibility and functionality, and allow users to set up shares with commonly implemented options and behaviors. | +| **Basic time machine share** | Select to set up a basic time machine share. This provides a centralized location for users to store and manage system backups. | +| **Multi-User time machine** | Select to set up a multi-user time machine share. This option allows multiple users to use TrueNAS as a centralized backup solution while simultaneously ensuring that each backup users make are kept separate and secure from one another. | +| **Multi-Protocol (NFSv3/SMB) shares**| Select for multi-protocol (NFSv3/SMB) shares. Choosing this option allows NFS and SMB users to access TrueNAS at the same time. | +| **Private SMB Datasets and Shares** | Select to create a share that maps to a path determined by the username of the authenticated user. TrueNAS creates a unique, private dataset matching the user name. | +| **SMB WORM. Files become read-only via SMB after 5 minutes** | The **SMB WORM** preset only impacts writes over the SMB protocol. Before deploying this option in a production environment, determine whether the feature meets your requirements. Employing this option, ensures data written to the share cannot be modified or deleted, thus increasing overall data integrity and security. | +{{< /truetable >}}