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.

Managing Users

In TrueNAS, user accounts allow flexibility for accessing shared data. Typically, administrators create users and assign them to groups. Doing so makes tuning permissions for large numbers of users more efficient.

When the network uses a directory service, import the existing account information using the instructions in Directory Services.

Using Active Directory requires setting Windows user passwords in Windows.

To see user accounts, go to Credentials > Users.

Local User non-Built-in Accounts
Figure 1: Local User non-Built-in Accounts

TrueNAS hides all built-in users (except root) by default. Click the toggle Show Built-In Users to see all built-in users.

Creating an Administrator User Account

Root account logins are deprecated in SCALE Bluefin 22.12.0 or newer for security hardening and to comply with Federal Information Processing Standards (FIPS). All TrueNAS users should create an administrator account with all required permissions and begin using it to access TrueNAS. When the root user password is disabled, only an administrative user account can log in to the TrueNAS web interface.

TrueNAS SCALE plans to permanently disable root account access in a future release.

The default SCALE administrator account name changes from admin to truenas_admin in TrueNAS SCALE 24.10 (Electric Eel) fresh installations. Earlier releases of SCALE with the admin account retain this account when upgrading to 24.10 through the UI.

To improve security and minimize username discoverability, create one or more administrator accounts with unique usernames and passwords and disable password access for default administrator accounts (root, admin, or truenas_admin). Configure appropriate administrative privileges for each admin account. Follow the principle of least privilege (PoLP) and assign the lowest permissions required to perform the administrative tasks expected for that user. If a task requires SSH login or sudo command permission, temporarily enable these settings then disable when the task is complete. See Security Recommendations and Allowing Sudo Commands for more information.

After adding the admin user account and group privileges, login to confirm UI access then disable the root and/or default administrator user password(s). Go to Credentials > Users, click on the user, and select Edit. Click the Disable Password toggle to disable the password, then click Save.

Go to Credentials > Users and click Add.

Enter memorable name that is difficult to guess for the administrator account. You can create multiple admin users with different names and assign each different administration roles and privileges.

Enter and confirm the admin user password.

Select Create New Primary Group to create a group with the same name as the admin user. To assign the new admin to an existing group with appropriate administrative privileges, either assign the group as an auxiliary group or deselect Create New Primary Group and select the group as the primary group.

Add the home directory for the new admin user. Enter or browse to select the location where SCALE creates the home directory. For example, /mnt/tank. If you created a dataset to use for home directories, select that dataset. Select the Read, Write, and Execute permissions for User, Group, and Other this directory should have, then select Create Home Directory.

Select the shell for this admin user from the Shell dropdown list. We recommend setting shell to TrueNAS Console as this provides access to the Console Setup menu and the Linux shell from the SCALE Shell screen.

If required, set the sudo permissions to assign. For improved security, temporarily enable limited sudo permissions only when required to complete an administrative task and disable sudo after completing the task. See Allowing Sudo Commands for more information.

For administrator accounts generated during the initial installation process, TrueNAS SCALE sets authorization to Allow all sudo commands. For improved security, deny sudo permissions unless required for specific, recurring administrative tasks or allow sudo permissions only when needed to perform a discrete task and then deny again when finished. Do not allow sudo permissions for read-only administrators.

Alternatively, accept default user sudo permissions and apply permissions to the group.

Click Save. The system adds the user to the builtin-users group after clicking Save.

Assigning Administrative Group Privileges

SCALE 24.04 or newer supports administrator privileges for role-based administrator accounts. Users can create new administrator accounts with limited privileges based on their needs. Predefined administrator roles are read only, share admin, and the default full access local administrator account. See Using Administrator Logins for more information.

Go to Credentials > Groups and select the row for primary group of the admin user to expand it. Click Edit.

Alternatively, click Add to create a new group for administrative users, such as Share_Administrators.

Use the Privileges dropdown to select assign permissions as Local Administrator to allow full administrative access or select Read-Only Administrator or Sharing Administrator to limit permissions.

