Managing Users

12 minute read.

Last Modified 2025-10-13 15:28 EDT

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.

TrueNAS hides all built-in users (except root) by default. Click the down arrow in the Filter by Type dropdown field to see all user options, including Built-In, Local (default option), and Directory Services. You can select any or all options to show all users configured in TrueNAS. To filter the user table, click any column header to sort in ascending or descending order. You can also use the advanced search option to search by specific criteria.

Creating an Administrator User Account

Root account logins are deprecated in TrueNAS 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 plans to permanently disable root account access in a future release.

The default TrueNAS administrator account name changes from admin to truenas_admin in TrueNAS 24.10 (Electric Eel) fresh installations. Earlier releases of TrueNAS 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.

Assigning Administrative Group Privileges

TrueNAS 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 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

SMB User is selected by default to allow using the account credentials to access data shared with SMB.

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.
Enter a Password.
Specify or accept the default user ID (UID)

Other options are required based on the level of access and role assigned to the user. The Shell option only shows for users with Shell Access or SSH Access selected.

To manually add a new user, click Credentials > Users, and then click Add to open the Add User screen.

Enter a username for the user. Names are case sensitive!
Set the level of access given to this user.
SMB Access is selected by default. Select TrueNAS Access, then select the administration role from the dropdown list that shows after selecting the TrueNAS Access option.
- To create an administrator with full access, select Full Admin.
- To create an administrator with access to manage shares, select Sharing Admin.
- To create an administrator with read-only access, select Readonly Admin.
- To allow the user to access the Shell in the UI, select Shell Access.
To allow the user to establish an SSH session with the system, select SSH Access. Selecting this option also selects the Shell Access option by default. To limit the user to only Shell access, do not select the SSH Access option.
Enter a password for the user.
Set up SSH authentication.
These options only show when you select the SSH Access option.
Select the optional Allow SSH Login with Password if you want to allow this user to log in to an SSH session and not be prompted to enter a password. This is not recommended as it presents a security vulnerability!
Manually enter or copy/paste the public key in the Public SSH Key field to assign a public SSH key to the user for key-based authentication.
Do not enter the private key!
After adding authentication settings, complete the SSH access by setting up sudo commands in the next step.
Always keep a backup of an SSH public key if you are using one.
Enter additional details for the user. Setting options change based on the access option selected. Shell Access and SSH Access show the Shell and Sudo Command settings.
Figure 3: Additional Details Settings
Enter the full name for the user. The full user name is not case sensitive.
(Optional) Enter the email for the user. Starting in TrueNAS 25.10, system notifications are sent to recipients configured in system email settings rather than user account emails.
Set up a group.
Accept the default group setting, which is Create New Primary Group. This creates a group with the same name as the admin user. The role setting adds the user to the appropriate auxiliary group for that role.
Figure 4: User Group Settings
To select a different group, clear the checkmark, and select a new group on the Primary Group dropdown list. Next, select the group in Auxiliary Groups from the dropdown list.
Accept the default UID Setting
Accept the default UID setting 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.
(Optional) Add a home directory for the user.
Some functions, such as replication tasks, require setting a home directory for the user configuring the task.
SSH User Validation
Users must have a home directory and shell access to log in with SSH.
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.
Figure 5: User Home Directory Settings
Select Create Home Directory to create a new home directory. Leave unselected to select an existing home directory. The file browser field is renamed based on whether you select this option.
Click the arrow to expand the dataset tree until you reach the home directory parent dataset. After clicking on a dataset, the Create Dataset option activates. Use the Create Dataset option to add a new dataset for the home directory if one does not already exist.
Leave Default Permissions selected to accept the default permissions, or clear the checkmark to select Read, Write, and Execute for each role (User, Group, and Other) and customize these permissions for the user, group, or other.
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 24.04 (or newer) does not include the customized version of pam_mkhomedir used in TrueNAS 13.0 that 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 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.
Select the shell option from the dropdown list. Default is zsh when you select Shell Access or SSH Access
Set up the sudo command options.
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.
To improve 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.
Select Allow all sudo commands if you want to allow the user to enter sudo commands in the shell or an SSH session, but still have TrueNAS prompt the user for their password. To limit the sudo commands allowed to a few rather than all commands, enter each in the Allowed sudo commands field. Enter each command as an absolute path to the ELF (Executable and Linkable Format) executable file, for example, /usr/bin/nano. /usr/bin/ is the default location for commands. Press enter after each command to separate the entries.
Figure 6: Add User Sudo Command Options
Select Allow all sudo commands with no password to allow the user to enter sudo commands in the shell or an SSH session, and not have TrueNAS prompt the user to enter their password. To limit the commands allowed to a few rather than all sudo commands, enter each in the Allowed sudo commands with no password field. Enter each command as an absolute path to the ELF (Executable and Linkable Format) executable file, for example, /usr/bin/nano. /usr/bin/ is the default location for commands. Press enter after each command to separate the entries.
Alternatively, accept default user sudo permissions and apply permissions to a new administrator group if you choose to use a group to assign permissions.
Click Save to add the user.

Disabling a Password

To disable a password, select the user, click Edit, and then select Disable Password. Setting Disable Password hides the Password widget, and TrueNAS removes any existing password from the account. The account is restricted from password-based logins for services like SMB shares and SSH sessions.

To disable all password-based functionality for the account, select Lock User option on the Access widget. This toggles to Unlock User when locked.

Adding Home Directories

You can add a home directory to a new or an existing user account. Before adding a user, you can create a dataset for home directories if needed. You can also create the dataset during the user creation process.

To add a home directory to an existing user, go to Credentials > Users, click on the user row, and then click Edit to open the Edit User screen. Scroll down to the Home Directory option, click in the field to show the settings.

Select Create Home Directory, then enter or browse to select the path to the dataset for home directories in Home Directory. For example, change /var/empty/ to the path to a new dataset. For example, /tank/homedirs.

Accept the default permissions or clear the checkmark to 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 a 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, then click Edit to open the Edit User configuration screen. See Users Screen for details on all settings.

Setting Up and Using API Keys

To view API keys that are linked to different user accounts, go to the Settings icon on the top toolbar and select My API Keys, or go to Credentials > Users, select the user row, and then click the View API Keys link on the Access widget to open the User API Keys screen. If a key does not exist for the user, click on the Add API Key link to open the Add API Key screen.

The Users API Keys screen shows a table of all API keys linked to user accounts on your TrueNAS.

You can edit or delete your API keys in the User API Keys screen. Click Edit to open the Edit API Key screen. Click Delete to delete an API key.

Adding An API Key

To add an API key for a user, select the user row on the Users table, and then click Add API Key to open the Add API Key screen. Enter a name for the key, select the user in the Username dropdown list field if not already populated with the correct username, and click Save.

To set the API key to expire, clear the checkmark in Non-expiring, then select the date using the calendar option in the field to set when this key expires.