The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Welcome to the TrueNAS SCALE Command Line Interface (CLI) guide!
The TrueNAS CLI in TrueNAS SCALE functions like a text-based version of the web UI with many functional areas grouped into parent and child namespaces that mirror the counterparts in the SCALE UI.
The underlying structure of the CLI namespaces and commands closely follows that of the SCALE API.
For more information on API commands, arguments, options, and definitions go to API Keys and click on API Docs in the SCALE UI.
Launching the TrueNAS CLI
You can access the TrueNAS CLI through either the Console Setup Menu or from the Shell screen in the SCALE web UI.
To access the TrueNAS CLI when the Linux shell is active, enter cli.
Entering the TrueNAS CLI in the Linux Shell
To access the TrueNAS CLI from the SCALE web UI, go to System Settings > Shell, then enter cli at the system prompt and press Enter.
Exiting the TrueNAS CLI from the Linux Shell
To exit the TrueNAS CLI, enter quit or exit.
Getting Help
The SCALE CLI includes help text for some namespaces and commands through the both the man, and ls commands.
To see the basic commands from any namespace, enter help.
Use the man command to show the help text for a namespace or command with options.
Type man namespacename or man commandname to display the help text for that namespace or command.
Use the ls command while in a child namespace to view a list of commands and the help text descriptions.
You can use the ls command for some commands that show an autofill list of options to display a list of those options with help text descriptions.
Note, not all namespaces, commands, or commands with options include help text.
Using ls with some commands with autofill options does not always display a list view or help text for the options.
Accessing Basic Commands
The TrueNAS CLI includes basic commands available from the CLI prompt or while in any namespace in the CLI.
To access these basic options, enter ? or help, then press Enter. The list of basic commands displays.
Command
Description
..
Moves up one level. For example, from a namespace like auth, enter .. to return to the CLI prompt. From a child namespace like interfaces, use .. to return to the network parent namespace.
exit
Leave the TrueNAS CLI and return to the system prompt.
ls
Lists the namespaces and commands from the active CLI level. For example, at the top level, ls displays the main namespaces in the TrueNAS CLI, or at a main namespace level, displays the additional namespaces or commands for that level.
man
When in a namespace, displays the help text for the command that follows man. For example, while in the network namespace, enter man create to see the help text for the create command.
menu
Displays the Console setup menu in the TrueNAS CLI. Type 6 to exit the menu and return to the CLI prompt.
?
Displays the list of basic commands for the TrueNAS CLI.
/
Returns to the main TrueNAS CLI prompt from any namespace.
.mode
Gets or sets the output mode.
.stacks
Enables/disables printing stack traces for errors.
Navigating Namespaces
The TrueNAS CLI provides eleven top level (parent) namespaces that correspond to SCALE UI functions but not all namespaces mirror the UI counterpart.
For example, the system name space includes alerts and certificates in the CLI but in the UI the counterpart is System Settings, and neither Alerts or Certificates are found under System Settings.
Each parent namespace has child namespaces and commands.
Use the ls command to view the list of namespaces or commands.
Parent and Child Namespaces
Namespace
Description
account
Provides access to user and group child namespaces and commands. In the UI these are found on the **Credentials screen.
app
Provides access to application child namespaces and commands including catalog, chart_release, container, docker, and kubernetes.
auth
Provides access to authentication child namespaces and commands including api_key, privilege, sessions, and two_factor.
directory_service
Provides access to directory services child namespaces and commands including activedirectory, idmap, kerberos, and ldap.
filesystem
Provides access to the acltemplate child namespace.
network
Provides access to network child namespaces and commands including configuration, dns, interface, ipmi, route, and static_route.
service
Provides access to service child namespaces and commands including cluster, ctdb, dyndns, ftp, gluster, ipmi, nfs, openvpn, rsync, rsync_mod, s3, smart, smb, snmp, ssh, tftp, vm, and webdav.
sharing
Provides access to sharing child namespaces and commands including iscsi, nfs, smb, and webdav.
storage
Provides access to storage child namespaces and commands including dataset, disk, enclosure, filesystem, pool, resilver, scrub, snapshot, and vmware.
system
Provides access system child namespaces and commands including acme, advanced, alert, boot, bootenv, certificate, config, core, failover, general, keychain_credential, kmip, mail, ntp_server, reporting, support, system_dataset, truecommand, truenas, tunable, update, and version.
task
Provides access to task child namespaces and commands including cloud_sync, cron_job, replication, rsync, smart_test, and snapshot.
Entering Namespaces and Commands
CLI namespaces and commands are case sensitive.
Enter commands in lower case unless the CLI autofill indicates otherwise.
To enter a namespace or command, begin typing the name.
The CLI displays an autofill list that begins with the letter typed and is available in that part of the CLI.
For example, the autofill list at the main CLI prompt includes only the parent namespaces that begin with the letter typed.
To enter a basic command such as checking current configuration settings in a namespace, enter namespace childnamespace config. The system displays the configured settings for the namespaces preceding the config command.
You can enter a namespace, child namespace, command, command options and option=value pairs from the main CLI prompt using autofill options. For example, parent namespace child namespace command option=value.
You can enter a namespace, then enter the child namespace, command, then select the command option to enter the option=value pair from the namespace prompt.
A command without options does not show an autofill list. Press space to see if the command has more options or wants input, or press Enter to apply the command.
To go up one namespace or command level, enter ...
Enter / to return to the CLI prompt.
Using Keyboard Arrow Keys
Use the up or down arrow keys to select an autofill option, then press space to apply it.
You can use Backspace to erase entered text to start over.
Use the left arrow to move the cursor to the left in a command string where you change the text or use Delete to remove anything to the right of the cursor.
Use the right arrow to move the cursor to the right to the end of the command string to either continue entering command options, or to press Enter to apply the command.
Command Syntax
TrueNAS CLI command structure varies by namespace.
CLI commands can include arguments, options, and or option=value pairs.
Command options that require a single value automatically add the = delimiter after the option on the autofill list and after reaching the end of the command option inputs.
This is an option=value pair.
Some commands allow entering multiple option=value pairs.
These option=value pairs are enclosed in curly brackets, but can also include square or angle brackets enclosed in the curly brackets.
Each namespace article includes command syntax examples for each namespace.
Using the Interactive Arguments Editor
Enter the -- flag following any CLI command to open the interactive arguments editor text-based user interface (TUI).
Enter account user create -- to open the user_create TUI.
Both username: and full_name: are required and enabled by default.
Either group: or group_create: and password: or password_disabled: are also required properties.
You must enable and configure one property for each pair.
All other disabled properties are optional.
To provide values for enabled properties, enter a value following the provided property.
For example, username: testuser.
To enable a property, remove # from the corresponding line and then enter its value.
For example,
# Integer: If `uid` is not provided it is automatically filled with the next one available.
# uid:
is entered as:
# Integer: If `uid` is not provided it is automatically filled with the next one available.
uid: 3000
Where 3000 is an available user identification (UID) number.
Enter values for all required and any optional properties you want to configure.
Save the modified file then Quit to exit the TUI and execute the user_create command.
Namespace Documentation
There are eleven primary or parent namespaces.
Each has additional child namespaces and commands to perform various actions.
⎙ Download or Print: View the entire CLI Reference Guide as a single page for download or print.
Account: Introduces the TrueNAS CLI account namespace, used to access user and group child namespaces and commands.
App: Introduces the TrueNAS CLI app namespace, used to access child namespaces and commands including catalog, chart_release, container, docker, and kubernetes.
Auth: Introduces the TrueNAS CLI auth namespace, used for currently logged-in user authentication and generating an access token for the web UI.
Directory Service: Introduces the TrueNAS CLI directory_service namespace, used to access child namespaces and commands including activedirectory, idmap, kerberos, and ldap.
Filesystem: Introduces the TrueNAS CLI filesystem namespace, used to access the acltemplate child namespace.
Network: Introduces the TrueNAS CLI network namespace, used to configure network settings found in the API and web UI.
Service: Introduces the TrueNAS CLI service namespace, used to access child namespaces and commands including cluster, ctdb, dyndns, ftp, gluster, ipmi, nfs, openvpn, rsync, rsync_mod, s3, smart, smb, snmp, ssh, tftp, vm, and webdav.
Sharing: Introduces the TrueNAS CLI sharing namespace, used to access child namespaces and commands including iscsi, nfs, smb, and webdav.
Storage: Introduces the TrueNAS CLI storage namespace, used to access child namespaces and commands including dataset, disk, enclosure, filesystem, pool, resilver, scrub, snapshot, and vmware.
System: Introduces the TrueNAS CLI system namespace that configures system related settings found in the API and web UI.
Task: Introduces the TrueNAS CLI task namespace, used to access child namespaces and commands including cloud_sync, cron_job, replication, rsync, smart_test, and snapshot.
1 - Account
Introduces the TrueNAS CLI account namespace, used to access user and group child namespaces and commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Welcome to the TrueNAS SCALE Command Line Interface (CLI) guide!
The TrueNAS CLI in TrueNAS SCALE functions like a text-based version of the web UI with many functional areas grouped into parent and child namespaces that mirror the counterparts in the SCALE UI.
The underlying structure of the CLI namespaces and commands closely follows that of the SCALE API.
For more information on API commands, arguments, options, and definitions go to API Keys and click on API Docs in the SCALE UI.
Account Namespace
The account namespace contains two child namespaces. It provides access to user and group creation, configuration, and management.
Account Namespaces
The following articles provide information on account child authentication namespaces:
User: Introduces the TrueNAS CLI account user namespace that configures Users related settings found in the API and web UI.
Group: Introduces the TrueNAS CLI account group namespace that configures Groups related settings found in the API and web UI.
1.1 - User
Introduces the TrueNAS CLI account user namespace that configures Users related settings found in the API and web UI.
The TrueNAS CLI guide for SCALE is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
User Namespace
The user namespace has 14 commands and is based on Users functions found in the SCALE API and web UI. It provides access to user account creation, configuration, and attribute management. You can also set up a local administrator account using this namespace.
User Commands
The following user namespace commands allow you to manage user accounts.
You can enter commands from the main CLI prompt or from the account namespace prompt.
Interactive Argument Editor (TUI)
Create Command
The create command configures a new user account.
Description
create has 19 configuration properties.
They are uid, username, group, group_create, home, home_mode, home_create, shell, full_name, email, password, password_disabled, locked, smb, sudo_commands, sudo_commands_nopasswd, sshpubkey, groups, and attributes.
A username, full name, primary group, and password status are all required for user creation.
For more details, see Create Configuration Properties.
account user create username=testuser full_name="Test User" group_create=true password=passwort1234
Press Enter
From the account prompt, enter:
user create username=testuser full_name="Test User" group_create=true password=passwort1234
Press Enter
Where testuser is the desired username, Test User is the user’s full name, true is a boolean value, and passwort1234 is the desired password for the account.
This command contains the minimum required properties to successfully create a user.
account user create username=testuser full_name="Test User" group_create=true password=passwort1234
Create Configuration Properties
create has 19 available properties for account configuration.
They are uid, username, group, group_create, home, home_mode, home_create, shell, full_name, email, password, password_disabled, locked, smb, sudo_commands, sudo_commands_nopasswd, sshpubkey, groups, and attributes.
Property arguments use the = delimiter to separate the property and value. For example, uid=3000.
See the table below for details.
Property
Accepts
Required
Function
uid
Integer
No
Specifies the User Identification number (UID). If a UID is not provided, it is automatically filled with the next one available. Ex: uid=3000 Where 3000 is an available UID number.
username
String
Yes
Sets the account username. Ex. username=testuser Where testuser is the desired username.
group
Integer or String
Yes*
Assigns the account to an existing group. Ex. group=value Where value is the group name or Group Identification number (GID). *Required when group_create is set to false.
group_create
Boolean
Yes*
If set to true, creates a new group based on username and assigns the account to it. Default state is false. Ex. group_create=true Where true is a boolean variable. *Required when an existing group is not assigned.
home
String
No
Sets a home directory for the account. Defaults to /nonexistent if not defined. Requires home_create=true if the desired directory does not exist. Ex. home="/mnt/tank/staff/" Where /mnt/tank/staff/ is an existing directory.
home_mode
String
No
Sets home directory permissions using octal permission values. Defaults to 700. Ex. home_mode= 700 Where 700 is an octal value representing the desired permission mode.
home_create
Boolean
No
If set to true, creates a new home directory for the user within a selected path defined by home. Default state is false. Reverts to default after the directory is created. Ex. home="/mnt/tank/" home_create=true Where /mnt/tank/ is the desired parent path and true is a boolean variable. This command creates a new home directory at /mnt/tank/. The directory name is the account username.
shell
String
No
Sets which shell option the user accesses when entering Shell via the TrueNAS SCALE Web UI. Defaults to /usr/bin/zsh if not defined. Available choices can be retrieved with user.shell_choices. Ex. shell="/usr/bin/bash" Where /usr/bin/bash is the desired shell choice.
full_name
String
Yes
Sets the user full name for the account. Ex. full_name="Test User" Where Test User is the user’s full name.
email
String or Null
No
Sets the account email address. Ex. email="testuser@gmail.com" Where testuser@gmail.com is the user email address.
password
String
Yes*
Assigns a password to the account. Ex. password=passw0rt Where passw0rt is the desired password. *Required when password_disabled is set to false.
password_disabled
Boolean
Yes*
Sets whether to disable or require a password for account log in. Default state is false, password required. Ex. password_disabled=true Where true is a boolean variable. *Required when password is not defined.
locked
Boolean
No
If set to true, prevents the user from logging in or using password-based services until this property is unset. Locking an account is only possible when Disable Password is false and a Password has been created for the account. Defaults to false. Ex. locked=true Where true is a boolean variable.
smb
Boolean
No
Enables or disables authentication of SMB shares for the user. Defaults to true. Enabling SMB authentication on an account where it was previously disabled requires setting a new password. Ex. smb=false Where false is a boolean variable.
sudo_commands
Array
No
Sets any sudo commands the user is allowed to use. Security best practice is to limit sudo permissions to administrative users. Ex. sudo_commands="</path1/>,</path2/>" Where </path1/> and </path2/> are absolute paths to the location of executable scripts or packages. You can also use sudo_commands="ALL"
sudo_commands_nopasswd
Array
No
Sets any sudo commands the user is allowed to use without entering a password. Exercise caution when allowing sudo commands without password prompts. It is recommended to limit this privilege to trusted users and specific commands to minimize security risks. Ex. sudo_commands_nopasswd="</path1/>,</path2/>" Where </path1/> and </path2/> are absolute paths to the location of executable scripts or packages. You can also use sudo_commands_nopasswd="ALL", but this is not recommended.
sshpubkey
String or Null
No
Adds a public SSH key of the user for any key-based authentication. Do not enter the private key. User account must have a defined home directory to store an SSH key. Ex. sshpubkey="<key>" Where <key> is the SSH public key string.
groups
Array
No
Assigns the user to one or more auxiliary groups. Ex. groups=news,staff,testuser Where news,staff,testuser are the names of desired groups.
attributes
Object
No
The attributes dictionary is a general-purpose object for storing arbitrary user information. This property can be used to store custom metadata and other information relevant to the user. Custom keys and corresponding values can relate to specfic needs and use cases. Ex. attributes={"favorite_color": "blue"} Where favorite_color is a new or existing key and blue is a corresponding value.
Delete Command
The delete command erases an existing user account.
By default, the user delete command also deletes the users’s primary group if it is not being used by another user.
The delete_group option set to false retains the user’s primary group.
Usage
From the CLI prompt, enter:
account user delete id=3001
Press Enter
From the account prompt, enter:
user delete id=3001
Press Enter
Where 3001 is the user ID number for the account.
account user delete id=<UID>
Use the delete_group option to retain the user’s primary group.
account user delete id=<UID> options={"delete_group": false}
Get_Instance Command
The TrueNAS CLI guide for SCALE is a work in progress!
Full documentation for this command is still being developed. Check back for updated information.
The get_instance command retrieves information about a user such as their username, UID (User ID), group membership, permissions, and other relevant attributes.
Get_Next_Uid Command
The get_next_uid command displays the next available user identification number (UID).
Description
The get_next_uid command does not require entering properties or values.
get_next_uid returns the next available UID in numerical order.
Default behavior begins identification number for local users at 3000.
Usage
From the CLI prompt, enter:
account user get_next_uid
Press Enter
From the account prompt, enter:
user get_next_uid
Press Enter
account user get_next_uid
3003
Get_User_Obj Command
The get_user_obj command returns dictionary containing information from struct passwd for the user and bypasses user cache.
Description
The get_user_obj command returns username, account UID, primary group GID, full name (displayed as pw_gecos), home directory, and shell preference setting.
The user account can be specified using either the username or UID.
get_user_obj has two additional options.
The get_groups option includes the user’s assigned groups in the command results.
Results do not include nested groups for Active Directory users.
The sid_info option retrieves the Security Identifier (SID) and domain information for the user.
In some instances retrieving SID and domain information makes the operation hang until the winbindd request timeout has been reached if the winbindd connection manager has not yet marked the domain as offline. Check the Active Directory service state prior to batch operations using this option.
Usage
From the CLI prompt, enter:
account user get_user_obj get_user_obj={“uid”: 3001}
Press Enter
From the account prompt, enter:
user get_user_obj get_user_obj={“uid”: 3001}
Press Enter
Where 3001 is the id number for the targeted account.
You can also use get_user_obj={“username”: “testuser”}, where testuser is the username of the targeted account.
Starting with SCALE Bluefin 22.12.0, root account logins are deprecated for security hardening and to comply with Federal Information Processing Standards (FIPS).
All TrueNAS users should create a local 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.
A future update of TrueNAS SCALE will permanently disable root account access.
Use pop_attribute to manage custom account attributes.
Use cases for the attributes storage object include custom user metadata, access control, user categorization, integration with external systems, and automation and policies.
The command returns true if the attribute is successfully deleted.
The command returns false if the specified key or user attribute does not exist.
Usage
From the CLI prompt, enter:
account user pop_attribute id=3001 key="favorite_color"
Press Enter
From the account prompt, enter:
account user pop_attribute id=3001 key="favorite_color"
Press Enter
Where 3001 is the UID of the target account and favorite_color is the account dictionary key to erase.
account user pop_attribute id=3001 key="favorite_color"
true
Query Command
The TrueNAS CLI guide for SCALE is a work in progress!
Full documentation for this command is still being developed. Check back for updated information.
The query command retrieves information about a user or users and can use various query-filters and query-options.
Description
Enter the command with no additional attributes or properties to perform a basic query of all local users.
Add additional properties to return the value of the specified key(s) for all users.
There are 23 query properties available.
Property
Purpose
uid
username
home
shell
full_name
email
password_disabled
locked
smb
sudo_commands
sudo_commands_nopasswd
sshpubkey
group
attributes
group
id
builtin
id_type_both
local
unixhash
smbhash
nt_name
sid
Expanded information may be requested by specifying the extra option
"extra": {"additional_information": []}.
There are two additional_information options supported.
Option
Purpose
SMB
Includes Windows SID and NT Name for user. If this option is not specified, then these keys have null value.
DS
Includes users from Directory Service (LDAP or Active Directory) in results
Use set_attribute to manage custom account attributes.
Use cases for the attributes storage object include custom user metadata, access control, user categorization, integration with external systems, and automation and policies.
Usage
From the CLI prompt, enter:
account user set_attribute id=3001 key="favorite_color" value="blue"
Press Enter
From the account prompt, enter:
user set_attribute id=3001 key="favorite_color" value="blue"
Press Enter
Where 3001 is the UID of the account to update, favorite_color is the desired property, and blue is the corresponding value.
account user set_attribute id=3001 key="favorite_color" value="blue"
true
Set_Root_Password Command
The set_root_password command is a deprecated method. Use the setup_local_administrator command instead.
Starting with SCALE Bluefin 22.12.0, root account logins are deprecated for security hardening and to comply with Federal Information Processing Standards (FIPS).
All TrueNAS users should create a local 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.
A future update of TrueNAS SCALE will permanently disable root account access.
Setup_Local_Administrator Command
The setup_local_administrator command creates and configures an admin account. It can be used during initial configuration.
The setup_local_administrator command only works if both a local administrator and root password have not been configured.
This means that you have either performed a fresh install of SCALE, and chose to not configure an admin or root password in the TrueNAS Console installer, or you have reset configuration to defaults and have not yet logged in to the SCALE Web UI.
If either a local administrator or a root password exist, this command returns Error: Local administrator is already set up.
Description
Enter the CLI from the Console setup menu before configuring a local administrator or root user account.
Introduces the TrueNAS CLI account group namespace that configures Groups related settings found in the API and web UI.
The TrueNAS CLI guide for SCALE is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Welcome to the TrueNAS SCALE Command Line Interface (CLI) guide!
The TrueNAS CLI in TrueNAS SCALE functions like a text-based version of the web UI with many functional areas grouped into parent and child namespaces that mirror the counterparts in the SCALE UI.
The underlying structure of the CLI namespaces and commands closely follows that of the SCALE API.
For more information on API commands, arguments, options, and definitions go to API Keys and click on API Docs in the SCALE UI.
Group Namespace
The group namespace contains eight commands and is based on functions found in the SCALE API and web UI. It provides access to group account creation, configuration, and management.
User Commands
The following group namespace commands allow you to manage groups.
You can enter commands from the main CLI prompt or from the system namespace prompt.
Interactive Argument Editor (TUI)
Create Command
The create command creates a new group.
Description
create has seven configuration properties.
They are gid, name, smb, sudo_commands, sudo_commands_nopasswd, allow_duplicate_gid, and users.
The only required property is name.
If a group identification number is not provided, it is automatically filled with the next one available.
For more details, see Create Configuration Properties.
Enter the command, then press Enter.
The command returns a blank line.
account group create name=TestGroup gid=3022 smb=false users=[3000,3001]
Where 3022 is the group id number, TestGroup is the group name, false is a boolean value, and 3000,3001 are user id numbers for group members.
Create Configuration Properties
create has one required and six optional properties for group configuration. name is required.
The optional properties are gid, smb, sudo_commands, sudo_commands_nopasswd, allow_duplicate_gid, and users.
Property arguments use the = delimiter to separate the property and value. For example, gid=3000.
See the table below for details.
Property
Accepts
Required
Function
gid
Integer
No
Assigns the group identification number. If gid is not provided it is automatically filled with the next one available. Ex. gid=3005 Where 3005 is an available GID number.
name
String
Yes
Sets the group name. Ex. name=TestGroup Where TestGroup is the desired group name.
smb
Boolean
No
Sets whether the group should be mapped into an NT group for Windows SMB sharing. Defaults to true. Ex. smb=false Where false is a boolean value.
sudo_commands
Array
No
Sets any sudo commands group members are allowed to use. Security best practice is to limit sudo permissions to administrative users. Ex. sudo_commands="path1,path2" Where path1 and path2 are absolute paths to the location of executable scripts or packages. You can also use sudo_commands="ALL"
sudo_commands_nopasswd
Array
No
Sets any sudo commands group members are allowed to use without entering a password. Exercise caution when allowing sudo commands without password prompts. It is recommended to limit this privilege to trusted users and specific commands to minimize security risks. Ex. sudo_commands_nopasswd="path1,path2" Where path1 and path2 are absolute paths to the location of executable scripts or packages. You can also use sudo_commands_nopasswd="ALL", but this is not recommended.
allow_duplicate_gid
Boolean
No
If set to true, allows distinct group names to share the same group identification number. Defaults to false. Important: Use only if absolutely necessary. Duplicate GIDs can lead to unexpected behavior. Ex. allow_duplicate_gid=true Where true is a boolean value.
users
Array or Integer
No
Assigns users to the group with a list of one or more user identification numbers (UIDs). Ex. users=[3001,3002] Where 3001 and 3002 are UID numbers for group members.
Delete Command
The delete command erases an existing group.
Description
If the delete_group option is set to true, the command also deletes any user with the target as its primary group. delete_group defaults to false.
account group delete id=3000 options={"delete_group": true}
Where 3000 is the group identification number and true is a boolean value.
options={"delete_group": true} deletes any users whose primary group matches the deleted group.
Carefully consider affected users before adding this option.
Get_Group_Obj Command
The get_group_obj command returns dictionary containing information from struct grp including group name, identification number, and group members.
Description
The target group can be specified by group name or GID.
The command returns a list of basic information about the group.
Usage
From the CLI prompt, enter:
account group get_group_obj get_group_obj={“groupname”: “TestGroup”}
Press Enter.
From the account prompt, enter:
group get_group_obj get_group_obj={“groupname”: “TestGroup”}
Where 3002 is the GID number for the target group.
Get_Instance Command
The TrueNAS CLI guide for SCALE is a work in progress!
Full documentation for this command is still being developed. Check back for updated information.
The get_instance command retrieves information about a group.
Get_Next_Gid Command
The get_next_gid command displays the next available group identification (GID) number.
Description
get_next_gid returns the next available GID in numerical order.
Default behavior begins identification number for local groups at 3000.
Usage
From the CLI prompt, enter:
account group get_next_gid
Press Enter
From the account prompt, enter:
group get_next_gid
Press Enter
account group get_next_gid
3000
Has_Password_Enabled_User Command
The has_password_enabled_user command checks whether at least one local user with a password enabled is a member of one or more provided groups.
Description
Target groups are specified by group identification number (GID).
Returns a single boolean value for all targeted groups.
The exclude_user_ids option sets specified password enabled users to ignore.
has_password_enabled_user returns a single boolean value for the entire list of GIDs queried. If more than one group is included in the query, the command does not return group specific information.
Usage
From the CLI prompt, enter:
account group has_password_enabled_user gids=3001
Press Enter
From the account prompt, enter:
group has_password_enabled_user gids=3001
Press Enter
Where 3001 represents the GID(s) to query.
account group has_password_enabled_user gids=3001
false
account group has_password_enabled_user gids=3002
true
account group has_password_enabled_user gids=3001,3002
true
Query Command
The TrueNAS CLI guide for SCALE is a work in progress!
Full documentation for this command is still being developed. Check back for updated information.
The query command retrieves information about a group or groups and can use various query-filters and query-options.
Description
Enter the command with no additional attributes or properties to perform a basic query of all local groups.
Add additional properties to return the value of the specified key(s) for all groups.
There are 13 query properties available.
Property
Purpose
gid
name
smb
sudo_commands
sudo_commands_nopasswd
users
id
group
builtin
id_type_both
local
nt_name
sid
Expanded information may be requested by specifying the extra option
"extra": {"additional_information": []}.
There are two additional_information options supported.
Option
Purpose
SMB
Includes Windows SID and NT Name for group. If this option is not specified, then these keys have null value.
DS
Includes groups from Directory Service (LDAP or Active Directory) in results
Introduces the TrueNAS CLI app namespace, used to access child namespaces and commands including catalog, chart_release, container, docker, and kubernetes.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Welcome to the TrueNAS SCALE Command Line Interface (CLI) guide!
The TrueNAS CLI in TrueNAS SCALE functions like a text-based version of the web UI with many functional areas grouped into parent and child namespaces that mirror the counterparts in the SCALE UI.
The underlying structure of the CLI namespaces and commands closely follows that of the SCALE API.
For more information on API commands, arguments, options, and definitions go to API Keys and click on API Docs in the SCALE UI.
App Namespace
The app namespace has five child namespaces and is based on functions found in the SCALE API and web UI.
It provides access to application configuration methods through the child namespaces and their commands.
You can enter commands from the main CLI prompt or from the app namespace prompts.
App Namespaces
The following articles provide information on app child namespaces:
Catalog: Provides information about the app catalog namespace in the TrueNAS CLI. Includes command syntax and common commands.
Chart_Release: Provides information about the app chart_release namespace in the TrueNAS CLI. Includes command syntax and common commands.
Container: Provides information about the app container namespace in the TrueNAS CLI. Includes command syntax and common commands.
Docker: Provides information about the app docker namespace in the TrueNAS CLI. Includes command syntax and common commands.
Kubernetes: Provides information about the app kubernetes namespace in the TrueNAS CLI. Includes command syntax and common commands.
2.1 - Catalog
Provides information about the app catalog namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the app chart_release namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the app container namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the app docker namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the app kubernetes namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Introduces the TrueNAS CLI auth namespace, used for currently logged-in user authentication and generating an access token for the web UI.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Auth Commands
The auth namespace has five commands and four child namespaces and is based on functions found in the SCALE API and web UI.
It provides access to authentication methods for the logged-in user and a method to generate an access token for web UI session through the five auth commands.
The four child namespaces have their own commands.
You can enter commands from the main CLI prompt or from an auth namespace prompt.
Check_User Command
The check_user and check_password commands verify the logged-in credentials.
The check_user command has two required options, username and password to include in the command string.
Command returns true if the values entered for the username and password are correct.
From the CLI prompt, enter:
auth check_user username=name password=password
From the auth prompt, enter:
check_user username=name password=password
Where:
username is the name assigned to the user logged in. For example, if the admin user is logged in and named admin, enter admin as the value.
password is the password assigned to the user logged in.
The check_password and check_user commands verify the logged-in user credentials.
The check_password command has two required options, username and password to include in the command string.
Command returns true if the values entered for the username and password are correct.
The generate_token command generates an authentication token to use for access. The setting determines when the current session expires.
The generate_token command has three required options, ttl, attrs, and match_origin to include in the command string.
Command returns an authentication token.
ttl= represents the time to live (ttl) value is in seconds. Values are either 600 or null. 600equates to an idle authentication session lasting 10 minutes before the token expires and the user must log back into the UI.
null means the session does not expire, and is not recommended as a best practice for system security.
attrs= {} represents attribute options for the token.
{} is the default. (Optional) Enter options in the curly brackets to define specific values.
match_origin=value represents a boolean (true/false) value.
The me command returns password, user and group information about the currently logged-in user.
The me command does not require entering additional options or arguments. Enter the command, then press Enter.
From the CLI prompt, enter:
auth me
From the auth namespace prompt, enter:
me
Output includes:
Property
Description
pw_name
Displays the logged-in user name. For example, admin.
pw_uid
Displays the user ID (UID) number for the logged-in user. For example, 3000.
pw_gid
Displays the group ID (GID) number for the logged-in user. For example, 3000.
pw_gecos
Displays the record in the /etc/passwd file, which is general information about the account or user. For example, for the admin user.
pw_dir
Displays the password or home directory for the logged-in user. For example, mnt/tank/homedir.
pw_shell
Displays the logged-in user shell setting. For example, /usr/bin/bash displays when the Shell setting on the Add User or Edit User screen is set to bash.
The two_factor_auth command returns the state of two-factor authentication for the logged-in user.
The two_factor_auth command does not require entering options. Enter the command, then press Enter.
From the CLI prompt, enter:
auth two_factor_auth
From the auth namespace prompt, enter:
two_factor_auth
auth two_factor_auth
false
Auth Child Namespace Articles
The following articles provide information on auth child authentication namespaces:
API_Key: Provides information about the auth api_key namespace in the TrueNAS CLI. Includes command syntax and common commands.
Privilege: Provides information about the auth privilege namespace in the TrueNAS CLI. Includes command syntax and common commands.
Sessions: Provides information about the auth sessions namespace in the TrueNAS CLI. Includes command syntax and common commands.
Two_Factor: Provides information about the auth two_factor namespace in the TrueNAS CLI. Includes command syntax and common commands.
3.1 - API_Key
Provides information about the auth api_key namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the auth privilege namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the auth sessions namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Welcome to the TrueNAS SCALE Command Line Interface (CLI) guide!
The TrueNAS CLI in TrueNAS SCALE functions like a text-based version of the web UI with many functional areas grouped into parent and child namespaces that mirror the counterparts in the SCALE UI.
The underlying structure of the CLI namespaces and commands closely follows that of the SCALE API.
For more information on API commands, arguments, options, and definitions go to API Keys and click on API Docs in the SCALE UI.
Sessions Commands
The sessions namespace has seven commands and is based on functions found in the SCALE API and web UI.
It provides access to session information through the seven sessions commands.
You can enter commands from the main CLI prompt or the auth namespace prompt.
Sessions Command
The sessions command returns a table that displays each session id, whether or not each session is current and internal, each session origin, and the credentials and credential data used to log into each session.
Description
The sessions command does not require entering properties or arguments.
Enter the command, then press Enter.
The command returns a table with the ID, current session state, origin such as an IP or socket information, credentials, and creation date and time.
The id command displays the IDs of all TrueNAS sessions since boot.
Description
The id command does not require entering properties or arguments.
Enter the command, then press Enter.
The command returns a table of recent and active session IDs.
Usage
From the CLI prompt, enter:
auth sessions id
auth sessions id
+--------------------------------------+
| id |
+--------------------------------------+
| 8a21fefe-1255-42eb-a86d-8a7f74752b94 |
| f01274e8-4954-4926-9346-76a16d3648dd |
+--------------------------------------+
Current Command
The current command displays whether or not the TrueNAS sessions in the sessions list are current.
Description
The current command does not require entering properties or arguments.
Enter the command, then press Enter.
The command returns a table showing which sessions are current (true) or not (false). The rows of the table are relative to the rows returned from the sessions command.
Usage
From the CLI prompt, enter:
auth sessions current
auth sessions current
+---------+
| current |
+---------+
| false |
| true |
+---------+
Internal Command
The internal command displays whether sessions in the sessions list are internally created (via the web UI) or not (via SSH).
Description
The internal command does not require entering properties or arguments.
Enter the command, then press Enter.
The command returns a table showing if sessions are internal (true) or not (false). The rows of the table are relative to the rows returned from the sessions command.
The origin command displays the login origin of the sessions in the sessions list.
Description
The origin command does not require entering properties or arguments.
Enter the command, then press Enter.
The command returns a table showing the login origin of each session. The rows of the table are relative to the rows returned from the sessions command.
The credentials command displays the credentials used to authenticate each session in the sessions list.
Description
The credentials command does not require entering properties or arguments.
Enter the command, then press Enter.
The command returns a table showing the credentials used to authenticate each session. See the table below for ll possible credential types. The rows of the table are relative to the rows returned from the sessions command.
Possible states:
Property
Description
UNIX_SOCKET
Indicates the session used web UI user credential authentication.
ROOT_TCP_SOCKET
Indicates the session used TCP and Root user credential authentication.
LOGIN_PASSWORD
Indicates the session used SSH password authentication.
API_KEY
Indicates the session used API key authentication.
The created_at command displays the creation date and time of the sessions in the sessions list.
Description
The created_at command does not require entering properties or arguments.
Enter the command, then press Enter.
The command returns a table showing the creation date and time of each session. The rows of the table are relative to the rows returned from the sessions command.
Provides information about the auth two_factor namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Two_Factor Commands
The two_factor namespace has five commands and is based on functions found in the SCALE API and web UI.
It provides access to two-factor authentication (2FA) configuration methods through the five two_factor commands.
Config Command
The config command displays current 2FA settings.
Description
The config command does not require entering properties or arguments.
Enter the command, then press Enter.
The command returns a table showing current 2FA settings.
The provisioning_uri command displays the provisioning URI for the One-Time Password (OTP).
The provisioning_uri command only displays part of the provisioning URI. For the full URI, access the TrueNAS web UI and go to Credentials > 2FA.
Description
The provisioning_uri command does not require entering properties or arguments.
Enter the command, then press Enter.
The command returns the OTP provisioning URI for authenticator app QR encoding.
The renew_secret command generates a new secret for 2FA.
Description
The renew_secret command does not require entering properties or arguments.
Enter the command, then press Enter.
The command returns true when successful, but displays an error if run when 2FA is not enabled.
Usage
From the CLI prompt, enter:
auth two_factor renew_secret
auth two_factor renew_secret
true
Update Command
The update command updates 2FA settings and requires one of five arguments in the command string: enabled, otp_digits, window, interval, and services.
Description
The update enabled command requires you to include either the true (enable) or false (disable) option.
Enter the command string, then press Enter.
The command returns nothing when successful.
Usage
From the CLI prompt, enter:
auth two_factor update enable=true/false
Where:
Where true enables two-factor authentication, and false disables it.
auth two_factor update enabled=true
Description
The update otp_digits command requires you to include a number from six to eight.
Enter the command string, then press Enter.
The command returns nothing when successful, and returns an error when you enter an invalid integer.
Usage
From the CLI prompt, enter:
auth two_factor update otp_digits=number
Where:
number is the number of digits from six to eight.
auth two_factor update otp_digits=6
Description
The update window command extends the validity of one-time passwords and requires you to include an integer.
Enter the command string, then press Enter.
The command returns nothing when successful, and returns an error when you enter an invalid integer.
Usage
From the CLI prompt, enter:
auth two_factor update window=number
Where:
number is the number of passwords before and after the current one that are still valid. Must be between 0 and 999999999999999999.
auth two_factor update window=1
Description
The update interval command sets the lifespans of one-time passwords and requires you to include an integer.
Enter the command string, then press Enter.
The command returns nothing when successful, and returns an error when you enter an invalid integer.
Usage
From the CLI prompt, enter:
auth two_factor update interval=number
Where:
number is the number (in seconds) an OTP will last before expiring. Must be between 5 and 999999999999999999.
s
auth two_factor update interval=30
Description
The update services command enables or disables 2FA for SSH logins, and requires you to include an argument.
Enter the command string, then press Enter.
The command returns nothing when successful.
Usage
From the CLI prompt, enter:
auth two_factor update services={“ssh”:true/false
Where:
true/false enables (true) or disables (false) SSH 2FA authentication.
auth two_factor update services={"ssh":true}
Verify Command
The verify command verifies whether or not a password is authenticated.
Description
The verify command requires the token property.
The property argument is separated by the = delimiter.
Enter the command, then press Enter.
The command returns true if provided token successfully authenticates.
Introduces the TrueNAS CLI directory_service namespace, used to access child namespaces and commands including activedirectory, idmap, kerberos, and ldap.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Welcome to the TrueNAS SCALE Command Line Interface (CLI) guide!
The TrueNAS CLI in TrueNAS SCALE functions like a text-based version of the web UI with many functional areas grouped into parent and child namespaces that mirror the counterparts in the SCALE UI.
The underlying structure of the CLI namespaces and commands closely follows that of the SCALE API.
For more information on API commands, arguments, options, and definitions go to API Keys and click on API Docs in the SCALE UI.
Directory_Service Commands
The directory_service namespace has two commands and four child namespaces and is based on functions found in the SCALE API and web UI.
It provides access to directory service methods.
The four child namespaces have their own commands.
You can enter commands from the main CLI prompt or from the directory_service namespace prompt.
Cache_Refresh Command
The cache_refresh command refreshes the directory services cache for users and groups. The user query and group query commands use this cache.
The first cache file in an Active Directory domain might take a significant amount of time to complete, so it is performed within a job.
Refresh the cache after adding new users or groups to a remote directory server to have the users or groups appear in the results.
A cache refresh is not required to use newly-added users and groups for permissions and ACL related methods.
It also does not resolve issues with users that cannot authenticate to shares.
The cache_refresh command displays the status of the cache-refresh process in percentage complete.
The get_state command returns the current status of the directory service.
The get_state command returns the state of the Active Directory and LDAP directory services.
Possible states:
Property
Description
DISABLED
Indicates directory service is disabled.
FAULTED
Indicates directory service is enabled, but not HEALTHY. Review logs and generated alert messages to debug the issue causing the faulted service state.
LEAVING
Indicates the directory service is in the process of stopping.
JOINING
Indicates the directory service is in the process of starting.
HEALTHY
Indicates the directory service is enabled, and the last status check passed.
The following articles provide information on directory_service child authentication namespaces:
Activedirectory: Provides information about the directory_service activedirectory namespace in the TrueNAS CLI. Includes command syntax and common commands.
Idmap: Provides information about the directory_service idmap namespace in the TrueNAS CLI. Includes command syntax and common commands.
Kerberos: Provides information about the directory_service kerberos namespace in the TrueNAS CLI. Includes command syntax and common commands.
LDAP: Provides information about the directory_service ldap namespace in the TrueNAS CLI. Includes command syntax and common commands.
4.1 - Activedirectory
Provides information about the directory_service activedirectory namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the directory_service idmap namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the directory_service kerberos namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the directory_service ldap namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Introduces the TrueNAS CLI filesystem namespace, used to access the acltemplate child namespace.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Welcome to the TrueNAS SCALE Command Line Interface (CLI) guide!
The TrueNAS CLI in TrueNAS SCALE functions like a text-based version of the web UI with many functional areas grouped into parent and child namespaces that mirror the counterparts in the SCALE UI.
The underlying structure of the CLI namespaces and commands closely follows that of the SCALE API.
For more information on API commands, arguments, options, and definitions go to API Keys and click on API Docs in the SCALE UI.
Filesystem Namespace
The filesystem namespace has one child namespace and is based on functions found in the SCALE API and web UI.
It provides access to ACL or permission methods through the child namespace and its command.
You can enter commands from the main CLI prompt or from the filesystem namespace prompts.
Filesystem Namespaces
The following articles provide information on filesystem child namespace:
Acltemplate: Provides information about the filesystem acltemplate namespace in the TrueNAS CLI. Includes command syntax and common commands.
5.1 - Acltemplate
Provides information about the filesystem acltemplate namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
The acltemplate namespace provides the ability to find existing ACL templates, create new or update exiting templates, or delete a template.
The web UI refers to ACL templates as presets.
This namesapce does not assign ACL permissions to a dataset.
The storage namespace provides access to commands to assign dataset permissions.
Acltemplate Commands
The acltemplate namespace has six commands and is based on functions found in the SCALE API and web UI.
It provides access to filesystem methods to list, create, edit, or delete ACL templates using the acltemplate commands.
You can enter commands from the main CLI prompt or from the filesystem acltemplate namespace prompt.
By_Path Command
The by_path command retrieves a list of available ACL templates for a given path.
Description
The by_path command has one required option value pair, acltemplate_ by_path.
Use the default {} to display the list of preset SCALE ACL templates.
by_path supports query-filters and query-options. format-options provides additional options to alter the template query results.
Format.optionsadditional options:
Option
Description
canonicalize
Places ACL entries for NFSv4 ACLS in Microsoft canonical order.
ensure_builtins
Ensures all resutls contain entries for builtin_users and builtin_administrators groups.
resolve_names
Converts IDs in ACL entries to names.
Usage
From the CLI prompt, enter:
filesystem acltemplate by_path acltemplate= {}
filesystem acltemplate by_path acltemplate= {}
+-----+-----------------+------------------------------------------------------------------+---------+--------+---------+
| id | name | comment | acltype | acl | bulitin |
+-----+-----------------+------------------------------------------------------------------+---------+----- --+---------+
| 1 | NFS4_OPEN | Template that grants full control to owner@, group@, and ever... | NFS4 | <list> | true |
| 2 | NFS4_RESTRICTED | Template that omits access for the everyone@ special entry. T... | NFS4 | <list> | true |
| 3 | NFS4_HOME | Template for special Samba homes share that only grants read ... | NFS4 | <list> | true |
| 4 | NFS4_DOMAIN_HOME | Template special Samba homes share in Active Directory(A... | NFS4 | <list> | true |
| 5 | POSIX_OPEN | Template that grants read, write, and execute permissions to ... | POSIX1E | <list> | true |
| 6 | POSIX_RESTRICTED | Template that grants read, write, and execute to owner and gr... | POSIX1E | <list> | true |
| 7 | POSIX_HOME | Template for special Samba homes share that only grants read ... | POSIX1E | <list> | true |
| 8 | NFS4_ADMIN | Template restricting access to local and domain administrators. | NFS4 | <list> | true |
| 9 | POSIX_ADMIN | Template restricting access to local and domain administrators. | POSIX1E | <list> | true |
+-----+-----------------+------------------------------------------------------------------+---------+--------+---------+
Create Command
The create command creates a filesystem ACL template.
The TrueNAS CLI guide for SCALE is a work in progress!
Full documentation for this command is still being developed. Check back for updated information.
Delete Command
The delete command deleted a filesystem acl template from the system.
The TrueNAS CLI guide for SCALE is a work in progress!
Full documentation for this command is still being developed. Check back for updated information.
Get_Instance
The get_instance command returns the instance matching the value of the ID number of the ACL template or the query-options-get_instance value specified.
Description
The get_instance command returns the instance matching the value of the id number or the query-options-get_instance value specified.
Enter the command, then press Enter.
Usage
From the CLI prompt, enter:
filesystem acltemplate get_instance id=10
Where 10 is the ID number for the template.
filesystem acltemplate get_instance id=1
+---------+------------------------------------------------------------------+
| id |1 |
| name | NFS4_OPEN |
| comment | Template that grants full control to owner@, group@, and ever... |
| acltype | NFS4 |
| acl | <list> |
| builtin | true |
+---------+------------------------------------------------------------------+
Query Command
The query command returns a list of filesystem ACL templates.
Description
The query command returns the list of filesystem ACL templates.
Enter the command, then press Enter.
The output from this command is the same as the acltemplate by_path acltemplate= {} command.
Usage
From the CLI prompt, enter:
filesystem acltemplate query
filesystem acltemplate query
+-----+-----------------+------------------------------------------------------------------+---------+--------+---------+
| id | name | comment | acltype | acl | bulitin |
+-----+-----------------+------------------------------------------------------------------+---------+----- --+---------+
| 1 | NFS4_OPEN | Template that grants full control to owner@, group@, and ever... | NFS4 | <list> | true |
| 2 | NFS4_RESTRICTED | Template that omits access for the everyone@ special entry. T... | NFS4 | <list> | true |
| 3 | NFS4_HOME | Template for special Samba homes share that only grants read ... | NFS4 | <list> | true |
| 4 | NFS4_DOMAIN_HOME | Template special Samba homes share in Active Directory(A... | NFS4 | <list> | true |
| 5 | POSIX_OPEN | Template that grants read, write, and execute permissions to ... | POSIX1E | <list> | true |
| 6 | POSIX_RESTRICTED | Template that grants read, write, and execute to owner and gr... | POSIX1E | <list> | true |
| 7 | POSIX_HOME | Template for special Samba homes share that only grants read ... | POSIX1E | <list> | true |
| 8 | NFS4_ADMIN | Template restricting access to local and domain administrators. | NFS4 | <list> | true |
| 9 | POSIX_ADMIN | Template restricting access to local and domain administrators. | POSIX1E | <list> | true |
+-----+-----------------+------------------------------------------------------------------+---------+--------+---------+
Update Command
The update command updates the filesystem ACL template for the id included in the command.
The TrueNAS CLI guide for SCALE is a work in progress!
Full documentation for this command is still being developed. Check back for updated information.
Introduces the TrueNAS CLI network namespace, used to configure network settings found in the API and web UI.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Welcome to the TrueNAS SCALE Command Line Interface (CLI) guide!
The TrueNAS CLI in TrueNAS SCALE functions like a text-based version of the web UI with many functional areas grouped into parent and child namespaces that mirror the counterparts in the SCALE UI.
The underlying structure of the CLI namespaces and commands closely follows that of the SCALE API.
For more information on API commands, arguments, options, and definitions go to API Keys and click on API Docs in the SCALE UI.
Network Namespace
The network namespace has seven child namespaces and is based on functions found in the SCALE API and web UI.
It provides access to network configuration methods through the child namespaces and their command.
You can enter commands from the main CLI prompt or from the network namespace prompts.
Network Child Namespace Contents
The following articles provide information on network child authentication namespaces:
DNS: Provides information about the network dns namespace in the TrueNAS CLI. Includes command syntax and common commands.
Configuration: Provides information about the network configuration namespace in the TrueNAS CLI. Includes command syntax and common commands.
General: Provides information about the network general namespace in the TrueNAS CLI. Includes command syntax and common commands.
Interface: Provides information about the network interface namespace in the TrueNAS CLI. Includes command syntax and common commands.
IPMI: Provides information about the network ipmi namespace in the TrueNAS CLI. Includes command syntax and common commands.
Route: Provides information about the network route namespace in the TrueNAS CLI. Includes command syntax and common commands.
Static_Route: Provides information about the network static_route namespace in the TrueNAS CLI. Includes command syntax and common commands.
6.1 - DNS
Provides information about the network dns namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
DNS Commands
The dns namespace has one command that is based on functions found in the SCALE API and web UI.
It displays the current DNS nameserver IP addresses configured on the system.
You can enter commands from the main CLI prompt or from a network namespace prompt.
Query Command
The query command returns the results of the query-filter and query-option for the dns namespace.
Enter as either a simple command to display the current DNS nameserver IP addresses configured on the system, or enter a command string to customize the output returned.
Run a simple dns command by pressing Enter after entering query.
The dns query command returns the current DNS nameserver IP addresses configured on the system.
To enter a string and define additional parameters, enter the query command and press space to see the autofill namespace option.
Press space again to see additional autofill argument options.
Entering the string customizes the information the query command returns.
Provides information about the network configuration namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Configuration Commands
The configuration namespace has three commands that are based on functions found in the SCALE API and web UI.
These commands return allowed network activity choices, configuration information, and allow you to change global network configuration settings.
Options can vary by the type of system and license applied (i.e., an HA system).
You can enter commands from the main CLI prompt or from a network namespace prompt.
Activity_choices Command
The activity_choices command returns a list of system activities.
Press Enter after entering the command to display the list.
From the CLI prompt, enter:
network configuration activity_choices
From the network prompt, enter:
configuration activity_choices
Config Command
The config command displays the current system configuration network settings.
Press Enter after entering the command to display the list.
From the CLI prompt, enter:
network configuration config
From the network prompt, enter:
configuration config
Update Command
This section covers configuring the default gateway.
Enter configuration (or network configuration if you just opened the TrueNAS CLI Shell).
Enter update ipv4gateway="ipaddress"
If entered properly, your system networking is now configured.
Provides information about the network general namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the network interface namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Interface Commands
The interface namespace has 24 commands based on functions found in the SCALE API and web UI.
These commands return interface and options by type (bridge, VLAN, etc.), allow you to add or manage settings, get interface and IP address information, and commit or roll back network changes for interfaces on the system.
Options can vary by the type of system and license applied (i.e., an HA system).
You can enter commands from the main CLI prompt or from a network namespace prompt.
Interfaces
This section covers assigning an IP address to a network interface.
Enter network interface.
If you do not already know the interface you want to configure, enter query to display a list of all physical network interfaces.
To edit the interface, enter update interfacename aliases=["ipaddress/subnetmask"] ipv4_dhcp=false
The CLI displays the message: “You have pending network interface changes. Please run ’network interface commit’ to apply them.”
Enter commit to apply the changes, then enter checkin to make them permanent.
Enter query to make sure the TrueNAS applies the changes successfully.
Enter .. to exit interface and go up one level to the network menu.
Provides information about the network ipmi namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the network route namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the network static_route namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Introduces the TrueNAS CLI service namespace, used to access child namespaces and commands including cluster, ctdb, dyndns, ftp, gluster, ipmi, nfs, openvpn, rsync, rsync_mod, s3, smart, smb, snmp, ssh, tftp, vm, and webdav.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Service Commands
The service namespace has 10 commands and 12 child namespaces and is based on functions found in the SCALE API and web UI.
It provides access to service configuration and validation methods for the 10 service commands.
The 12 child namespaces have their own commands.
You can enter commands from the main CLI prompt or from the service namespace prompt.
Get_Instance Command
The get_instance command displays the id, name, and status of a service.
The get_instance command requires you to include the id option in the command string. After entering the command correctly, it returns a table with multiple outputs.
From the CLI prompt, enter:
service get_instance id=number
From the service prompt, enter:
get_instance id=number
Where:
number is the service id. For example, if the ssh service id is 11, enter 11.
get_instance id=11
+---------+--------------+
| id | 11 |
| service | ssh |
| enable | false |
| state | STOPPED |
| pids | <empty list> |
+---------+--------------+
Query Command
The query command displays a simple overview of all services.
The query command has no additional requirements. After entering the command, it returns a table with multiple outputs.
The reload command requires you to include the service option in the command string. After entering the command correctly, it returns either a true or false output.
From the CLI prompt, enter:
service reload service=name
From the service prompt, enter:
reload service=name
Where:
name is the service name. For example, enter ssh for the ssh service.
Possible states:
Property
Description
true
Indicates the service reloaded.
false
Indicates the service did not reload.
reload service=ssh
true
Restart Command
The restart command restarts a specified service.
The restart command requires you to include the service option in the command string. After entering the command correctly, it returns either a true or false output.
From the CLI prompt, enter:
service restart service=name
From the service prompt, enter:
restart service=name
Where:
name is the service name. For example, enter ssh for the ssh service.
Possible returns:
Property
Description
true
The service restarted successfully.
false
The service did not restart.
restart service=ssh
true
Start Command
The start command restarts a specified service.
The start command requires you to include the service option in the command string. After entering the command correctly, it returns either a true or false output.
From the CLI prompt, enter:
service start service=name
From the service prompt, enter:
start service=name
Where:
name is the service name. For example, enter ssh for the ssh service.
Possible returns:
Property
Description
true
The service started successfully.
false
The service did not start.
start service=ssh
true
Started Command
The started command verifies whether or not a start command succeeded for a specified service.
Possible returns:
Property
Description
true
The service started successfully.
false
The service did not start.
The started command requires you to include the service option in the command string. After entering the command correctly, it returns either a true or false output.
From the CLI prompt, enter:
service started service=name
From the service prompt, enter:
started service=name
Where:
name is the service name. For example, enter ssh for the ssh service.
started service=ssh
true
Started_or_Enabled Command
The started_or_enabled command displays whether or not a service starts automatically upon reboot or is running.
Possible returns:
Property
Description
true
The service restarts automatically and/or is running.
false
The service is not running, nor does start automatically.
The started_or_enabled command requires you to include the service option in the command string. After entering the command correctly, it returns either a true or false output.
From the CLI prompt, enter:
service started_or_enabled service=name
From the service prompt, enter:
started_or_enabled service=name
Where:
name is the service name. For example, enter ssh for the ssh service.
started_or_enabled service=ssh
true
Stop Command
The start command restarts a specified service.
Possible returns:
Property
Description
false
The service stopped or is not running.
The stop command requires you to include the service option in the command string. After entering the command correctly, it returns either a true or false output.
From the CLI prompt, enter:
service stop service=name
From the service prompt, enter:
stop service=name
Where:
name is the service name. For example, enter ssh for the ssh service.
stop service=ssh
false
Terminate_Process Command
The terminate_process command forces a service to stop and disables it.
The command only returns with true to show that the service stopped or is not running.
The terminate_process command requires you to include the pid option in the command string. You may also include the timeout option (not required) to specify the amount of time (in seconds) the system should attempt to terminate the service. After entering the command correctly, it returns either a true or false output.
From the CLI prompt, enter:
service terminate_process pid=number timeout=number
From the service prompt, enter:
terminate_process pid=number timeout=number
Where:
number is the pid (process id) and the number of seconds before the task times out. For example, 108648 and 1 to try terminating process 108648 for 10 seconds.
terminate_process pid=108648 timeout=true
true
Update Command
The update command lets you decide whether or not you want a service to start automatically upon system reboot.
The update command requires you to include the id_or_name and enable options in the command string.
From the CLI prompt, enter:
service update id_or_name=number/name enable=true/false
From the service prompt, enter:
update id_or_name=number/name enable=true/false
Where:
number/name is the service id name. For example, enter 11 or ssh for the ssh service.
true/false enables (true) or disables (false) the start automatically feature.
update id_or_name=ssh enable=true
7.1 - Cluster
Provides information about the service cluster namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the service ctdb namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the service dyndns namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
This service is deprecated in TrueNAS SCALE 23.10.
Provides information about the service ftp namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the service gluster namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the service openvpn namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
This service is deprecated in TrueNAS SCALE 23.10.
Provides information about the service rsync namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
This service is deprecated in TrueNAS SCALE 23.10.
Provides information about the service rsync_mod namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
This service is deprecated in TrueNAS SCALE 23.10.
Provides information about the service s3 namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
This service is deprecated in TrueNAS SCALE 23.10.
Provides information about the service ipmi namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the service nfs namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the service smb namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the service snmp namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the service ssh namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the service tftp namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
This service is deprecated in TrueNAS SCALE 23.10.
Provides information about the service ups namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the service vm namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the service webdav namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
This service is deprecated in TrueNAS SCALE 23.10.
Provides information about the service smart namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Introduces the TrueNAS CLI sharing namespace, used to access child namespaces and commands including iscsi, nfs, smb, and webdav.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Welcome to the TrueNAS SCALE Command Line Interface (CLI) guide!
The TrueNAS CLI in TrueNAS SCALE functions like a text-based version of the web UI with many functional areas grouped into parent and child namespaces that mirror the counterparts in the SCALE UI.
The underlying structure of the CLI namespaces and commands closely follows that of the SCALE API.
For more information on API commands, arguments, options, and definitions go to API Keys and click on API Docs in the SCALE UI.
Sharing Namespace
The sharing namespace has four child namespaces and is based on functions found in the SCALE API and web UI.
It provides access to configure shares through the child namespaces and their commands.
You can enter commands from the main CLI prompt or from the sharing namespace prompts.
Sharing Namespaces
The following articles provide information on sharing child namespaces:
iSCSI: Provides information about the sharing iscsi namespace in the TrueNAS CLI. Includes command syntax and common commands.
NFS: Provides information about the sharing nfs namespace in the TrueNAS CLI. Includes command syntax and common commands.
SMB: Provides information about the sharing smb namespace in the TrueNAS CLI. Includes command syntax and common commands.
Webdav (Deprecated): Provides information about the deprecated sharing webdav namespace in the TrueNAS CLI. Includes command syntax and common commands.
8.1 - iSCSI
Provides information about the sharing iscsi namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the sharing nfs namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the sharing smb namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the deprecated sharing webdav namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Introduces the TrueNAS CLI storage namespace, used to access child namespaces and commands including dataset, disk, enclosure, filesystem, pool, resilver, scrub, snapshot, and vmware.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Welcome to the TrueNAS SCALE Command Line Interface (CLI) guide!
The TrueNAS CLI in TrueNAS SCALE functions like a text-based version of the web UI with many functional areas grouped into parent and child namespaces that mirror the counterparts in the SCALE UI.
The underlying structure of the CLI namespaces and commands closely follows that of the SCALE API.
For more information on API commands, arguments, options, and definitions go to API Keys and click on API Docs in the SCALE UI.
Storage Namespace
The storage namespace has nine child namespaces and is based on functions found in the SCALE API and web UI.
It provides access to storage configuration methods through the child namespaces and their commands.
You can enter commands from the main CLI prompt or from the storage namespace prompts.
Storage Namespaces
The following articles provide information on storage child namespaces:
Dataset: Provides information about the storage dataset namespace in the TrueNAS CLI. Includes command syntax and common commands.
Disk: Provides information about the storage disk namespace in the TrueNAS CLI. Includes command syntax and common commands.
Enclosure: Provides information about the storage enclosure namespace in the TrueNAS CLI. Includes command syntax and common commands.
Filesystem (Storage): Provides information about the storage filesystem namespace in the TrueNAS CLI. Includes command syntax and common commands.
Pool: Provides information about the storage pool namespace in the TrueNAS CLI. Includes command syntax and common commands.
Resilver: Provides information about the storage resilver namespace in the TrueNAS CLI. Includes command syntax and common commands.
Scrub: Provides information about the storage scrub namespace in the TrueNAS CLI. Includes command syntax and common commands.
Snapshot: Provides information about the storage snapshot namespace in the TrueNAS CLI. Includes command syntax and common commands.
VMWare: Provides information about the storage vmware namespace in the TrueNAS CLI. Includes command syntax and common commands.
9.1 - Dataset
Provides information about the storage dataset namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Listing Datasets
To list all configured datasets, enter storage dataset query.
Provides information about the storage disk namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the storage enclosure namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Enclosure Commands
The enclosure namespace has four commands and is based on functions found in the SCALE API and web UI.
It provides access to enclosure management methods through the four enclosure commands.
You can enter commands from the main CLI prompt or from the enclosure namespace prompt.
Get_Instance Command
The get_instance command displays the status of a specified enclosure.
The get_instance command only requires the id option. Command returns a table of values when entered correctly.
From the CLI prompt, enter:
enclosure get_instance id=name
From the enclosure prompt, enter:
get_instance id=name
If there are variables in the command include this section:
Where:
id is the enclosure id. For example, mapped_enclosure_0.
get_instance id=mapped_enclosure_0
+------------+--------------------+
| id | mapped_enclosure_0 |
| name | Drive Bays |
| model | R40 |
| controller | true |
| elements | <list> |
| number | 0 |
| label | Drive_Bays |
+------------+--------------------+
Query Command
The query command lists all enclosures in the system.
The query command has no additional requirements. After entering the command, it returns a table with multiple outputs.
From the CLI prompt, enter:
enclosure query
From the service prompt, enter:
query
enclosure> query
+--------------------+------------+-------+------------+----------+--------+------------+
| id | name | model | controller | elements | number | label |
+----+---------------+------------+-------+------------+----------+--------+------------+
| mapped_enclosure_0 | Drive Bays | R40 | true | <list> | 0 | Drive_Bays |
+--------------------+------------+-------+------------+----------+--------+------------+
Set_Slot_Status Command
The set_slot_status command forces a drive slot into a specified state.
The set_slot_status command has three required options, enclosure_id, slot, and status to include in the command string. Command returns an empty line when entered correctly.
Provides information about the storage filesystem namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the storage pool namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Listing Storage Pools
To list all configured storage pools, enter storage pool query.
Provides information about the storage resilver namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the storage scrub namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the storage snapshot namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the storage vmware namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Introduces the TrueNAS CLI system namespace that configures system related settings found in the API and web UI.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Welcome to the TrueNAS SCALE Command Line Interface (CLI) guide!
The TrueNAS CLI in TrueNAS SCALE functions like a text-based version of the web UI with many functional areas grouped into parent and child namespaces that mirror the counterparts in the SCALE UI.
The underlying structure of the CLI namespaces and commands closely follows that of the SCALE API.
For more information on API commands, arguments, options, and definitions go to API Keys and click on API Docs in the SCALE UI.
System Namespace
The system namespace has 23 child namespaces and 19 commands, and is based on functions found in the SCALE API and web UI.
It provides access to system configuration methods through the system namespace commands and the child namespaces and their commands.
You can enter commands from the main CLI prompt or from the system namespace prompt.
System Commands
The system namespace has 19 commands based on functions found in the SCALE API and web UI.
You can enter commands from the main CLI prompt or from the system namespace prompt.
Boot_ID Command
The boot_id command returns a unique boot identifier consisting of lowercase aphanumeric characters and dashes.
The boot_id command does not require entering options or arguments.
Enter the command, then press Enter.
The command returns a unique alphanumeric identifier.
From the CLI prompt, enter:
system boot_id
From the system prompt, enter:
boot_id
system boot_id
16b14f52-7da1-a042-bb39c5c0d183
Build_Time Command
The build_time command returns the date and time of the software build installed and running on the system but not the release name and number.
Use the version or version_short commands to see the name and number assigned to the software build.
The build_time command does not require entering options or arguments.
Enter the command, then press Enter.
The command returns the date and time of the software build installed and running on the system.
From the CLI prompt, enter:
system build_time
From the system prompt, enter:
build_time
system build_time
16b14f52-7da1-a042-bb39c5c0d183
Debug Command
The debug command downloads a system debug file to the home directory of the logged in admin user.
Specify the file name and extension for the debug file in the command string.
Debug files are usually .tgz files but you can use the extension of your choice.
Use a file transfer application such as WinSCP to connect to the system or a share (SMB, NFS, etc.) created on the system to access the file.
Enter the debug command followed by the > and then the filename.ext.
Press Enter to begin the download. The command displays status of logs downloaded.
From the CLI prompt, enter:
system debug > filename.ext
From the system prompt, enter:
debug > filename.ext
where filename is the name of the file and .ext is the file extension
system debug > debugfilename-date.tgz
[0%] …
[0%] Generating debug file…
[6%] Dump Active Directory Configuration…
[12%] Dump Hardware Configuration…
[18%] Dump iSCSI Configuration…
[25%] Dump Kubernetes Configuration…
[31%] Dump LDAP Configuration…
[37%] Dump Network Configuration…
[44%] Dump NFS Configuration…
[50%] Dump SMART Configuration…
[56%] Dump SMB Configuration…
[63%] Dump SSL Configuration…
[69%] Dump Sysctl Configuration…
[75%] Dump System Information…
[81%] Dump ZFS Configuration…
[86%] Compressing System Logs…
[87%] Compressing Debug Files…
[88%] Truncating Debug Files…
[87%] Copying Core Dumps…
[88%] Collecting Additional Information…
[89%] Compressing Archive…
[90%] Debug generation finished…
[90%] Preparing debug file for streaming…
[100%] Preparing debug file for streaming…
[100%] Job output (12320768 bytes) saved at ‘systemdebug-6-15-2023.tgz’
Environment Command
The environment commands returns the environment in which the product is running.
Possible values are DEFAULT or EC2.
The environment command does not require entering options or arguments.
Enter the command, then press Enter.
The environment command returns the current environment in which the product is running.
From the CLI prompt, enter:
system environment
From the system prompt, enter:
environment
system environment
DEFAULT
Feature_Enabled Command
The feature_enabled command determines if the feature specified is running.
Use to determine if the deduplication, fibre channel or virtual machine (VM) feature is enabled or disabled.
The feature_enabled command uses the feature option to specify one of three system features, DEDUP, FIBRECHANNEL, or VM, to get the enabled/disabled status of that feature.
Enter the command string, then press Enter. The command returns true for an enabled system feature, or false for disabled.
From the CLI prompt, enter:
system feature_enabled feature=option
From the system prompt, enter:
system feature_enabled feature=option
where options is DEDUP, FIBRECHANNEL, or VM.
system feature_enabled feature=DEDUP
false
Host_ID Command
The host_id command retrieves a hex string that is generated based on the contents of the /etc/hostid file.
This is a permanent value that persists across reboots/upgrades and can be used as a unique identifier for the machine.
The host_id command does not require entering options or arguments.
Enter the command, then press Enter. The host_id command returns a string of alphanumeric characters.
From the CLI prompt, enter:
system host_id
From the system prompt, enter:
host_id
system host_id
4c89087092kjfm709oeuanl234noidnvo536vlkujou231noi35n13nn
Info Command
The info command returns system information. Information includes:
SCALE version and build time
System host name
Hardware information including phyical memory, cores and physical cores, system product and version, manufacturer
System serial number
System uptime and uptime seconds, average loading, boot time, and date time
System timezone
System license
The info command does not require entering options or arguments.
Enter the command, then press Enter.
The command returns a table of system details.
The is_freenas command is deprecated. Use product_type command. Applied to TrueNAS CORE systems.
Is_Stable Command
The is_stable command returns whether the system software version is stable. This command is useful if upgrading from a nightly train of an unreleased version.
The is_stable command does not require entering options or aguments.
Enter the command, then press Enter. The command returns true if stable, false if not.
From the CLI prompt, enter:
system is_stable
From the system prompt, enter:
is_stable
system is_stable
true
License_Update Command
The license_update command updates the license file.
This is the license added to the system on the System Settings > General screen on the Support widget.
The license_update uses the license option to specify the license to update.
Enclose the license string in double quotes.
Enter the command, then press Enter.
The command returns you to the CLI prompt.
From the CLI prompt, enter:
system license_update license="AUZyZWVOQVMgTWluaQAAAABBMS00MDA5MQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAYAADIwMjMwNjIwAAAAANsCAAAAAAAAaVhzeXN0ZW1zOiBJbnRlcm5hbCBVc2UAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAoAAAAAAAAAAA=="
system license_update license="AUZyZWVOQVMgTWluaQAAAABBMS00MDA5MQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAYAADIwMjMwNjIwAAAAANsCAAAAAAAAaVhzeXN0ZW1zOiBJbnRlcm5hbCBVc2UAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAoAAAAAAAAAAA=="
Product_Name Command
The product_name command returns the name of the product (TrueNAS) in use.
The product_name command does not require an option or argument.
Enter the command, then press Enter. The command returns TrueNAS as the product name.
From the CLI prompt, enter:
system product_name
From the system prompt, enter:
product_name
system product_name
TrueNAS
Product_Type Command
The product_type command returns the name of the product (SCALE) in use.
The product_type command does not require an option or argument.
Enter the command, then press Enter. The command returns SCALE as the product name.
From the CLI prompt, enter:
system product_type
From the system prompt, enter:
product_type
system product_type
SCALE
Ready Command
The ready command returns whether the system completed the boot process and is ready to use.
This command is similar to the state command that provides the status of the system as READY or BOOTING.
The ready command does not require an option or argument.
Enter the command, then press Enter. The command returns true if the boot completed an the system is ready.
From the CLI prompt, enter:
system ready
From the system prompt, enter:
ready
system ready
true
Reboot Command
The reboot command reboots the system. It is the CLI equivalent to the UI power button option to restart the system.
The reboot command does not require an option or argument.
Enter the command, then press Enter.
The option to include system-reboot and specify a value exists but is not required to reboot the system.
From the CLI prompt, enter:
system reboot
From the system prompt, enter:
reboot
system reboot
[0] ...
[100] ...
Shutdown Command
The shutdown command exits the UI and shuts down the system. It is the CLI equivalent to the UI power button option to shutdown the system.
The shutdown command does not require an option or argument.
Enter the command, then press Enter.
The option to include system-shutdown and specify a value exists, but is not required to shut down the system.
From the CLI prompt, enter:
system shutdown
From the system prompt, enter:
shutdown
system shutdown
[0] ...
[100] ...
State Command
The state command returns the current system state as either booting, ready, or shutting down.
Use to determine the system state if uncertain of the current state. This command is similar to the ready command that indicates if the system completed the boot process and is ready.
The state command does not require an option or argument.
Enter the command, then press Enter.
The command returns the current state as BOOTING when the sytem is booting, READY when the system is either not booting or shutting down, or SHUTTING_DOWN if the system is shutting down.
From the CLI prompt, enter:
system state
From the system prompt, enter:
state
system state
READY
Version Command
The version command returns the system full software version name and number.
If uncertain of your SCALE release, enter this or the version_short command to view the currently-installed version number.
The version command does not require an option or argument.
Enter the command, then press Enter.
From the CLI prompt, enter:
system version
From the system prompt, enter:
version
system version
TrueNAS-SCALE-22.12.3
Version_Short Command
The version_short command returns the system software version number.
If uncertain of your SCALE release, enter this or the version command to view the currently-installed version name.
The version_short command does not require an option or argument.
Enter the command, then press Enter.
From the CLI prompt, enter:
system version_short
From the system prompt, enter:
version_short
system version_short
22.12.3
System Namespaces
The following articles provide information on system child namespaces:
ACME: Provides information about the system acme namespace in the TrueNAS CLI. Includes command syntax and common commands.
Advanced: Provides information about the system advanced namespace in the TrueNAS CLI. Includes command syntax and common commands.
Alert: Provides information about the system alert namespace in the TrueNAS CLI. Includes command syntax and common commands.
Boot: Provides information about the system boot namespace in the TrueNAS CLI. Includes command syntax and common commands.
Bootenv: Provides information about the system bootenv namespace in the TrueNAS CLI. Includes command syntax and common commands.
Certificate: Provides information about the system certificate namespace in the TrueNAS CLI. Includes command syntax and common commands.
Config: Provides information about the system config namespace in the TrueNAS CLI. Includes command syntax and common commands.
Core: Provides information about the system core namespace in the TrueNAS CLI. Includes command syntax and common commands.
Device: Provides information about the system device namespace in the TrueNAS CLI. Includes command syntax and common commands.
Failover: Provides information about the system failover namespace in the TrueNAS CLI. Includes command syntax and common commands.
General: Provides information about the system general namespace in the TrueNAS CLI. Includes command syntax and common commands.
Init_Shutdown_Script: Provides information about the system init_shutdown_script namespace in the TrueNAS CLI. Includes command syntax and common commands.
Keychain_Credential: Provides information about the system keychain_credential namespace in the TrueNAS CLI. Includes command syntax and common commands.
KMIP: Provides information about the system kmip namespace in the TrueNAS CLI. Includes command syntax and common commands.
Mail: Provides information about the system mail namespace in the TrueNAS CLI. Includes command syntax and common commands.
NTP_Server: Provides information about the system ntp_server namespace in the TrueNAS CLI. Includes command syntax and common commands.
Reporting: Provides information about the system reporting namespace in the TrueNAS CLI. Includes command syntax and common commands.
Support: Provides information about the system support namespace in the TrueNAS CLI. Includes command syntax and common commands.
System_Dataset: Provides information about the system system_dataset namespace in the TrueNAS CLI. Includes command syntax and common commands.
TrueCommand: Provides information about the system truecommand namespace in the TrueNAS CLI. Includes command syntax and common commands.
Truenas: Provides information about the system truenas namespace in the TrueNAS CLI. Includes command syntax and common commands.
Tunable: Provides information about the system tunable namespace in the TrueNAS CLI. Includes command syntax and common commands.
Update: Provides information about the system update namespace in the TrueNAS CLI. Includes command syntax and common commands.
10.1 - ACME
Provides information about the system acme namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the system advanced namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the system alert namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the system boot namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the system bootenv namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the system certificate namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the system config namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the system core namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the system device namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the system failover namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the system general namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
System General Commands
The system > general namespace has 14 commands and is based on functions found in the SCALE API and web UI.
It provides access to general system methods to configure time zone, language, HTTP protocol, UI address, and system certificate options.
You can also restart the system through this namespace.
You can enter commands from the main CLI prompt or from the system namespace prompt.
Adding the SCALE UI to an Iframe
To add the SCALE UI to an inline frame (iframe) using the system general update ui_x-frame_options command.
An iframe allows you to deploy the SCALE UI inside an existing HTML document.
Iframes are commonly used to host third-party content safely inside the frame where it cannot access the content of the host and the host cannot access the content of the iframe.
From the CLI prompt, enter:
system general update ui_x-frame_options=ALLOW_All
From the general prompt, enter:
update ui_x-frame_options=ALLOW_All
system general update ui_x-frame_options=ALLOW_All
Provides information about the system init_shutdown_script namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the system keychain_credential namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the system kmip namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the system mail namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the system ntp_server namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the system reporting namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the system support namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the system system_dataset namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the system truecommand namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the system truenas namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the system tunable namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the system update namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Performing Manual Updates
To perform a manual update via the TrueNAS CLI Shell, you must first upload a manual update file onto the system.
Connect to your system with your choice of FTP program (such as WinSCP) and place the manual update file in /var/tmp/firmware.
Once it finishes uploading, go to the console setup menu and launch the TrueNAS CLI Shell.
Enter system update manual path="/var/tmp/firmware/updatefilename"
Introduces the TrueNAS CLI task namespace, used to access child namespaces and commands including cloud_sync, cron_job, replication, rsync, smart_test, and snapshot.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Welcome to the TrueNAS SCALE Command Line Interface (CLI) guide!
The TrueNAS CLI in TrueNAS SCALE functions like a text-based version of the web UI with many functional areas grouped into parent and child namespaces that mirror the counterparts in the SCALE UI.
The underlying structure of the CLI namespaces and commands closely follows that of the SCALE API.
For more information on API commands, arguments, options, and definitions go to API Keys and click on API Docs in the SCALE UI.
Task Namespace
The task namespace has six child namespaces and is based on functions found in the SCALE API and web UI.
It provides access to task configuration methods through the child namespaces and their commands.
You can enter commands from the main CLI prompt or from the task namespace prompts.
Task Namespaces
The following articles provide information on task child authentication namespaces:
Cloud_Sync: Introduces the TrueNAS CLI task cloud_sync namespace, used to access the credentials child namespace and commands.
Credential: Provides information about the task cloud_sync credential namespace in the TrueNAS CLI. Includes command syntax and common commands.
Cron_Job: Provides information about the task cron_job namespace in the TrueNAS CLI. Includes command syntax and common commands.
Replication: Provides information about the task replication namespace in the TrueNAS CLI. Includes command syntax and common commands.
Rsync: Provides information about the task rsync namespace in the TrueNAS CLI. Includes command syntax and common commands.
Smart_Test: Provides information about the task smart_test namespace in the TrueNAS CLI. Includes command syntax and common commands.
Snapshot (Task): Provides information about the task snapshot namespace in the TrueNAS CLI. Includes command syntax and common commands.
11.1 - Cloud_Sync
Introduces the TrueNAS CLI task cloud_sync namespace, used to access the credentials child namespace and commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Welcome to the TrueNAS SCALE Command Line Interface (CLI) guide!
The TrueNAS CLI in TrueNAS SCALE functions like a text-based version of the web UI with many functional areas grouped into parent and child namespaces that mirror the counterparts in the SCALE UI.
The underlying structure of the CLI namespaces and commands closely follows that of the SCALE API.
For more information on API commands, arguments, options, and definitions go to API Keys and click on API Docs in the SCALE UI.
Cloud_Sync Namespace
The cloud_sync namespace has one child namespace and is based on functions found in the SCALE API and web UI.
It provides access to cloud_sync task configuration methods through the child namespace and commands.
You can enter commands from the main CLI prompt or from the cloud_sync namespace prompts.
Cloud_Sync Namespaces
The following articles provide information on cloud_sync child authentication namespaces:
Credential: Provides information about the task cloud_sync credential namespace in the TrueNAS CLI. Includes command syntax and common commands.
11.1.1 - Credential
Provides information about the task cloud_sync credential namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the task cron_job namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the task replication namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the task rsync namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the task smart_test namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
Provides information about the task snapshot namespace in the TrueNAS CLI. Includes command syntax and common commands.
The SCALE CLI guide is a work in progress!
New namespace and command documentation is continually added and maintained, so check back here often to see what is new!
