Merge pull request #2707 from truenas/PD-1136-update-24-04-release-no…

…tes-guidance-on-user-home-directory-change

Pd 1136 update 24 04 release notes guidance on user home directory change

content/GettingStarted/SCALEReleaseNotes.md

@@ -42,7 +42,7 @@ Users with this particular configuration are encouraged to either wait for the *
 * TrueNAS SCALE is an appliance built from specific Linux packages.
   Attempting to update SCALE with `apt` or methods other than the SCALE web interface can result in a nonfunctional system.
 
-* Users with unofficial apps installed should review app storage drivers to determine if any utilize the OpenEBS-ZFS container storage interface (CSI) before upgrading. This CSI is not supported in TrueNAS SCALE 24.04 ([Removal Notice](https://www.truenas.com/community/threads/openebs-zfs-driver-removal-notice.115026/)). Unofficial apps which use OpenEBS-ZFS CSI drivers should maintain functionality for existing deployments, but users are not able to make backups or restore any existing backup for those apps. New users are not able to install and deploy these apps.
+* Users with unofficial apps installed should review app storage drivers to determine if any utilize the OpenEBS-ZFS container storage interface (CSI) before upgrading. This CSI is not supported in TrueNAS SCALE 24.04 ([Removal Notice](https://www.truenas.com/community/threads/openebs-zfs-driver-removal-notice.115026/)). Unofficial apps which use OpenEBS-ZFS CSI drivers should maintain functionality for existing deployments, but users are not able to make backups or restore any existing backups for those apps. New users are not able to install and deploy these apps.
 
 * All auxiliary parameters can change between TrueNAS major versions due to security and development changes.
   We recommend removing all auxiliary parameters from TrueNAS configurations before upgrading.
@@ -54,14 +54,7 @@ Users with this particular configuration are encouraged to either wait for the *
 * Several built-in services from SCALE 22.12 (Bluefin) in **System Settings > Services** are replaced by community applications ([details](https://www.truenas.com/docs/scale/22.12/gettingstarted/scaledeprecatedfeatures/)).
   SCALE 22.12 (Bluefin) systems must disable these built-in services and begin using the equivalent application **before** upgrading to SCALE 23.10 (Cobia), prior to upgrading to SCALE 24.04, or users can force an upgrade without disabling them. This is not recommended for the S3 service as you must migrate the MinIO service and data or lose it.
 
-* 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.
-
-  Services impacted:
-
-  * SMB if a home share is enabled
-  * SSH
-  * Shell access (edited)
+* {{< include file="/static/includes/24.04HomeDirectory.md" >}}
 
   See [Managing Users]({{< relref "managelocalusersscale.md#configuring-a-user" >}}) for more information.
 
@@ -264,7 +257,7 @@ Notable changes:
 
 * systemd-nspawn containers ([Sandboxes]({{< relref "/SCALETutorials/Apps/Sandboxes.md" >}})) are added as an unsupported community feature so that an advanced containerization user can deploy custom software in persistent containers.
 
-* Support is added for data ingest via filesystem (SMB/NFS) clients, allowing users migrating to TrueNAS SCALE to more easily import data from a third party NAS solution ([NAS-123717](https://ixsystems.atlassian.net/browse/NAS-123717)).
+* Support is added for data ingest via filesystem (SMB/NFS) clients, allowing users migrating to TrueNAS SCALE to more easily import data from a third-party NAS solution ([NAS-123717](https://ixsystems.atlassian.net/browse/NAS-123717)).
   Supported SMB migration via the TrueNAS Syncthing Enterprise app is arriving in a future 24.04 release.
 
 * Linux kernel is updated to 6.6 ([NAS-123465](https://ixsystems.atlassian.net/browse/NAS-123465)).
@@ -282,7 +275,7 @@ Notable changes:
   New and existing users who only use official apps are unaffected by this change, as these apps do not use OpenEBS-ZFS CSI drivers.
   Unofficial apps are unaffected if they are configured as outlined below.
 
-  Unofficial apps which use OpenEBS-ZFS CSI drivers should maintain functionality for existing deployments, but users are not able to make backups or restore any existing backup for those apps. New users are not able to install and deploy these apps.
+  Unofficial apps that use OpenEBS-ZFS CSI drivers should maintain functionality for existing deployments, but users are not able to make backups or restore any existing backups for those apps. New users are not able to install and deploy these apps.
 
   Maintainers of unofficial catalog apps using OpenEBS-ZFS CSI drivers should either begin to ship a CSI driver with the app or use the one provided in SCALE.
 
@@ -298,7 +291,7 @@ Notable changes:
   * Read-only TrueNAS administrators are not able to query audit entries. This [fix](https://github.com/truenas/middleware/pull/13035) is anticipated in the 24.04-RC.1 release.
 
 * Displayed units for network traffic are inconsistent between the web interface Dashboard and Reporting screens.
-  Additional changes for consistency and IEC conformant terminology is targeted for 24.04-RC.1 [NAS-125453](https://ixsystems.atlassian.net/browse/NAS-125453).
+  Additional changes for consistency and IEC conformant terminology are targeted for 24.04-RC.1 [NAS-125453](https://ixsystems.atlassian.net/browse/NAS-125453).
 
 <a href="https://ixsystems.atlassian.net/issues/?filter=10487" target="_blank">Click here to see the latest information</a> about public issues discovered in 24.04-BETA.1 that are being resolved in a future TrueNAS SCALE release.
 {{< /expand >}}

content/SCALETutorials/Credentials/ManageLocalUsersSCALE.md

@@ -63,7 +63,7 @@ We recommend using an ID  of 3000 or greater for non-built-in users.
 
 {{< trueimage src="/images/SCALE/Credentials/AddUser-UserIDAndGroupSettings.png" alt="Add User ID and Groups Settings" id="Add User ID and Groups Settings" >}}
 
-Leave the **Create New Primary Group** toggle enabled to allow TrueNAS to create a new primary group with the same name as the user. 
+Leave the **Create New Primary Group** toggle enabled to allow TrueNAS to create a new primary group with the same name as the user.
 To add the user to a different existing primary group, disable the **Create New Primary Group** toggle and search for a group in the **Primary Group** field.
 To add the user to more groups use the **Auxiliary Groups** dropdown list.
 
@@ -75,20 +75,14 @@ When creating a user, the home directory path is set to <file>/var/empty</file>,
 To add a home directory, enter or browse to a path in **Home Directory**, then select **Create Home Directory**.
 
 {{< hint type="important" title="Home Directory Known Impacts" >}}
-SCALE 24.04 changes the user home directory location from **/nonexistent**, a directory that should never exist, to **/var/empty**.
-This new directory is an immutable directory shared by service accounts and accounts that should not have a full home directory.
-Services impacted:
-
-* SMB if a home share is enabled
-* SSH
-* Shell access (edited)
+{{< 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 SCALE does 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.
+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**.
@@ -97,7 +91,7 @@ This results in a permissions error if `pam_open_session()` is called by an appl
 
 {{< trueimage src="/images/SCALE/Credentials/AddUserHomeDirAuthSCALE.png" alt="Add User Home Directory and Authentication Settings" id="Add User Home Directory and Authentication Settings" >}}
 
-Select **Read**, **Write**, and **Execute** for each role (**User**, **Group**, and **Other**) to set access control for the user home directory. 
+Select **Read**, **Write**, and **Execute** for each role (**User**, **Group**, and **Other**) to set access control for the user home directory.
 Built-in users are read-only and can not modify these settings.
 
 Assign a public SSH key to a user for key-based authentication by entering or pasting the public key into the **Authorized Keys** field.
@@ -115,14 +109,14 @@ Select the [shell]({{< relref "LocalUsersScreensSCALE.md" >}}) option for the ad
 Options are **nologin**, **bash**, **rbash**, **dash**, **sh**, **tmux**, and **zsh**.
 For members of the **builtin_administrators** and **builtin_users** groups, select **TrueNAS Console** to open in the Console Setup menu for SCALE that provides access to the Linux and SCALE CLI prompts, or select **TrueNAS CLI** to open the **Shell** screen in the TrueNAS CLI.
 
-To disable all password-based functionality for the account, select **Lock User**. Clear to unlock the user. 
+To disable all password-based functionality for the account, select **Lock User**. Clear to unlock the user.
 
 Set the sudo permissions you want to assign this user.
 Exercise caution when allowing sudo commands, especially without password prompts.
 We recommend limiting this privilege to trusted users and specific commands to minimize security risks.
 
-**Allowed sudo commands**, **Allow all sudo commands**, **Allowed sudo commands with no password** and **Allow all sudo commands with no password** grant the account limited root-like permissions using the [sudo](https://www.sudo.ws/) command. 
-If selecting **Allowed sudo commands** or **Allowed sudo commands with no password**, enter the specific sudo commands allowed for this user. 
+**Allowed sudo commands**, **Allow all sudo commands**, **Allowed sudo commands with no password** and **Allow all sudo commands with no password** grant the account limited root-like permissions using the [sudo](https://www.sudo.ws/) command.
+If selecting **Allowed sudo commands** or **Allowed sudo commands with no password**, enter the specific sudo commands allowed for this user.
 Enter each command as an absolute path to the ELF (Executable and Linkable Format) executable file, for example, */usr/bin/nano*.
 <file>/usr/bin/</file> is the default location for commands.
 Select **Allow all sudo commands** or **Allow all sudo commands with no password**.
@@ -133,6 +127,6 @@ Click **Save**.
 
 ## Editing User Accounts
 
-To edit an existing user account, go to **Credentials > Local Users**. 
-Click anywhere on the user row to expand the user entry, then click **Edit** to open the **Edit User** configuration screen. 
+To edit an existing user account, go to **Credentials > Local Users**.
+Click anywhere on the user row to expand the user entry, then click **Edit** to open the **Edit User** configuration screen.
 See [Local User Screens]({{< relref "LocalUsersScreensScale.md" >}}) for details on all settings.

content/SCALETutorials/Shares/SMB/AddSMBHomeShare.md

@@ -7,6 +7,13 @@ tags:
 - smb
 ---
 
+{{< hint type=important title="Legacy Feature" >}}
+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.
+{{< /hint >}}
+
 ## Setting Up SMB Home Shares
 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.
 
@@ -26,7 +33,23 @@ By default, the user **Home Directory** title comes from the user account name a
 
 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 their own directory.
+Adjust the user home directory to the appropriate dataset and give it a name to create its own directory.
+
+{{< 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 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**.
+{{< /expand >}}
+{{< /hint >}}
+
 
 ### Adding Share Users with Directory Services
 
@@ -62,17 +85,17 @@ 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 is available on your network.
+Enable the **SMB** service when prompted to make the share available on your network.
 
 After saving the dataset, set the 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.
+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.
 
 Click on the new dataset. Scroll down to the **Permissions** widget and click **Edit**.
 
-Click the **Owner** dropdown and select the owner, the repeat for **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**.
 
 ![GroupDomainAdminsSCALE](/images/SCALE/Datasets/GroupDomainAdmins.png "Set the owning group to Domain Admins")

static/includes/24.04HomeDirectory.md

@@ -0,0 +1,14 @@
+

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

words-to-ignore.txt

@@ -1883,3 +1883,4 @@ VMCPUandMemorySettings
 VMGPUSettings
 CloneVMDialog
 enlightenments
+HomeDirectory