If required, set the sudo permissions to assign. For improved security, temporarily enable limited sudo permissions only when required to complete an administrative task and disable sudo after completing the task. See Allowing Sudo Commands for more information.

Click Save.

After creating a new group, click Members to open the Update Members screen and assign one or more administrative user accounts to the group. Click Save.

Log out of the TrueNAS system and then log back in using the new user credentials to verify that the admin credentials work properly with your network configuration.

Creating User Accounts

When creating a user, you must:

  • Enter a Full Name or description for the user, such as a first and last name.
  • Enter a Username or accept the generated user name.
  • Enter and enable a Password.
  • Specify or accept the default user ID (UID)
  • (Optional) Select the Shell the user has access to when they go to System > Shell. Not all users can select a shell.

All other settings are optional. Click Save after configuring the user settings to add the user.

Configuring a User

To create a new user, click Add.

Add User Identification Settings
Figure 6: Add User Identification Settings

Enter a personal name or description in Full Name, for example, John Doe or Share Anonymous User, then allow TrueNAS to suggest a simplified name derived from the Full Name or enter a name in Username.

Enter and confirm a password for the user. Make sure the login password is enabled. Click the Disable Password toggle to enable/disable the login password.
Setting the Disable Password toggle to active (blue toggle) disables these functions:

  • The Password field becomes unavailable and TrueNAS removes any existing password from the account.
  • The Lock User option disappears.
  • The account is restricted from password-based logins for services like SMB shares and SSH sessions.

Enter a user account email address in the Email field if you want this user to receive notifications

Accept the default user ID or enter a new UID. TrueNAS suggests a user ID starting at 3000, but you can change it if you wish. We recommend using an ID of 3000 or greater for non-built-in users.

Add User ID and Groups Settings
Figure 7: 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. 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.

Configure a home directory and permissions for the user. Some functions, such as replication tasks, require setting a home directory for the user configuring the task.

Add User Home Directory
Figure 8: Add User Home Directory

When creating a user, the default home directory path is set to /var/empty. This directory is an immutable directory shared by service accounts and accounts that should not have a full home directory. If set to this path TrueNAS does not create a home directory for the user. You must change this to the path for the dataset created for home directories.

To add a home directory, enter or browse to a path in Home Directory, then select Create 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.

Why did this change in TrueNAS 24.04 (Dragonfish) and later?

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.

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.

Assign a public SSH key to a user for key-based authentication by entering or pasting the public key into the Authorized Keys field. You can click Choose File under Upload SSH Key and browse to the location of an SSH key file.

Add Authentication Settings
Figure 9: Add Authentication Settings
Do not paste the private key.

Always keep a backup of an SSH public key if you are using one.

As of SCALE 24.04, the Shell setting defaults to nologin for read only and sharing administrators, which means they cannot access the Shell screen.

Select the shell option for the admin user from the Shell dropdown list. Options are nologin, TrueNAS CLI, TrueNAS Console, sh, bash, rbash, dash, tmux, and zsh.

To disable all password-based functionality for the account, select Lock User. Clear to unlock the user.

If required, set the sudo permissions to assign. For improved security, temporarily enable limited sudo permissions only when required to complete an administrative task and disable sudo after completing the task. See Allowing Sudo Commands for more information.

Leave SMB User selected to allow using the account credentials to access data shared with SMB.

Click Save.

Adding Home Directories

To add a home directory for a user account, first create a dataset to use for user home directories, for example a dataset named homedirs.

Next, go to Credentials > Users and either click Add to add a new user and their home directory, or select an existing user, click Edit, and then add a home directory for the user. While on the user configuration screen:

Enter the path to the new dataset for home directories in Home Directory. For example, change /var/empty/ to the path to the new dataset /tank/homedirs.

Next select Create Home Directory, and select the level of permissions you want to apply. We recommend leaving the default selections, Read/Write/Execute selected for the user home directory.

Click Save. TrueNAS creates the new home directory for the user.

Editing User Accounts

To edit an existing user account, go to Credentials > 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 for details on all settings.