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!
Launching the TrueNAS CLI
The SCALE Shell automatically opens in the SCALE CLI if the admin user Shell setting on the Credentials > Local User > Add User or Edit User screen is set to TrueNAS CLI.
If set to a different shell option such as bash or zsh, enter cli at the prompt on the shell screen.
You can also access the TrueNAS CLI through either the Console Setup Menu.
Entering the TrueNAS CLI from Console Setup Menu
You can access the Console Setup Menu when you SSH into the TrueNAS system, after you install SCALE from the iso, or from the Shell.
If you set the admin user Shell setting to TrueNAS Console, the Shell opens in the console setup menu.
The Shell screen opens in the shell option selected in the Shell setting on the Credentials > Local User > Add User or Edit User screen.
If set to zsh, bash, or the other options other than TrueNAS CLI or TrueNAS Console, the screen opens at a Linux prompt.
To access the TrueNAS CLI from the Linux shell, enter cli at the 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 the user and group namespaces and commands. In the UI these are found on the **Credentials screen.
app
Provides access to the catalog, chart_release, container, docker and kubernetes namespaces and commands.
auth
Provides access to the authentication api_key, privilege, sessions, and two_factor namespaces and commands.
directory_service
Provides access to directory services activedirectory, idmap, kerberos, and ldap namespaces and commands.
filesystem
Provides access to the acltemplate namespace.
network
Provides access to network configuration, dns, interface, ipmi, route, and static_route namespaces and commands.
service
Provides access to service cluster, ctdb, dyndns, ftp, gluster, ipmi, nfs, openvpn, rsync, rsync_mod, s3, smart, smb, snmp, ssh, tftp, vm, and webdav namespaces and commands.
sharing
Provides access to sharing iscsi, nfs, smb, and webdav namespaces and commands.
storage
Provides access to storage dataset, disk, enclosure, filesystem, pool, resilver, scrub, snapshot, and vmware namespaces and commands.
system
Provides access system 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 namespaces and commands.
task
Provides access to task cloud_sync, cron_job, replication, rsync, smart_test, and snapshot namespaces and commands.
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.
Press the down arrow to select the name of the command or namespace.
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 properties (options) and arguments (property=value pairs) from the main CLI prompt using autofill options.
For example, parent namespace child namespace command property=value.
You can enter a namespace, then enter the child namespace, command, then select the command property to enter the argument (property=value) from the namespace prompt.
A command without properties does not show an autofill list.
Press space to see if the command has more properties or wants input, or press Enter to apply the command.
To go up one namespace or command level, enter ...
Enter / to return to the main CLI prompt and to exit the namespace(s).
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 properties (options) and/or arguments (property=value pairs), and might include flags.
Command properties that require a single value automatically add the = delimiter after the property on the autofill list and after reaching the end of the command property inputs.
Some commands allow entering multiple arguments enclosed in curly brackets. These curly brackets could enclose multiple arguments in square brackets separated by a comma and space.
Argument properties (options) and values might require double quotes around each, and are separated by a colon : instead of the equal sign.
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.
Some of the primary namespaces include commands as well as having child namespaces.
Each child namespaces has 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 and provides access to child namespaces and commands including catalog, chart_release, container, docker, and kubernetes.
Auth: Introduces the TrueNAS CLI auth namespace and provides access to child namespaces and commands used to configure user authentication and generate an access token for the web UI.
Directory Service: Introduces the TrueNAS CLI directory_service namespace and provides access to 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 and provides access to child namespaces and commands used to configure network settings.
Service: Introduces the TrueNAS CLI service namespace and provides access to child namespaces and commands including cluster, ctdb, ftp, gluster, ipmi, nfs, smart, smb, snmp, ssh, and vm.
Sharing: Introduces the TrueNAS CLI sharing namespace and provides access to child namespaces and commands including iscsi, nfs, and smb.
Storage: Introduces the TrueNAS CLI storage namespace and provides access to 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 and provides access to 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 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.
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 a description for the user, 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 a description for the user, such as a first and last name. Ex. full_name="Test User" Where Test User is the full name or description for the user.
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!
This command has not been fully tested and validated.
Full documentation 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.
TrueNAS SCALE plans to permanently disable root account access in a future release.
Provisioning_URI Command
The provisioning_uri command displays the provisioning URI for the Two-Factor Authentication One-Time Password (OTP).
The provisioning_uri command only returns part of the provisioning URI.
Description
The provisioning_uri command requires the username property.
Enter the command, then press Enter.
The command returns the OTP provisioning URI for authenticator app QR encoding.
Usage
From the CLI prompt, enter:
account user provisioning_uri username=username
Where:
username is the user you want to see the provisioning URI for.
account user provisioning_uri username=admin
otpauth://totp/mysystems:truenas%50TrueNAS?secret=Noni&is...
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!
This command has not been fully tested and validated.
Full documentation 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
query can also return information about a specific user.
Renew_2FA_Secret Command
The renew_2fa_secret command generates a new secret for 2FA.
Description
The renew_2fa_secret command requires the username property.
Enter the command, then press Enter.
The command returns a table of user settings when successful, and displays an error if run when 2FA is not enabled.
Usage
From the CLI prompt, enter:
account user renew_2fa_secret username=username
Where:
username is the user you want to renew the 2FA secret for.
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.
TrueNAS SCALE plans to permanently disable root account access in a future release.
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.
account user setup_local_administrator username:admin password:passw0rt
Press Enter
From the account prompt, enter:
user setup_local_administrator username:admin password:passw0rt
Press Enter
Where passw0rt is the desired admin account password.
setup_local_administrator accepts only “admin” or “root” for username.
It is recommended to use “admin.” Root user access is a deprecated method.
account user setup_local_administrator username:admin password:passw0rt
Shell_Choices Command
The shell_choices command returns the shell choices available to user accounts.
Description
Enter the command with no additional properties to return shell choices available to all users.
Additional shell choices are available to users with administrative privileges (members of the builtin_administrators group).
Use group_ids to retrieve all options available to members of that group.
Enter all properties and corresponding values to update.
Press Enter
From the account prompt, enter:
user update uid_or_username=3001
Enter all properties and corresponding values to update.
Press Enter
Where 3001 represents the UID or user name of the target account.
account user update uid_or_username=3001 email="mail@email.com"
The command as written updates the email address for the account with UID 3001 to mail@email.com.
Verify_Twofactor_Token Command
The verify_twofactor_token command verifies whether or not a user password is authenticated.
Description
The verify_twofactor_token command requires the username and token properties.
The property argument is separated by the = delimiter.
Enter the command, then press Enter.
The command returns boolean true if provided username and token are successfully authenticated.
Usage
From the CLI prompt, enter:
account user verify_twofactor_token username=username token=password
Where:
username is the user you want to verify.
password is the user password.
account user verify_twofactor_token username=admin token=abcd1234
true
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!
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 functions.
Group Commands
The following group namespace commands allow you to manage group settings.
You can enter commands from the main CLI prompt or from the account 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 below.
Enter the command string with the property argument(s) using the `=’ delimiter to separate the properties and values, then press Enter.
The command returns a blank line.
To create a group that also sets Samba authentication and adds group members, enter:
account group create name=TestGroup gid=3022 smb=false users=[3000,3001]
Where:
3022 is the group id number.
TestGroup is a group name.
false does not set Samba authentication. Enter true to include Samba authentication.
3000,3001 are user id numbers to add as group members.
account group create name=TestGroup
Delete Command
The delete command erases an existing group.
Description
The delete command has one required property, id.
Enter property arguments using the = delimiter to separate the property and value.
Enter the command string, then press Enter.
The command returns a blank line.
If using the options property with the delete_group property argument set to true, the command also deletes any user with the target as its primary group. delete_group defaults to false.
Carefully consider affected users before adding this option.
Or to enter the command using the option property and the delete_group property argument, enter:
account group delete id=3000 options={“delete_group”:true}
Where:
3000 is a group ID.
delete_group is a property you can include in the options property array.
true sets the delete_group option to delete users with the specified group. If set to false the users are not deleted.
account group delete id=3000
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 get_group_obj command has one required property, get_group_obj that expects you to enter property arguments formatted as an array.
Enter the command string, using = followed by the curly brackets that enclose the property argument.
You can enter either the gid or groupname property in this command string.
Enter the property enclosed in double quotes, then the : delimiter followed by the value enclosed in double quotes, with no space after the colon. PressEnter.
The command returns a table for the GID that includes the gr_name, gr_gid, and gr_mem values.
Usage
From the CLI prompt, enter:
account group get_group_obj get_group_obj={“groupname”:"TestGroup"}
Where TestGroup is the name of the target group.
Or, enter the command using the group ID:
account group get_group_obj get_group_obj={“gid”:3002}
Where 3002 is the GID number for the target group.
The get_instance command retrieves information about a group.
The TrueNAS CLI guide for SCALE is a work in progress!
This command has not been fully tested and validated.
Full documentation is still being developed.
Check back for updated information.
Description
The get_instance command has one required property, id.
Enter property arguments with the = delimiter separating property and value.
Enter the command string, then then press Enter.
The command returns a table of information about the UID entered.
Usage
From the CLI prompt, enter:
account group get_instance id=1
Where 1 is the database id for the group, in this case root.
The get_next_gid command displays the next available group identification (GID) number.
Description
The get_next_gid command does not require entering properties or values.
Enter the command, then press Enter
The command 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
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
The has_password_enabled_user command has one required property, gids.
The exclude_user_ids property sets specified password enabled users to ignore.
Target groups are specified by group identification number (GID).
Enter property arguments using the = delimiter to separate property and value.
Enter the command string, then press Enter.
Returns a single true if any targeted groups have at least one user with a password enabled, false if all groups have no users with passwords enabled.
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
Where 3001 represents the GID(s) to query.
account group has_password_enabled_user gids=3001
false
Or if specifying multiple gids:
account group has_password_enabled_user gids=3001,3002
true
Query Command
The query command retrieves information about a group or groups or the query-options-get_instance value specified.
The TrueNAS CLI guide for SCALE is a work in progress!
This command has not been fully tested and validated.
Full documentation is still being developed.
Check back for updated information.
Description
The query command has no required properties or arguments, but you can use various query-filters and query-options specified in an array.
Enter the command, then press Enter.
Returns a table of all groups in the system.
The update command updates the attributes of an existing group.
Descripton
The update command uses the same properties as the create command.
The required property is uid_or_username.
Enter property arguments with the = delimiter separating property and values, then press Enter.
The command returns a blank line.
Introduces the TrueNAS CLI app namespace and provides access to child namespaces and commands including catalog, chart_release, container, docker, and kubernetes.
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.
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 and provides access to child namespaces and commands used to configure user authentication and generate an access token for the 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!
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.
Description
The check_user command has two required properties, username and password to include in the command string.
username is the name of the user and password is the authentication for the user.
Command returns true if the values entered for username and password are correct.
Usage
From the CLI prompt, enter:
auth check_user username=name password=password
Where:
name is the name assigned to the user to log into the UI with.
The check_password and check_user commands verify the logged-in user credentials.
Description
The check_password command has two required properties, username and password to include in the command string.
username is the name of the user and password is the authentication for the user.
Command returns true if the values entered for username and password are correct.
The generate_token command generates an authentication token to use for access. This token determines when the current session expires.
Description
The generate_token command has three required properties, ttl, attrs, and match_origin to include in the command string.
Enter the command string, then press Enter.
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.
Description
The me command does not require entering entering properties or arguments.
Enter the command, then press Enter.
Usage
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.
Description
The two_factor_auth command has two required properties, username and password.
Enter property arguments using the = delimiter to separate property and value.
Enter the command string, then press Enter.
The command returns true if two-factor authentication is enabled, false if not enabled.
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!
API_Key Namespace
The api_key namespace has five commands and is based on API key management functions found in the SCALE API and web UI.
It provides access to API key creation and management methods through the api_key commands.
API_Key Commands
The following api_key commands allow you to create, view, and delete API keys.
You can enter commands from the main CLI prompt or from the auth namespace prompt.
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!
Interactive Argument Editor (TUI)
Enter the -- flag following any CLI command to open the interactive arguments editor text-based user interface (TUI).
Create Command
The create command lets you create simple or complex API keys.
Description
The create command has one required property, name, and one optional property allowlist.
See Create Command Properties below for more information on these properties.
Enter the command string then press Enter.
The command returns the API key when successful.
Always back up and secure keys. The key string displays only one time, at creation!
Property
Required
Description
Syntax Example
name
Yes
Enter a user-readable name for the API key using alphanumeric characters with or without the underscore _. Enter the property argument using the = to separate property and value.
name=mykey
allowlist
No
Use to enter the HTTP method and WebSocket API authorized to use the API key. Enter the required resource permitted to use this key. Append /api/docs/ to the end of your TrueNAS web UI address to see our full list of WebSocket API resources. Enter the HTTP method as a string using any of these values:
GETto retrieve information about the API resource.
POST to create an API resource.
PUT to update an API resource.
DELETE to delete the API resource.
CALL,or
SUBSCRIBE
Enclosed property arguments within curly brackets {} inside square brackets []. Enter property arguments using the = to separate double-quoted property and values. Separate each propery argument with a comma and space.
Where name is the name you want to assign to the key.
auth api_key create name=apikey3
API Key: 3-xTqwhyf3SrUgUlotMQEEGuUr6oRvqg89SBDfXob6xtWSgLbRiDBr6SVRWxswSXx3
Description
Enter the create command name property argument followed by the allowlist property argument.
You can also specify an HTTP method and a WebSocket API method.
Enter the command string then press Enter.
The command returns the API key when successful.
Always back up and secure keys. The key string displays only one time, at creation!
METHOD is the HTTP method you want the key to use. Options are GET, POST, PUT, DELETE, CALL, and SUBSCRIBE.
api.resource is the WebSocket API resource you want to use. Append “/api/docs/” to the end of your TrueNAS web UI address to see our full list of WebSocket API resources.
auth api_key create name=apikey3 allowlist=[{"method":"SUBSCRIBE","resource":"certificate.query"}]
API Key: 3-xTqwhyf3SrUgUlotMQEEGuUr6oRvqg89SBDfXob6xtWSgLbRiDBr6SVRWxswSXx3
Delete Command
The delete command deletes an API key.
Description
The delete command has one required property, id.
Enter the property argument using the = delimiter to separate the property and value.
Enter the command then press Enter.
The command returns nothing when successful.
Usage
From the CLI prompt, enter:
auth api_key delete id=number
Where number is the list number of the API key you want to delete. Use the query command to retrieve id numbers for all API keys on the system.
auth api_key delete id=1
Get_Instance Command
The get_instance command returns a table of properties for the specified API key.
Description
The get_instance command has one required property, id.
Enter the property argument using the = delimiter to separate the property and value.
Enter the command then press Enter.
The command returns a table of properties for the specified API key when successful.
Usage
From the CLI prompt, enter:
auth api_key get_instance id=number
Where number is the list number of the API key you want to delete. Use the query command to retrieve id numbers for all API keys on the system.
The query command returns a table of properties for all API keys.
Description
The query command does not require entering property arguments.
Enter the command then press Enter.
The command returns a table of properties for all API keys when successful.
The update command allows you to update existing API keys.
Description
The update command has one required property, id, and three configurable properties.
See Update Command Properties below for details.
After specifying the id of the API key you want to update, you must include at least one of the properties.
Enter -- after entering the id property argument to open the interactive argument editor.
Enter the command string then press Enter.
The command returns a table of properties for all API keys when successful.
number is the list number of the API key you want to update. For example, the first API key created on the system would be 1.
name is the new name you want to assign to the key.
METHOD is the HTTP method you want the key to use. Options are GET, POST, PUT, DELETE, CALL, and SUBSCRIBE.
api.resource is the WebSocket API resource you want to use. Append “/api/docs/” to the end of your TrueNAS web UI address to see our full list of WebSocket API resources.
true/false determines if you want to remove the existing API key and generate a new random key.
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!
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 two commands is based on functions found in the SCALE API and web UI.
It provides access to two-factor authentication (2FA) configuration methods through the two 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 with the current two-factor settings.
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 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}
4 - Directory Service
Introduces the TrueNAS CLI directory_service namespace and provides access to child namespaces and commands including activedirectory, idmap, kerberos, and ldap.
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.
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.
Description
The cache_refresh command displays the status of the cache-refresh process in percentage complete.
This command does not require entering properties or arguments.
Enter the command, then press Enter.
The cache_refresh command returns the status of the refresh in percentage complete.
The get_state command displays the current status of the directory service.
Description
The get_state command returns the state of the Active Directory and LDAP directory services.
The command does not require entering properties or arguments.
Enter the command, then press Enter.
The command returns a table with the state of both the Active Directory and LDAP services as one of the five possible states in the table below.
Possible states:
State
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 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 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.
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!
This command has not been fully tested and validated.
Full documentation 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!
This command has not been fully tested and validated.
Full documentation 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!
This command has not been fully tested and validated.
Full documentation is still being developed.
Check back for updated information.
Introduces the TrueNAS CLI network namespace and provides access to child namespaces and commands used to configure network settings.
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.
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!
IPMI Namespace
The ipmi namespace has four commands and is based on user functions found in the SCALE API and web UI.
It provides access to IPMI (Intelligent Platform Management Interface) configuration and management options.
IPMI Commands
The following ipmi namespace commands allow you to configure and manage IPMI access.
You can enter commands from the main CLI prompt or from the network namespace prompt.
Channels Command
The channels command returns a list of available IPMI channels.
Description
The channels command does not require entering properties or arguments.
Enter the command, then press Enter.
The command returns the number of IPMI channels the system has available.
Usage
From the CLI prompt, enter:
network ipmi channels
network ipmi channels
1
Get_Instance Command
The get_instance command returns the settings for a user-specified IPMI channel.
Description
The get_instance command requires the id property, which is a single integer you can find using the query command.
Enter the command string, then press Enter.
The command returns a table with the specified IPMI channel settings, including the IP address type, IP address, MAC address, subnet mask, gateway IP address, gateway MAC address, backup gateway IP, address, backup gateway MAC address, VLAN ID, VLAN ID status, and VLAN ID priority.
Usage
From the CLI prompt, enter:
network ipmi get_instance id=number
Where number is the IPMI channel ID you want to return settings for.
The query command returns a table of all IPMI channels and their settings.
Description
The query command does not require entering properties or arguments.
Enter the command, then press Enter.
The command returns a table of all IPMI instances and their settings, including IP addresses type, IP addresses, MAC addresses, subnet masks, gateway IP addresses, gateway MAC addresses, backup gateway IP addresses, backup gateway MAC addresses, VLAN IDs, VLAN ID statuses, and VLAN ID priorities.
The update command allows you to update the settings for a specified IPMI instance.
Description
The update command has six configuration properties. They are ipaddress, netmask, gateway, password, dhcp, and vlan explained in detail in Update Properties below.
You must enter a channel and at least one property for the command to succeed.
Enter the command string, then press Enter.
The command returns a blank line.
Property
Description
Syntax Example
ipaddress
IPv4 address to assign to the channel.
ipaddress="ipaddress"
netmask
Subnet mask associated with the IP address.
netmask="expandednetmask"/i>"
gateway
IPv4 address used by the ipaddress to reach outside the local subnet.
gateway="gateway"
password
Password to assign to the channel. The password must be between 8 and 16 characters and contain at least 3 of the following categories: lowercase character, uppercase character, digits 0-9, special characters (!, $, #, %, etc.)
password=password
dhcp
If false, you must define ipaddress, netmask, and gateway.
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 and provides access to child namespaces and commands including cluster, ctdb, ftp, gluster, ipmi, nfs, smart, smb, snmp, ssh, and vm.
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!
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.
Description
The get_instance command requires you to include the id property in the command string.
Enter the command, then press Enter.
After entering the command correctly, it returns a table with multiple outputs.
Usage
From the CLI prompt, enter:
service 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.
Description
The query command does not require entering properties or arguments.
Enter the command, then press Enter.
After entering the command, it returns a table with multiple outputs.
The reload command requires you to include the service property in the command string.
Enter the command string, then press Enter.
After entering the command correctly, it returns either a true or false output.
True indicates the service reloaded. False indicates the service did not reload.
Usage
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.
reload service=ssh
true
Restart Command
The restart command restarts a specified service.
Description
The restart command requires you to include the service property in the command string.
Enter the command string, then press Enter.
After entering the command correctly, it returns either a true or false output.
True indicates the service restarted successfully. False indicates the service did not restart.
Usage
From the CLI prompt, enter:
service restart service=name
Where name is the service name. For example, enter ssh for the ssh service.
restart service=ssh
true
Start Command
The start command restarts a specified service.
Description
The start command requires you to include the service property in the command string.
Enter the command string, then press Enter.
After entering the command correctly, it returns either a true or false output.
True indicates the service started successfully. False indicates the service did not start.
Usage
From the CLI prompt, enter:
service start service=name
Where name is the service name. For example, enter ssh for the ssh service.
start service=ssh
true
Started Command
The started command verifies whether a start command succeeded for a specified service.
Description
The started command requires you to include the service option in the command string.
Enter the command string, then press Enter.
After entering the command correctly, it returns either a true or false output.
True indicates the service started successfully. False indicates the service did not start.
Usage
From the CLI prompt, enter:
service 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 a service starts automatically upon reboot or is running.
Description
The started_or_enabled command requires you to include the service option in the command string.
Enter the command string, then press Enter.
After entering the command correctly, it returns either a true or false output.
True indicates the service restarts automatically and/or is running. False indicates the service is not running and does start automatically.
Usage
From the CLI prompt, enter:
service 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 stop command stops a specified service.
Description
The stop command requires you to include the service option in the command string.
Enter the command string, then press Enter.
After entering the command correctly, it returns either a true or false output.
True indicates the service started or is running. False indicates the service stopped or is not running.
Usage
From the CLI prompt, enter:
service 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.
Description
The terminate_process command requires you to include the pid proptery in the command string.
You can also include the timeout property (not required) to specify the amount of time (in seconds) the system should attempt to terminate the service.
Enter the command string, then press Enter.
After entering the command correctly, it returns either a true or false output.
The command only returns true to show that the service stopped or is not running.
Usage
From the CLI prompt, enter:
service terminate_process pid=number timout=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 updates the service specified and lets you decide whether or not you want a service to start automatically upon system reboot.
Description
The update command requires you to include the id_or_name and enable property in the command string.
Enter the command string, then press Enter.
The command returns an empty line.
Usage
From the CLI prompt, enter:
service 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 the start automatically feature if the value is true or disables start automatically if the value is false.
update id_or_name=ssh enable=true
Service Namespaces
The following articles provide information on service child namespaces:
Cluster: Provides information about the service cluster namespace in the TrueNAS CLI. Includes command syntax and common commands.
CTDB: Provides information about the service ctdb namespace in the TrueNAS CLI. Includes command syntax and common commands.
FTP: Provides information about the service ftp namespace in the TrueNAS CLI. Includes command syntax and common commands.
Gluster: Provides information about the service gluster namespace in the TrueNAS CLI. Includes command syntax and common commands.
IPMI: Provides information about the service ipmi namespace in the TrueNAS CLI. Includes command syntax and common commands.
NFS: Provides information about the service nfs namespace in the TrueNAS CLI. Includes command syntax and common commands.
SMB: Provides information about the service smb namespace in the TrueNAS CLI. Includes command syntax and common commands.
SNMP: Provides information about the service snmp namespace in the TrueNAS CLI. Includes command syntax and common commands.
SSH: Provides information about the service ssh namespace in the TrueNAS CLI. Includes command syntax and common commands.
UPS: Provides information about the service ups namespace in the TrueNAS CLI. Includes command syntax and common commands.
VM: Provides information about the service vm namespace in the TrueNAS CLI. Includes command syntax and common commands.
SMART: Provides information about the service smart namespace in the TrueNAS CLI. Includes command syntax and common commands.
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 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 ipmi namespace in the TrueNAS CLI. Includes command syntax and common commands.
IPMI Namespace
The ipmi namespace has four commands and is based on IPMI management functions found in the SCALE API and web UI.
It provides access to ipmi service management methods through the ipmi commands.
IPMI Commands
The following ipmi commands allow you to view and edit ipmi service properties.
You can enter commands from the main CLI prompt or from the ipmi namespace prompt.
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!
Interactive Argument Editor (TUI)
Enter the -- flag following any CLI command to open the interactive arguments editor text-based user interface (TUI).
Chassis Command
The chassis command allows you to toggle IPMI identify light and view IPMI service settings.
Description
The chassis command has one required property, identify, and one optional property, info, described in Viewing IPMI Service Settings below.
identify has one property, verb, used to toggle the IPMI light on and off.
verb has two values, ON or OFF.
Enter identify, then enter the verb property argument using = to separate property and value.
Enter the command string then press Enter.
The command returns a blank line when successful.
Usage
From the CLI prompt, enter:
service ipmi chassis identify verb=ON/OFF
Where ON and OFF toggle the IPMI light on and off.
service ipmi chassis identify verb=ON
Description
Use the chassis command info property to view IPMI service settings.
The info default value is {}.
Enter the command string with the default value then press Enter.
The command returns a table of settings when successful.
The mc command allows you to view information on your management controller (MC).
Description
The mc command requires the info property.
info has no property arguments.
Enter the command string then press Enter.
The command returns a table of MC information when successful.
The sel command manages the IPMI System Event Log (SEL).
Description
The sel command has three optional properties, clear, elist, and info, but can only use one at a time.
See SEL Properties below for details.
Enter the command string then press Enter.
The command returns completion percentages and a table of SEL information when successful.
Property
Description
clear
Clears the SEL. Clears the IMPI system event log.
elist
Queries the SEL extended list. Queries the IPMI system event log extended list.
info
Queries general information about the SEL. Returns general information about the IPMI system event log.
Usage
From the CLI prompt, enter:
service ipmi sel property
Where property is the SEL property you want to run.
The sensors command allows you to view IPMI sensor data.
Description
The sensors command has required property, query.
query does not require a property argument.
Enter the command string then press Enter.
The command returns a table of SEL information when successful.
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.
SSH Namespace
The ssh namespace has three commands and is based on SSH service functions found in the SCALE API and web UI.
It provides access to SSH service management methods through the ssh commands.
SSH Commands
The following ssh commands allow you to view and edit ssh properties.
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!
Interactive Argument Editor (TUI)
Enter the -- flag following any CLI command to open the interactive arguments editor text-based user interface (TUI).
Bindiface_Choices Command
The bindiface_choices command returns a table of available interface for SSH to listen on.
Description
The bindiface_choices command has no required properties.
Enter the command then press Enter.
The command returns a table of available interfaces when successful.
The config command returns a table with current SSH settings.
Description
The config command has no required properties.
Enter the command then press Enter.
The command returns a table of current SSH service settings when successful.
The update command allows you to update SSH service settings.
Description
The update command has 12 optional properties; bindiface, tcpport, rootlogin, adminlogin, passwordauth, kerberosauth, tcpfwd, compression, sftp_log_level, sftp_log_facility, weak_ciphers, and options.
See Update Command Properties below for details.
After entering update, you must include at least one property to update. Separate additional properties with a space.
Enter the command string then press Enter.
The command returns a blank line when successful.
Property
Description
Syntax Example
bindiface
The interfaces for SSH to listen on. Leave empty for SSH to listen on all interfaces.
bindiface=[interface, interface]
tcpport
The port you want to use for SSH connection requests.
tcpport=number
rootlogin
Allows root logins.
rootlogin=true/false
adminlogin
Allows admin logins.
adminlogin=true/false
passwordauth
Allows using a password to authenticate the SSH login.
passwordauth=true/false
kerberosauth
Allows Kerberos authentication using valid directory services entries.
kerberosauth=true/false
tcpfwd
Allows users to bypass firewall restrictions using the SSH port forwarding feature.
tcpfwd=true/false
compression
When enabled, the system attempts to reduce latency over slow networks.
Provides information about the service ups namespace in the TrueNAS CLI. Includes command syntax and common commands.
UPS Namespace
The ups namespace has three commands and is based on UPS service functions found in the SCALE API and web UI.
It provides access to UPS management methods through the ups commands.
UPS Commands
The following ups commands allow you to view and edit UPS properties.
You can enter commands from the main CLI prompt or from the UPS namespace prompt.
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!
Interactive Argument Editor (TUI)
Enter the -- flag following any CLI command to open the interactive arguments editor text-based user interface (TUI).
Config Command
The config command returns a table with current UPS settings.
Description
The config command has no required properties.
Enter the command then press Enter.
The command returns a table of current UPS settings when successful.
The driver_choices command returns choices of UPS drivers supported by the system.
Description
The driver_choices command has no required properties.
Enter the command then press Enter.
The command returns a table of UPS drivers your system supports when successful.
Usage
From the CLI prompt, enter:
service ups driver_choices
service ups driver_choices
+-----------------------------------+------------------------------------------------------------------+
| blazer_usb$625L | Ablerex ups 2 625L USB (blazer_usb) |
| snmp-ups$various RPC | Baytech pdu 3 various RPC (snmp-ups) |
| genericups upstype=7$550SL | Cyber Power Systems ups 1 550SL (genericups) |
| mge-shut$Tower 500W LV / HV | Dell ups 5 Tower 500W LV / HV Serial port (mge-shut) |
| usbhid-ups$3S | Eaton ups 5 3S (usbhid-ups) |
| blazer_ser$PowerPal | Fenton Technologies ups 5 PowerPal L-series (blazer_ser) |
| gamatronic$µPS3/1 | Gamatronic ups 5 µPS3/1 (gamatronic) |
| apcsmart$PowerTrust 2997A | HP ups 1 PowerTrust 2997A HP 5061-2575 cable (apcsmart) |
| usbhid-ups$Various | IBM ups 5 Various USB port (usbhid-ups) |
| genericups upstype=4$Jasuny USPS | Jageson Technology ups 1 Jasuny USPS (genericups) |
| nutdrv_atcl_usb$800 VA | Kanji ups 1 800 VA USB (nutdrv_atcl_usb) / Plexus ups 1 800 V... |
| metasys$WHAD 2500 | Legrand ups 4 WHAD 2500 Serial (metasys) |
| masterguard$(various) | Masterguard ups 1 (various) (masterguard) |
| gamatronic$Expert C Online 6000 | NHS Sistemas de Energia ups 5 Expert C Online 6000 (gamatronic) |
| oneac$ON400 | Oneac ups 1 ON400 advanced interface (oneac) |
| usbhid-ups$Black Knight PRO | Powercom ups 5 Black Knight PRO USB (2009 models, product id:... |
| snmp-ups$Metered PDU - Raritan PM | Raritan pdu 3 Metered PDU - Raritan PM no report, but should ... |
| blazer_ser$Castle C*K | Santak ups 2 Castle C*K Serial (blazer_ser) |
| usbhid-ups$AVRX750UD | Tripp Lite ups 3 AVRX750UD USB (protocol 2010) (usbhid-ups) |
| blazer_ser$Alpha 1000is | UNITEK ups 2 Alpha 1000is (blazer_ser) |
| nutdrv_qx$Vesta LED 850VA | Voltronic Power ups 2 Vesta LED 850VA USB (nutdrv_qx) |
| blazer_ser$CPM-800 | WinPower ups 2 CPM-800 (blazer_ser) |
+-----------------------------------+------------------------------------------------------------------+
Port_Choices Command
The port_choices command returns choices of UPS ports available on the system.
Description
The port_choices command has no required properties.
Enter the command then press Enter.
The command returns a list of UPS port choices when successful.
Usage
From the CLI prompt, enter:
service ups port_choices
service ups port_choices
/dev/ttyS1
/dev/ttyS0
/dev/uhid
auto
Update Command
The update command allows you to update UPS service settings.
Description
The update command requires entering a port and a driver. It also has 17 additional properties you can configure.
See the Update Command Properties table below for details.
After specifying the port and a driver, you can include any other properties you want to update.
Enter the command string, then press Enter.
The command returns nothing when successful.
Property
Required
Description
Syntax Example
powerdown
No
When enabled, the UPS powers off after the system shuts down.
powerdown="true/false"
rmonitor
No
Sets the default configuration to listen on all interfaces using the known values of user: upsmon and password: fixmepass.
rmonitor="true/false"
nocommwarntime
No
Number in seconds to wait before alerting that the service cannot reach any UPS. Warnings continue until the situation is fixed.
nocommwarntime=number
remoteport
No
Only enabled when the UPS Mode is set to SLAVE. Enter the open network port number of the UPS Master system. The default port is 3493.
remoteport=number
shutdowntimer
No
Value in seconds the service waits for the UPS before initiating a shutdown. This only applies when shutdown is set to BATT.
shutdowntimer=number
hostsync
No
Value in seconds Upsmon waits in master mode for the slaves to disconnect during a shutdown situation.
hostsync=number
description
No
User-defined description for the service.
description=“description”
driver
Yes
Network UPS Tools compatible driver.
driver="driver"
extrausers
No
User ID you want to have administrative access.
extrausers=UID
identifier
No
User-defined identifier. It can contain alphanumeric, period, comma, hyphen, and underscore characters.
identifier=identifier
mode
No
Choose MASTER if the UPS is plugged into the serial port. The UPS shuts down last. Choose SLAVE to have this system shut down before master.
mode=MODE
monpwd
No
Changes the default password to improve system security. The new password cannot contain a space or #.
monpwd=password
monuser
No
Enter a user ID to associate with this service. We recommend the default.
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 smart namespace in the TrueNAS CLI. Includes command syntax and common commands.
SMART Namespace
The smart namespace has two commands and is based on S.M.A.R.T. service functions found in the SCALE API and web UI.
It provides access to S.M.A.R.T. service management methods through the smart commands.
SMART Commands
The following smart commands allow you to view and edit smart properties.
You can enter commands from the main CLI prompt or from the smart namespace prompt.
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!
Interactive Argument Editor (TUI)
Enter the -- flag following any CLI command to open the interactive arguments editor text-based user interface (TUI).
Config Command
The config command returns a table with current UPS settings.
Description
The config command has no required properties.
Enter the command then press Enter.
The command returns a table of current S.M.A.R.T. service settings when successful.
The update command allows you to update S.M.A.R.T. service settings.
Description
The update command has five optional properties; interval, powermode, difference, informational, and critical.
See Update Command Properties below for details.
After entering update, you must include at least one property to update. Separate additional properties with a space.
Enter the command string then press Enter.
The command returns a blank line when successful.
Property
Description
Syntax Example
interval
Defines the value in minutes for smartd to wake up and check if any tests are configured to run.
interval=number
powermode
S.M.A.R.T. power mode to apply.
NEVER where the device is fully powered up and ready to send/receive data. The disk only undergoes S.M.A.R.T. tests when powermode is set to NEVER. Default value is NEVER.
IDLE where the disk completes commands slower than when set to NEVER but uses less power.
STANDBY where the disk completes commands slower than when set to IDLE but uses less power.
SLEEP where the disk does not complete commands until reset. Uses the least amount of power.
powermode=:MODE
difference
Enter the threshold temperature in Celsius. Report if the temperature of a drive has changed by this many degrees Celsius since the last report. 0 disables the report. Enter the property argument using the = to separate the property and double-quoted value.
difference=number
informational
Enter the threshold temperature in Celsius. Report if the drive temperature is at or above this temperature in Celsius. 0 disables the report. Enter the property argument using the = to separate the property and double-quoted value.
informational=number
critical
Enter the threshold temperature in Celsius. If the drive temperature is higher than this value, a LOG_CRIT level log entry is created and an email is sent. 0 disables this check. Enter the property argument using the = to separate the property and double-quoted value.
critical=number
Usage
From the CLI prompt, enter:
service smart update property=value
Where:
property is the property you want to update.
value is the value you want to specify for the property.
service smart update interval=30 powermode=NEVER difference=0 informational=0 critical=0
Introduces the TrueNAS CLI sharing namespace and provides access to child namespaces and commands including iscsi, nfs, and smb.
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.
Sharing Namespace
The sharing namespace has three 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.
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!
NFS Namespace
The nfs namespace has five command(s), and is based on share creation and management functions found in the SCALE API and web UI.
It provides access to NFS share methods through the nfs commands.
NFS Commands
The following nfs commands allow you to create new shares, manage existing shares, get information on NFS shares on the system
You can enter commands from the main CLI prompt or from the sharing namespace prompt.
Interactive Argument Editor (TUI)
Enter the -- flag following any CLI command to open the interactive arguments editor text-based user interface (TUI).
Create Command
The create command adds a new NFS share.
It is best practice to use a dataset instead of a full pool for SMB and/or NFS shares.
Sharing an entire pool makes it more difficult to later restrict access if needed.
Description
The create has one required property, path.
The Create Command Optional Properties section below lists the 12 optional properties.
Enter a property argument using the = delimiter to separate property and value. Enter a string value enclosed in double quotes.
Enter the command string, then press Enter.
create returns an empty line.
Use the query command to verify the share was created and to view details of the share.
These optional properties are also used with the update command.
Command
Description
Syntax Example
aliases
This option is a Work in Progress.
comment
Enter a description for the share. Enclose the string in double quotes.
comment="For read only access"
networks
Specify a list of network IP addresses with CIDR notation allowed to access this share. Leave empty to allow all. Enter the network values enclosed in square brackets []. Enclose each IP address/CIDR value in double quotes and separate multiple network values with a comma and space.
networks=["1.2.3.0/24", “1.2.2.2/21”]
hosts
Specify a list of network IP addresses with CIDR notation or hostnames allowed to access this share. Leave empty to allow all. Enter the network values enclosed in square brackets []. Enclose each IP address/CIDR or hostname value in double quotes and separate multiple network values with a comma and space.
networks=["1.2.3.0/24", “truenas.com”]
ro
Set to true to prohibit writing to the share or false to allow writing to the share.
ro=true or ro=false
quiet
Do not use.
maproot_user
Enter a username to limit the root user to the permissions of that user.
maproot_user=admin
maproot_group
Enter a group name to limit the root user to the permissions of that group.
mapgroup=admin
mapall_user
Enter a username set all clients to use the specified permissions of that user.
mapall_user=admin
mapall_group
Enter a group name set all clients to use the specified permissions of that group.
mapall_group=admin
security
Sets the security for the share to one of four options:
SYS to set the share to use locally acquired UID and GID permissions.
KRB5 to set the share to use Kerberos V5 user authentication.
KRB5i to set the share to use Kerberos V5i for user authentication and perform integrity checking of NFS operations using secure checksums to prevent data tampering.
KRB5P to set the share to use Kerberos V5 user authentication and integrity checking that encrypts NFS traffic to prevent traffic sniffing.
security=SYS
enabled
Set to true to enable this share or false to disable the share without deleting it.
enable=true or enable=false
Usage
From the CLI prompt, enter:
sharing nfs create path="/mnt/tank/shares/nfs2"
Where mnt/tank/shares/nfs2 is the path to the dataset created for the share.
If using optional property arguments, for example, to set networks and read only access, enter:
mnt/tank/shares/nfs2 is the path to the dataset created for the share.
10.123.12.1/24 10.123.11.2/23 are the space-separated IP addresses with CIDR notation for each network you allow to connect to the share.
true sets the share to read only or false to allow write access to the share.
sharing nfs create path=/mnt/tank/shares/nfs2
Delete Command
The delete command deletes an NFS share.
Description
The delete command has one required property, id.
Enter a property argument using the = delimiter to separate property and value and enclose the value in double quotes.
Enter the command string, then press Enter.
delete returns an empty line.
Usage
From the CLI prompt, enter:
sharing nfs delete id="4"
Where 4 is the ID assigned to the share.
sharing nfs delete id=4
Get_Instance Command
The get_instance command retrieves information for an NFS share matching the id entered in the command string.
Use to verify properties for the configured share.
Description
The get_instance command has one required property, id.
Enter the command, then press Enter.
get_instance returns a table (dictionary) of properties for the ID entered.
The dictionary includes the share ID, path, aliases, comment, networks, hosts entered, the read only, quiet, and locked status as true or false, value for maproot and mapall users and groups, security applied, and the enabled status as true or false.
Use the query command to locate the ID number for the share.
The query command returns a table (dictionary) of all NFS shares on the system.
Use to locate the share ID number and other configuration information.
Description
The query does not require entering property arguments.
Enter the command, then press Enter.
The query returns a table (dictionary) of all NFS shares configured on the system.
Information includes the ID, path, aliases, any comments, networks hosts, read only status, maproot user and group, mapall user and group, security, enabled, and locked status.
The update command returns a table (dictionary) of all NFS shares on the system.
Use to locate the share ID number and other configuration information.
Description
The update has one required property, id.
This command uses the optional share properties listed in Create Command Optional Properties found in the Create Command section.
Follow the syntax examples provided for each property.
Enter the command string, then press Enter.
update returns an empty line.
Usage
To add or change a comment for a share, from the CLI prompt, enter:
sharing nfs update id=4 comment="test share"
Where
4 is the ID number assigned to the share to update.
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!
Introduces the TrueNAS CLI storage namespace and provides access to child namespaces and commands including dataset, disk, enclosure, filesystem, pool, resilver, scrub, snapshot, and vmware.
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.
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!
Snapshot Namespace
The dataset namespace has one namespace, user_prop and 22 commands, and is based on dataset creation and management functions found in the SCALE API and web UI.
It provides access to storage dataset methods through the dataset commands.
Do not use the user_prop commands.
Dataset Commands
The following dataset commands allow you to create new and manage existing datasets.
You can enter commands from the main CLI prompt or from the dataset namespace prompt.
Interactive Argument Editor (TUI)
Enter the -- flag following any CLI command to open the interactive arguments editor text-based user interface (TUI).
Attachments
The attachments command lists services dependent on the dataset matching the ID entered.
Use the storage dataset query or storage dataset details command to obtain dataset IDs.
Description
The attachments command has one required property, id.
id is the ID found in the output of the storage dataset query command.
Enter the property argument using the = delimiter to separate property and value.
Enter the command string then press Enter.
The command returns a table with type, service, and attachments for the specified dataset ID.
Usage
From the CLI prompt, enter:
storage dataset attachments id=tank
Where tank is the ID assigned to the dataset by the system.
Use the change_key command to change the encryption key properties for the dataset matching the ID entered.
The TrueNAS CLI guide for SCALE is a work in progress!
This command has not been fully tested and validated.
Full documentation is still being developed.
Check back for updated information.
Checksum_Choices Command
The checksum_choices command lists checksums supported for the ZFS dataset.
Description
The checksum_choices command does not require entering a property argument.
Enter the command then press Enter.
The command returns a table with a list of checksums supported by ZFS.
Checksums are ON, FLETCHER2, FLETCHER4, SHA256, SHA512, SKEIN, and EDNOR.
The compression_choices command lists compression alogrithms supported by ZFS.
Description
The commpression_choices command does not require entering a property argument.
Enter the command then press Enter.
The command returns a table listing compression algorithms supported by ZFS.
Use the Create command to create datasets or zvols.
Description
The create command has one required property and 38 optional properties.
Of these, set share_type and casesensitivity as these cannot be changed after creating a new dataset.
See Create Properties below for details.
The create command is a complex command.
Enter the storage dataset create -- command string to open the interactive argument editor/text user interface (TUI) and make configuring a dataset or zvol easier.
Enter the CLI command string then press Enter.
The command creates a new dataset and returns an empty line.
Enter property arguments using the = delimiter to separate property and value. Double-quote values that include special characters.
Property arguments enclosed in curly backets {} have double-quoted properties and values separated by the : delimiter, and separate multiple property arguments with a comma. For example:
Enter the full name for the dataset as pool/dataset. Enter the value in double-quote.
name="tank/dataset"
type
No
Enter FILESYSTEM to create a dataset or VOLUME to create a zvol. Include the volsize property argument if using VOLUME.
type=FILESYSTEM or type=VOLUME
volsize
Yes*
*Required if setting type=VOLUME. Enter the value which is a multiple of the block size. Options are 512, 512B, 1K, 2K, 4K, 8K, 16K, 32K, 64K, 128K.
volsize=8k
volblocksize
No
Only used when setting type=VOLUME. Enter the block size for the zvol. For example, 10GiB. Use the recommended_zvol_blocksize command to get a blocksize value.
volblocksize=10GiB
sparse
No
Only used when setting type=VOLUME. Enter true to or false
sparse=true or sparse=false
force_size
No
Only used when setting type=VOLUME. The system restricts creating a ZVol that brings a pool to over 80% capacity. Enter true to force creating of a zvol in this case (not recommended). Default is false.
force_size=false or force_size=true
comments
No
Enter comments using upper and lowercase alphanumeric and special characters as a description about this dataset. Enclose value in double quotes.
sync
No
Enter the option for the desired sync setting.
STANDARD to use the standard sync settings requested by the client software.
ALWAYS to wait for data write to complete.
DISABLED to never wait for writes to complete.
comments="my comments"
snapdev
No
Enter the option to set whether the volume snapshot devices under /dev/zvol/poolname are HIDDEN or VISIBLE. Default inherits HIDDEN.
snapdev=HIDDEN or snapdev=VISIBLE
compression
No
Enter the compression level to use from the available ZFS supported options. Use storage dataset compression_choices to list ZFS supported compression algorithms. Enter the value in double quotes.
compression=OFF</>
atime
No
Set the access time for the dataset. Options are:
ON updates the access time for files when they are read.
OFF disables creating log traffic when reading files to maximize performance.
atime=ON or atime=OFF
exec
No
Enter ON to allow executing processes from within the dataset or OFF to prevent executing processes from within the dataset. We recommend setting this to ON.
exec=ON or exec=OFF
managedby
No
Not used. Query command includes a reference the router/switch by default.
N/A
quota
No
Enter a value to define the maximum overall allowed space for the dataset and the dataset descendants. Default 0 disables quotas. Default is Null.
quota_warning
No
Enter a percentage value that when reached or exceeded generates a warning alert or enter Null.
quota_crtical
No
Enter a percentage value that when reached or exceeded generates a critical alert or enter Null.
refquota
No
Enter a value to define the maximum allow space for just the dataset. Default 0 disables quotas. Default is Null.
rfquota_warning
No
Enter a percentage value that when reached or exceeded generates a warning alert or enter Null.
refquota_crtical
No
Enter a percentage value that when reached or exceeded generates a critical alert or enter Null.
reservation
No
Enter a value to reserve additional space for this dataset and the dataset descendants. 0 is unlimited.
refreservation
No
Enter a value to reserve additional space for just this dataset. 0 is unlimited.
special_small_block_size
No
Enter the threshold block size for including small file blocks into the special allocation class fusion pool. Blocks smaller than or equal to this value are assigned to to the special allocation class while greater blocks are assigned to the regular class. Valid values are zero or a power of two from 512B up to 1M. Default is 0 which means no small file blocks are allocated in the special class. Add a special class VDev to the pool before setting this value.
special_small_block_size=0
copies
No
Enter a number for allowed duplicates of ZFS user data stored on this dataset.
copies=2
snapdir
No
Enter the visibility of the .zfs directory on the dataset as HIDDEN or VISIBLE.
snapdir=HIDDEN or snapdir=VISIBLE
deduplication
No
Enter the option to transparently reuse a single copy of duplicated data to save space. Options are:
ON to use deduplication.
VERIFY to do a byte-to-byte comparison when two blocks have the same signature to verify the block contents are identical.
OFF to not use deduplication
Deduplicating data is a one-way process. You cannot undo deduplicated data!
deduplication=OFF
checksum
No
Enter the checksum to use from the options: ON, OFF, FLETCHER2, FLETCHER4, SHA256, SHA512, SKEIN, or EDONR.
checksum=OFF
readonly
No
Enter ONto make the dataset readonly, or OFF to allow write access.
readonly=ON
recordsize
No
Set the logical block size in the dataset matching the fixed size of data, as in a database. This can result in better performance. Use the recordsize_choices command to return a list of options to use with this command.
recordsize=Null
casesensitivity
No
Enter SENSITIVE to assume file names are case sensitive or INSENSITIVE for mixed case or case-insensitivity. You cannot change case sensitivity after saving the dataset. Default is INSENSITIVE.
casesensitivity=INSENSITIVE
aclmode
No
Enter the option that determines how chmod behaves when adjusting file. See zfs(8)aclmod property for more information. Options are:
PASSTHROUGH only updates ACL entries that are related to the file or directory mode.
RESTRICTED does not allow chmod to make changes to files or directories with a non-trivial ACL. A trivial ACL can be fully expressed as a file mode without losing any access rules. Use this to optimize a dataset for SMB sharing.
DISCARD
acl_type determines the acl_mode options available in the UI.
aclmodes=PASSTHROUGH
acltype
No
acltype is inherited from the parent or root dataset. Enter the access control type from these options:
OFF specifies neither NFSV4 or POSIX protocols.
NFSV4 is used to cleanly migrate Windows-style ACLs across Active Directory domains (or stand-alone servers) that use ACL models richer than POSIX. Use to maintain compatibility with TrueNAS CORE, FreeBSD, or other non-Linux ZFS implementations.
POSIX use when an organization data backup target does not support native NFSV4 ACLs. Linux platforms use POSIX and many backup products that access the server outside the SMB protocol cannot understand or preserve native NFSV4 ACLs. Datasets with share_type set to GENERIC or APPS have POSIX ACL types.
acltype=POSIX
share_type
Yes
Enter the option to define the type of data sharing the dataset uses to optimize the dataset for that sharing protocol. Options are:
GENERIC to use for all datasets except those using SMB shares.
SMB for datasets using SMB shares.
APPS for datasets created to use with applications and to optimize the dataset for use by any application.
share_type=GENERIC
xattr
No
Set SA to store extended attributes as System Attributes. This allows storing of tiny xattrs (~100 bytes) with the dnode and storing up to 64k of xattrs in the spill block. This results in fewer IO requests when extended attributes are in use. Set ON to store extended attributes in hidden sub directories but this can require multiple lookups when accessing a file.
xatter=SA
encryption_options
*No
Use to specify the type of encryption, hex-encoded key or passphrase. Enter the property arguments that apply:
generate_keyenter true to have the system generate a hex-encoded key. Default is false to use key to enter a hex-encoded key of your choice.
key_file enter true to use a key file for key encryptiont. Default is false if not using an uploaded key file.
pbkdf2iters enter the number of password-based key deviations function 2 (PBKDF2) iterations to use for reducing vulnerability to brute-fore attacks. Enter a value greater than 100000 or use the default value 350000.
passphrase enter the double-quoted password of your choice. Must be specified to use password encryption. Default value is Null or use any string of alpha-numeric and special characters of your choice.
key enter the hex-encoded key of your choice. Default is Null.
Enter true to encrypt the dataset. Default is false if the parent dataset is not encrypted. You must enter inherit_encryption=false to change encryption for a child of an unencrypted dataset and if changing from key to passphrase encryption.
encryption=true or encryption=false
inherit_encryption
*No
Required if encrypting a dataset that is a child of an unencrypted dataset. Enter true to inherit encryption from the parent dataset or false to encrypt a dataset that is a child of an unencrypted dataset or changing or if changing from key to passphrase encryption. You cannot create an unencrypted child dataset of an encrypted parent dataset.
inherit_encryption=true or inherit_encryption=false
Use the delete command to delete a dataset or zvol matching the ID entered.
Description
The delete command has one required property, id, and one optional property, dataset_delete.
id is the found in the output of the storage dataset query command.
Enter the property argument using the = delimiter to separate property and double-quoted value.
Enter the command string then press Enter.
The command returns an empty line.
Usage
From the CLI prompt, enter:
storage dataset delete id="tank/tank-e3"
Where tank/tank-e3 is identifier for the dataset.
storage dataset delete id="tank/tank-e3"
Destroy_Snapshots Command
Use the destroy_snapshots command to destroy snapshots for the dataset matching the ID entered.
Use the storage snapshot query command to obtain a list of snapshots on the system.
If the system is performing a snapshot task for the dataset specified, the command returns an error stating the dataset is busy.
Description
The destroy_snapshot command has two required properties, name and snapshots.
name is the dataset name found in the output of the storage dataset query command.
snapshots has four optional properties. See Snapshots Properties below for details.
Use the default {} value to destroy all datasets for the dataset matching the ID entered.
Enter the property argument using the = delimiter to separate property and value.
Enter the command string then press Enter.
The command returns progress status in percentage validated and then the name of the snapshot.
Enter snapshots optional property arguments inside the curly brackets {}, where the properties and values are double-quoted and separated by the : delimiter, and with each argument separated with a comma.
Use the default value snapshots={} without specifying any optional property to destroy all snapshots for the specified dataset.
Property
Description
Syntax Example
start
Enter the start date and time for the snapshot range.
“start”:"snapshot_start"
end
Enter the end date and time for the snapshot range.
“start”:"snapshot_send"
snapshot_spec
Enter the start and ending date and time range in an object array.
“start”:"snapshot_start,"snapshot_end"
snapshot_name
Enter the name of the snapshot as found in the output of the storage snapshot query command.
Use the details command to list all datasets on the system and the services or tasks that might be consuming them.
Description
The details command does not require entering a property argument.
Enter the command then press Enter.
The command returns a table with the same information found in the query command output and any services consuming the dataset.
Use the encryption_alogorithm_choices command to list encryption alogrithms supported by ZFS.
Description
The encryption_alogorithm_choices command does not require entering a property argument.
Enter the command then press Enter.
The command returns a list of ZFS-supported encryption alogrithms.
Use the encryption_summary command to retrieve a summary of all encrypted root datasets under the entered ID.
Description
The encryption_summary command has one required property, id.
id is the identifier for the dataset found in the output of the storage dataset query.
Enter the property argument using the = delimiter to separate property and value.
Enter the command string then press Enter.
The command returns progress in percentage complete followed by the encryption root datasets under the identifier entered or (empty list) if none exist.
Use the export_key command to export the encryption key for the dataset matching the ID entered.
Use with storage dataset encryption_summary to identify dataset encryption types for datasets on the system.
Description
The export_key command has one required property, id.
id is the identifier for the dataset found in the output of the storage dataset query.
Enter the property argument using the = delimiter to separate property and value.
Enter the command string then press Enter.
The command returns the encryption key for the dataset matching the id entered.
Usage
From the CLI prompt, enter:
storage dataset export_key id="tank/tank-e"
Where tank/tank-e2 is the identifier for the dataset.
Use the export_keys command to export keys for the ID entered and all children of it stored in the system.
The TrueNAS CLI guide for SCALE is a work in progress!
This command has not been fully tested and validated.
Full documentation is still being developed.
Check back for updated information.
Get_Instance Command
Use the get_instance command to list detials for the dataset matching the ID entered.
Description
The get_instance command has one required property, id.
id is the identifier for the dataset found in the output of the storage dataset query.
Enter the property argument using the = delimiter to separate property and value.
Enter the command string then press Enter.
The command returns the query information for the dataset matching the id entered.
Use the get_quota command to return a list of the specified quota_type of quotas on the ZFS dataset ds.
Description
The get_quota command has two required properties, id and quota_type.
id is the identifier for the dataset found in the output of the storage dataset query.
quota_type has four options: USER, GROUP, DATASET, or PROJECT.
PROJECT displays quotas on each user in the specified filesystem, snapshot, or path, and space consumed by the file system.
If specifying a path, the file system containing that path is used.
This corresponds to the userused@user, userobjused@user, userquota@user, and userobjquota@user properties.
Enter the property arguments using the = delimiter to separate properties and values.
Enter the command string then press Enter.
The command returns quota type details for the dataset matching the id entered.
Details include the quota type, ID, name for the dataset, the quota, refquota, and bytes used values.
If entering quota_type=PROJECT, information returned is the quota type and ID entered, the bytes used, and number of user objects.
storage dataset get_quota ds="tank" quota_type= DATASET
+------------+------+------+-------+----------+-------------+
| quota_type | id | name | quota | refquota | used_bytes |
+------------+------+------+-------+----------+-------------+
| DATASET | tank | tank | 0 | 0 | 26452549632 |
+------------+------+------+-------+----------+-------------+
Inherit_Parent_Encryption_Properties Command
The inherit_parent_encryption_properties command allows inheriting parent dataset encryption root disregarding the current encryption settings.
Use only when the specified dataset ID is an encrypted parent and ID itself is an encryption root (parent to encrypted child datasets).
Description
The inherit_parent_encryption_properties command has one required property, id.
id is the identifier for the dataset found in the output of the storage dataset query.
Enter the property argument using the = delimiter to separate property and value.
Enter the command string then press Enter.
The command returns an empty line.
Use the lock command to lock the dataset matching the ID entered.
Only works with datasets using passphrase encryption. Datasets with key encryption return an error.
The TrueNAS CLI guide for SCALE is a work in progress!
This command has not been fully tested and validated.
Full documentation is still being developed.
Check back for updated information.
Mountpoint Command
Use the mountpoint command to obtain the mountpoint for the dataset matching the ID entered.
Description
The mountpoint command has one required property, id, and one optional property, raise.
id is the identifier for the dataset found in the output of the storage dataset query.
raise default value is true.
Enter the property argument using the = delimiter to separate property and value.
Enter the command string then press Enter.
The command returns the mount path for the dataset identifier entered.
Usage
From the CLI prompt, enter:
storage dataset mountpoint id="tank/minio"
Where tank/minio is the identifier for the dataset.
Use the permission command to set the owner and group, and other dataset permission options (i.e., recursive, traverse, etc.) for the dataset matching the ID entered.
The permissions command is complex. Use either the UI Edit ACL screen or the the interactive arguments editor/text user interface (TUI) to configure ACL permissions.
Description
The permissions command has two required properties, id and pool_dataset_permissions.
See Pool_Dataset_Permissions Properties below for details.
id is the identifier for the dataset found in the output of the storage dataset query.
Enter the property argument using the = delimiter to separate property and value.
Enter the command string then press Enter.
The command returns a table with user and options for the specified dataset identifier.
Permissions are specified as either a POSIX or NFSV4 acl. This method is a wrapper around filesystem.setperm, filesystem.setacl, and filesystem.chown.
Enter the pool_dataset_permissions property arguments inside the curly brackets {}, use the : delimiter to separate double-quoted properties and values, and separate each argument with a comma and a space. For example:
*Must enter user but can enter both user and group. Enter the name if the user (owner) of permissions for the dataset matching the id entered.
{“user”:"admin"}
group
No
Enter the name if the group (owner) of permissions for the dataset matching the id entered.
{“group”:"admin"}
mode
No
Enter the ACL mode from these options: INHERIT, RESTRICTED, or PASSTHROUGH. If specified filesystem.perm is called. If neither mode or acl are specified, filesystem.chown is called.
Use the processes command lists the processes using the dataset matching the ID entered.
Description
The processes command has one required property, id.
id is the identifier for the dataset found in the output of the storage dataset query.
Enter the property argument using the = delimiter to separate property and value.
Enter the command string then press Enter.
The command returns (empty list) if no processes are using the dataset matching the id entered.
Use the promote command to promote a the cloned dataset matching the ID entered.
Use the storage snapshot query command to list snapshots on the system.
Description
The promote command has one required property, id.
id is the identifier for the dataset found in the output of the storage dataset query.
Enter the property argument using the = delimiter to separate property and value.
Enter the command string then press Enter.
The command returns an empty line.
Use the query command to list all configured datasets, enter storage dataset query.
Information provided includes id (name), type, name, pool encryption settings, child datasets, comments, ACL mode and type, checksum, compression settings, quota settings, and other settings found on the Dataset add and edit screens in the UI.
To include the services consuming the dataset use the storage dataset details command.
Description
The query command does not require entering a property argument.
Enter with id or any other option to refine the output to the information requested
Enter the command then press Enter.
The command returns a table with information for all datasets on the system.
The recommended_zvol_blocksize command is a helper method to get recommended size for a new zvol (dataset of type VOLUME).
Use when creating a zvol using the storage dataset create command volblocksize property argument to enter a blocksize.
Description
The recommended_zvol_blocksize command has one required property, pool.
pool is the name of the pool found in the output of the storage pool query or storage dataset query id commands.
Enter the property argument using the = delimiter to separate property and value.
Enter the command string then press Enter.
The command returns a blocksize recommendation.
The recordsize_choices command lists record size options to use with the
Description
The recordsize_choices command does not require entering a property argument.
Enter the command then press Enter.
The command returns a list of record sizes.
Use the set_quota command to set quotas for the dataset matching the identifier specified.
There are three over-arching types of quotas for ZFS datasets:
Dataset quotas and refquotas. If specifying a DATASET quota type, then the command acts as a wrapper for pool.dataset.update.
User and group quotas.
These limit the amount of disk space consumed by files that are owned by the specified users or groups.
If specifying object quota types is specified, then the quota limits the number of objects the specified user or group can own.
Project quotas.
These limit the amount of disk space consumed by files that are owned by the specified project.
Project quotas are not yet implemented.
This command allows users to set multiple quotas simultaneously by submitting a list of quotas. The list can contain all supported quota types.
Use the account user query command or the UI to obtain the UID for the user entered into the command string.
Description
The set_quota command has two required properties, ds and quotas.
ds is the name of the target ZFS dataset found in the output of the storage dataset query.
See Quota Properties below for details on entering quota properties.
Enter the property argument using the = delimiter to separate property and value.
Enter the command string then press Enter.
The command returns an empty line.
quotas specifies three required properties to apply to dataset.
Enter property arguments inside curly brackets {}, using the : to separate double-quoted property and values, and separating with a comma and space. The quota_value property value does not require double quotes.
Enter the entire string inside square brackets []. For example:
Enter the type of quota to apply to the dataset. Options are:
USER
USEROBJ limits the number of objects consumed by the specified user or group.
GROUP
GROUPOBJ limits the number of objects consumed by the specified user or group.
DATASET
id
Enter the uid, gid, or name to apply the quota to. If quota_type is DATASET, then id must be either QUOTA or REFQUOTA. Only the root user can specify 0 as the id value.
quota_value
the quota size in bytes. Setting a value of 0 removes the user or group quota.
The snapshot_count command lists the snapshot count for the dataset matching the name entered.
Description
The snapshot_count command has one required property, dataset.
dataset is the name of the dataset found in the output of the storage dataset query.
Enter the property argument using the = delimiter to separate property and value.
Enter the command string then press Enter.
The command returns the number of snapshots for the dataset specified.
Use the unlock command to unlock the dataset or zvol matching the ID entered.
This command only works with datasets locked with a password.
The TrueNAS CLI guide for SCALE is a work in progress!
This command has not been fully tested and validated.
Full documentation is still being developed.
Check back for updated information.
Unlock_Services_Restart_Choices Command
Use the unlock_services_restart_choices command to get mapping of services identifiers and labels that can be restarted on dataset unlock.
The TrueNAS CLI guide for SCALE is a work in progress!
This command has not been fully tested and validated.
Full documentation is still being developed.
Check back for updated information.
Update Command done
Use the update command to update settings for the dataset or zvol matching the ID entered.
Description
The Update command has one required property, id.
id is the identifier for the dataset found in the output of the storage dataset query.
Enter the property argument using the = delimiter to separate property and value.
Enter the command string then press Enter.
The command returns an empty line.
Enter property arguments using the = delimiter to separate property and value. Double-quote values that include special characters.
Property arguments enclosed in curly backets {} have double-quoted properties and values separated by the : delimiter, and separate multiple property arguments with a comma. For example:
update id="tank/tank-e" sync=ALWAYS
Property
Description
Syntax Example
volsize
*Required if setting type=VOLUME. Enter the value which is a multiple of the block size. Options are 512, 512B, 1K, 2K, 4K, 8K, 16K, 32K, 64K, 128K.
volsize=8k
force_size
Only used when setting type=VOLUME. The system restricts creating a zvol that brings a pool to over 80% capacity. Enter true to force creating of a zvol in this case (not recommended). Default is false.
force_size=false or force_size=true
comments
Enter comments using upper and lowercase alphanumeric and special characters as a description about this dataset. Enclose value in double quotes.
sync
Enter the option for the desired sync setting.
STANDARD to use the standard sync settings requested by the client software.
ALWAYS to wait for data write to complete.
DISABLED to never wait for writes to complete.
comments="my comments"
snapdev
Enter the option to set whether the volume snapshot devices under /dev/zvol/poolname are HIDDEN or VISIBLE. Default inherits HIDDEN.
snapdev=HIDDEN or snapdev=VISIBLE
compression
Enter the compression level to use from the available ZFS supported options. Use storage dataset compression_choices to list ZFS supported compression algorithms. Enter the value in double quotes.
compression=OFF</>
atime
Set the access time for the dataset. Options are:
ON updates the access time for files when they are read.
OFF disables creating log traffic when reading files to maximize performance.
atime=ON or atime=OFF
exec
Enter ON to allow executing processes from within the dataset or OFF to prevent executing processes from within the dataset. We recommend setting this to ON.
exec=ON or exec=OFF
managedby
Not used. Query command includes a reference the router/switch by default.
N/A
quota
Enter a value to define the maximum overall allowed space for the dataset and the dataset descendants. Default 0 disables quotas. Default is Null.
quota=Null
quota_warning
Enter a percentage value that when reached or exceeded generates a warning alert or enter Null.
quota_warning=Null
quota_crtical
Enter a percentage value that when reached or exceeded generates a critical alert or enter Null.
quota_critical=Null
refquota
Enter a value to define the maximum allow space for just the dataset. Default 0 disables quotas. Default is Null.
refquota=Null
rfquota_warning
Enter a percentage value that when reached or exceeded generates a warning alert or enter Null.
refquota_warning=Null
refquota_crtical
Enter a percentage value that when reached or exceeded generates a critical alert or enter Null.
refquota_critical=Null
reservation
Enter a value to reserve additional space for this dataset and the dataset descendants. 0 is unlimited.
reservation=0
refreservation
Enter a value to reserve additional space for just this dataset. 0 is unlimited.
refreservation=0
special_small_block_size
Enter the threshold block size for including small file blocks into the special allocation class fusion pool. Blocks smaller than or equal to this value are assigned to to the special allocation class while greater blocks are assigned to the regular class. Valid values are zero or a power of two from 512B up to 1M. Default is 0 which means no small file blocks are allocated in the special class. Add a special class VDev to the pool before setting this value.
special_small_block_size=0
copies
Enter a number for allowed duplicates of ZFS user data stored on this dataset.
copies=2
snapdir Enter the visibility of the .zfs directory on the dataset as HIDDEN or VISIBLE.
snapdir=HIDDEN or snapdir=VISIBLE
deduplication
Enter the option to transparently reuse a single copy of duplicated data to save space. Options are:
ON to use deduplication.
VERIFY to do a byte-to-byte comparison when two blocks have the same signature to verify the block contents are identical.
OFF to not use deduplication
Deduplicating data is a one-way process. You cannot undo deduplicated data!
deduplication=OFF
checksum
Enter the checksum to use from the options: ON, OFF, FLETCHER2, FLETCHER4, SHA256, SHA512, SKEIN, or EDONR.
checksum=OFF
readonly
Enter ONto make the dataset readonly, or OFF to allow write access.
readonly=ON
recordsize
Set the logical block size in the dataset matching the fixed size of data, as in a database. This can result in better performance. Use the
aclmode
Enter the option that determines how chmod behaves when adjusting file. See zfs(8)aclmod property for more information. Options are:
PASSTHROUGH only updates ACL entries that are related to the file or directory mode.
RESTRICTED does not allow chmod to make changes to files or directories with a non-trivial ACL. A trivial ACL can be fully expressed as a file mode without losing any access rules. Use this to optimize a dataset for SMB sharing.
DISCARD
acl_type determines the acl_mode options available in the UI.
aclmodes=PASSTHROUGH
acltype
acltype is inherited from the parent or root dataset. Enter the access control type from these options:
OFF specifies neither NFSV4 or POSIX protocols.
NFSV4 is used to cleanly migrate Windows-style ACLs across Active Directory domains (or stand-alone servers) that use ACL models richer than POSIX. Use to maintain compatibility with TrueNAS CORE, FreeBSD, or other non-Linux ZFS implementations.
POSIX use when an organization data backup target does not support native NFSV4 ACLs. Linux platforms use POSIX and many backup products that access the server outside the SMB protocol cannot understand or preserve native NFSV4 ACLs. Datasets with share_type set to GENERIC or APPS have POSIX ACL types.
acltype=POSIX
xattr
Set SA to store extended attributes as System Attributes. This allows storing of tiny xattrs (~100 bytes) with the dnode and storing up to 64k of xattrs in the spill block. This results in fewer IO requests when extended attributes are in use. Set ON to store extended attributes in hidden sub directories but this can require multiple lookups when accessing a file.
Provides information about the storage disk namespace in the TrueNAS CLI. Includes command syntax and common commands.
Disk Namespace
The disk namespace has 12 commands and is based on disk management functions found in the SCALE API and web UI.
It provides access to disk management methods through the disk commands.
Disk Commands
The following disk commands allow you to view and edit disk properties.
You can enter commands from the main CLI prompt or from the disk namespace prompt.
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!
Interactive Argument Editor (TUI)
Enter the -- flag following any CLI command to open the interactive arguments editor text-based user interface (TUI).
Get_Instance Command
The get_instance command returns all the settings for a specified disk.
Use the query command to locate the identification number for system disks.
Description
The get_instance command has one property, id.
Enter the entire string listed as the identifier in the query command output for the identifier property value.
Enter the property argument using the = delimiter separating the property and double-quoted value.
Enter the command then press Enter.
The command returns a table containing the identifier, name, subsystem, number, serial, lunid, size, description, transfermode, hddstandby, advpowermgmt, togglesmart, smartoptions, expiretime, passwd, critical, difference, informational, model, rotationrate, type, kmip_uid, zfs_guid, bus, exported_zpool, unsupported_md_devices, duplicate_serial, enclosure, partitions, add devname properties for the specified disk.
Usage
From the CLI prompt, enter:
storage disk get_instance id="diskidentifier"
Where diskidentifier is the identifier of the disk you want to view.
The get_unused command returns disks that are not in use by any zpool. It also returns disks used by any exported zpool.
You can add the optional join_partitions property argument to list disk partitions as well.
Description
The get_unused command does not require entering properties or arguments but has one optional join_partitions property.
Enter join_partitions=true to include disk partitions in the command output, or false to not include partition information.
Enter the command then press Enter.
The command returns a table containing the identifier, name, subsystem, number, serial, lunid, size, description, transfermode, hddstandby, advpowermgmt, togglesmart, smartoptions, expiretime, passwd, critical, difference, informational, model, rotationrate, type, kmip_uid, zfs_guid, bus, exported_zpool, unsupported_md_devices, duplicate_serial, enclosure, partitions, add devname properties for every unused disk.
Enter the join_partitions argument to return all partitions written to each disk. The default is false.
Enter the command string then press Enter.
The command returns a table containing the identifier, name, subsystem, number, serial, lunid, size, description, transfermode, hddstandby, advpowermgmt, togglesmart, smartoptions, expiretime, passwd, critical, difference, informational, model, rotationrate, type, kmip_uid, zfs_guid, bus, exported_zpool, unsupported_md_devices, duplicate_serial, enclosure, partitions, add devname properties for every unused disk.
The query command displays information about all disks on the system.
Description
The query command does not require entering property arguments.
Enter the command then press Enter.
The command returns a table containing the identifier, name, subsystem, number, serial, LUN ID, size, description, transfer mode, HDD standby status, S.M.A.R.T. status, S.M.A.R.T. options, expiration time, criticality, difference, informational status, model, rotation rate, drive type, ZFS globally unique identifier, bus type, dev name, enclosure, S.M.A.R.T. support, and pool for every disk in the system.
Enter the query command with one of the optional attributes to filter out other attributes from the query return.
See Query Attributes below for the list of 26 available query attributes.
Enter the command string then press Enter.
The command returns a table with the specified attribute.
Attribute
Purpose
identifier
Disk serial number and LUN ID.
name
Disk name.
subsystem
Disk subsystem (SAS, SCSI, NVME)
number
Disk number.
serial
Disk serial.
lunid
Disk LUN ID.
size
Disk size in bytes.
description
Disk description.
transfermode
Disk transfer mode.
hddstandby
HDD standby timer.
advpowermgmt
Advanced power management profile.
togglesmart
S.M.A.R.T. status.
smartoptions
Applied S.M.A.R.T. options.
expiretime
critical
Threshold temperature in Celsius
difference
Report if the temperature of a drive has changed by this many degrees Celsius since the last report.
informational
Report if the drive temperature is at or above this temperature in Celsius. 0 disables the report.
model
Disk model number.
rotationrate
Disk rotation rate.
type
Disk type (HDD, SSD, NVME).
zfs_guid
Disk ZFS ID.
bus
Disk bus type (ATA, SCSI, M.2).
devname
Disk developer name.
enclosure
Disk enclosure.
supports_smart
Disk S.M.A.R.T. support status.
pool
Disk pool.
Usage
From the CLI prompt, enter:
storage disk query attribute
Where:
attribute is the attribute you want to filter in the query.
storage disk query name
+---------+
| name |
+---------+
| sdb |
| sda |
| nvme0n1 |
| sdc |
...
+---------+
Resize Command
The resize command allows you to resize disks to a specific size in gigabytes.
Use the query command to locate the name for system disks.
Description
The resize command has one required property, disks, and two optional properties, sync, and raise_error.
See Resize Properties below for details.
Enter the command string then press Enter.
The command returns completion percentages when successful.
Property
Required
Description
Syntax Example
disks
Yes
Use to specify the disks and size (optional) in gigabytes. Enter the name property argument using : to separate double-quoted property and value. Separate multiple disk values with a comma. Enter the size property argument using : to separate double-quoted property and value. The default value for size is null. Enclose both name and size in curly brackets {}.
If size is smaller than the physical space available on the disk, the remaining space is reserved for over-provisioning. If size is not given, the disk reverts to its original size (un-overprovision).
The retaste command forces the system to re-read specified disks and update their data.
Use the query command to locate the identification number for system disks.
Description
The retaste command has one required property, disks.
Enter the disks property argument using = to separate property and value. Separate multiple disks with a comma.
Enter the command string then press Enter.
The command returns completion percentages when successful.
Usage
From the CLI prompt, enter:
storage disk retaste disks=name1,name2
Where name1 and name2 are the names of the disks you want to retaste.
storage disk retaste disks=sdl
[85%] Retasting disks...
[95%] Waiting for disk events to settle...
[100%] Retasting disks done...
SUCCESS
Smart_Attributes Command
The smart_attributes command returns S.M.A.R.T. attributes values for specified disk.
Use the query command to locate the identification number for system disks.
Only devices with the ATA bus type support S.M.A.R.T. attributes.
Description
The smart_attributes command has one required property, disks, which specifies the disk you want to view S.M.A.R.T. attributes for.
Enter the property argument using = to separate property and value.
Enter the command string then press Enter.
The command returns a table with S.M.A.R.T. attributes when successful.
Usage
From the CLI prompt, enter:
storage disk smart_attributes name=diskname
Where diskname is the name of the disk you want to view S.M.A.R.T. attributes for.
The temperature command returns the temperature of a specified disk.
Use the query command to locate the identification number for system disks.
Description
The temperature command has two required properties, name and options.
options has two required properties, cache and powermode.
See Temperature Command Properties below for details.
Enter the command string then press Enter.
The command returns a temperature (in Celsius) when successful.
Property
Required
Description
Syntax Example
name
Yes
Use to specify the disk to see temperature for. Enter the name property argument using : to separate double-quoted property and value. Separate multiple disk values with a comma. Enter the size property argument using : to separate double-quoted property and value. The default value for size is null. Enclose both name and size in curly brackets {}.
Use to retrieve previous temperatures for the disk by specifying how far back in seconds to go in the cache and to specify the power mode to apply. cache specifies the number of seconds to go in the cached temperature values to go to retrieve information. Enter the number property argument using : to separate double-quoted property and value. The default is null which returns the current temperature. powermode specifies the S.M.A.R.T. power mode to apply:
NEVER where the device is fully powered up and ready to send/receive data. The disk only undergoes S.M.A.R.T. tests when powermode is set to NEVER. The default value is NEVER.
IDLE where the disk completes commands slower than when set to NEVER but uses less power.
STANDBY where the disk completes commands slower than when set to IDLE but uses less power.
SLEEP where the disk does not complete commands until reset. Uses the least amount of power.
Enter property argument enclosed in curly brackets {}, with both cache and powermode using : to separate double-quoted properties and values, and each argument is separated with a comma.
storage disk temperature name=diskname options={“cache”:"seconds",“powermode”:"MODE"}
Where:
diskname is the name of a disk.
seconds is how far back in seconds you want to view the disk temperature.
MODE is the S.M.A.R.T. powermode you want to apply.
storage disk temperature name=sda options={"cache":"30","powermode":"NEVER"}
40
Temperature_Agg Command
The temperature_agg command returns min/max/avg temperature for specified disks for a set amount of previous days.
Use the query command to locate the identification number for system disks.
Description
The temperature_agg command has one required property, name, and one optional property, days.
days specifies the number of days to include in the result. The default is 7.
Enter the property argument using = to separate property and value.
Enter the command string then press Enter.
The command returns a table with the minimum, maximum, and average temperatures over the specified amount of days.
Usage
From the CLI prompt, enter:
storage disk temperature_agg names=diskname1,diskname2 days=number
Where
diskname1 and diskname2 are the names of disks to include in the command output.
number is the number of days you want to view temperatures for.
The temperature_alerts command returns existing temperature alerts for specified disks.
Use the query command to locate the identification number for system disks.
Description
The temperature_alerts command has one required property, name.
Enter the property argument using the = to separate the property and value. Separate multiple values with a comma.
Enter the command string then press Enter.
The command returns a list with all existing disk alerts.
Usage
From the CLI prompt, enter:
storage disk temperature_alerts names=diskname1,diskname2
Where diskname1 and diskname2 are the names of the disks you want to view alerts for. Separate each disk name with a comma.
storage disk temperature_alerts names=sda,sdb
(empty list)
Temperatures Command
The temperatures command returns temperatures for a list of specified disks and allows you to set the S.M.A.R.T. powermode.
Use the query command to locate the identification number for system disks.
Description
The temperatures command has two required properties, name and options.
options has two required properties, cache and powermode.
See Temperature Command Properties found in the temperature command section.
Enter the command string then press Enter.
The command returns a table of disk temperatures (in Celsius) when successful.
Usage
From the CLI prompt, enter:
storage disk temperatures name=diskname options=MODE
Where
diskname is the name of a disk.
MODE is the S.M.A.R.T. powermode you want to apply.
The update command allows you to update settings for a specified disk.
Description
The update command requires entering id and has 12 additional required properties and three optional properties.
See Update Command Properties below for details.
After specifying the id of the disk you want to update, you must include at least one property to update.
Enter the command string, then press Enter.
The command returns nothing when successful.
Property
Required
Description
Syntax Example
id
Yes
Enter the full string found in the identifier column in the query command output. Enter the property argument using the = to separate the property and double-quoted value. Value can be null.
id="identifiervalue"
number
Yes
Enter the disk number. Must be between 1 and 21 digits. Enter the property argument using the = to separate the propery and value.
number=number
lunid
Yes
Enter the disk LUN ID. Can be numbers, letters, and symbols. Enter the property argument using the = to separate the property and double-quoted value. Value can be null.
lunid=“lunid”
description
Yes
Enter the disk description. Enter the property argument using the = to separate the property and double-quoted value.
description=“description”
hddstandby
Yes
Enter the HDD standby timer (in minutes). Options are ALWAYS ON, 5, 10, 20, 30, 60, and 120. Enter the property argument using the = to separate the property and double-quoted value.
hddstandby=“option”
advpowermgmt
Yes
Enter the advanced power management profile. Options are DISABLED, 1, 64, 127, 128, 192, and 254. Enter the property argument using the = to separate the property and double-quoted value.
advpowermgmt=“option”
togglesmart
Yes
Enter true to enable S.M.A.R.T. status.
togglesmart=true/false
smartoptions
Yes
Enter the S.M.A.R.T. options to apply. Options are NEVER, IDLE, STANDBY, and SLEEP. Enter the property argument using the = to separate the property and double-quoted value.
smartoptions=option
critical
Yes
Enter the threshold temperature in Celsius. If the drive temperature is higher than this value, a LOG_CRIT level log entry is created and an email is sent. 0 disables this check. Enter the property argument using the = to separate the property and double-quoted value.
critical=number
difference
Yes
Enter the threshold temperature in Celsius. Report if the temperature of a drive has changed by this many degrees Celsius since the last report. 0 disables the report. Enter the property argument using the = to separate the property and double-quoted value.
difference=number
informational
Yes
Enter the threshold temperature in Celsius. Report if the drive temperature is at or above this temperature in Celsius. 0 disables the report. Enter the property argument using the = to separate the property and double-quoted value.
informational=number
bus
Yes
Enter the disk bus type (ATA, SCSI, M.2). Enter the property argument using the = to separate the property and double-quoted value.
bus=“option”
enclosure
No
Enter a number for the disk enclosure. enclosure has two properties, number and slot. Enclose these property arguments in curly brackets {}. Enter the property arguments using the : to separate the double-quoted property and value of each property argument. Separate the number and slot property arguments with a comma.
enclosure={“number”:“number”,“slot”:“number”
pool
Yes
Enter the disk pool or use null. Enter the property argument using the = to separate the property and double-quoted value.
N/a
passwd
No
SED alphanumeric password. Enter the property argument using the = to separate the property and double-quoted value.
password=password
supports_smart
No
Enter true to enable disk S.M.A.R.T. support status.
supports_smart=true or supports_smart=false
Usage
From the CLI prompt, enter:
storage disk update id="diskidentifier" property=option
Where:
diskidentifier is the full string value found in the identifier column of the query command output.
option is any of the properties listed in the Update Command Properties table above.
storage disk update id="{serial_lunid}N4G22WKK_5000cca24503ce58" enclosure={"number":"1","slot":"1"}
Wipe Command
The wipe command wipes a specified disk using various wipe modes.
The wipe command has four required properties, dev, mode, synccache, and swap_removal_options.
See the Wipe Command Properties below for details.
After specifying the dev name of the disk you want to update, you must include at least one property to update.
Enter the command string then press Enter.
The command returns nothing when successful.
Property
Description
Syntax Example
dev
Enter the name of the disk (device). Enter the property argument using the = to separate the property and value.
dev=devname
mode
Enter the mode to use when wiping the disk. Options are:
QUICK to clean the first and last 32 megabytes.
FULL to write the whole disk with zeros.
FULL_RANDOM to write the whole disk with random bytes.
Enter the property argument using the = to separate the property and value.
mode=wipemode
syncchace
Enter true to enable synchronization with the cache after wiping the disk. The default is true.
synccache=true or synccache=false
swap_removal_options
Enter true to remove the swap file entry or swap partition after wiping the disk. The default is true.
swap_removal_options=true or swap_removal_options=false
Usage
From the CLI prompt, enter:
storage disk wipe dev=devname mode=wipemode synccache=true/false swap_removal_options=true/false
Where:
devname is the dev name of a disk.
wipemode is the wipe mode to use on the disc.
true/false to enable/disable synchronizing with the cache after wiping the disk.
true/false to enable/disable swap_removal_options.
storage disk wipe dev=sdl mode=QUICK synccache=true swap_removal_options=true
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!
Snapshot Namespace
The pool namespace has 23 commands, and is based on pool creation and management functions found in the SCALE API and web UI.
It provides access to storage pool methods through the pool commands.
Snapshot Commands
The following pool commands allow you to create new pools and manage existing pools.
You can enter commands from the main CLI prompt or from the snapshot namespace prompt.
Interactive Argument Editor (TUI)
Enter the -- flag following any CLI command to open the interactive arguments editor text-based user interface (TUI).
Attach Command
Use the attach command to add disks to a VDev.
The target_vdev is the GUID of the VDev (pool) where you need to attach the disk. A GUID is a random and unique 64-bit identifier for a pool, VDev, or disk.
If attaching to a stripe VDev (pool), this is the striped disk GUID that is converted to a mirror.
If attaching to a mirror VDev, the mirror is converted to an n-way mirror.
ZFS supports n-way mirroring. This means you can add disks into a mirror VDev. See TrueNAS ZFS Primer for more information.
This command only works with mirror and stripe VDevs. You cannot use this command if the pool is in a RAIDz configuration.
Use the storage disk query command to locate the zfs_guid number.
Use the disk ID with the storage disk get_instance command to find the zfs_guid for a specific disk in a format easier to read.
The TrueNAS CLI guide for SCALE is a work in progress!
This command has not been fully tested and validated.
Full documentation is still being developed.
Check back for updated information.
Attachments Command
The attachments command returns a list of services the pool matching the specified ID is using.
Description
The attachments command has one required property, id.
id is the GUID number for the pool found in the output of the storage pool query command and either of the storage pool get_instance commands.
Enter the property argument using the = delimiter to separate property and value.
Enter the command string then press Enter.
The command returns a table with type, service, and attachments for the specified pool ID.
Usage
From the CLI prompt, enter:
storage pool attachments id=4
Where 4 is the number assigned to the pool by the system.
The create command creates a new pool, specifies the type of VDev(s) and number of disks for each VDev in the pool.
This command performs the same functions as the Pool Creation Wizard in the UI.
The TrueNAS CLI guide for SCALE is a work in progress!
This command has not been fully tested and validated.
Full documentation is still being developed.
Check back for updated information.
Detach Command
The detach command detaches a disk from the pool matching the ID entered. Removing a disk from a mirror pool changes the pool VDev to a stripe.
Use the storage disk query command to locate the vdev_guid for the disk.
Description
The detach command has two required properties, id and options.
options has one required property argument, label.
Use label to enter the vdev guid or the device name.
Enclose the options property argument in curly brackets{}. Enter the label property argument inside the brackets using the = delimiter to separate the property and double-quoted value.
Enter the command string then press Enter.
The command returns true upon successful execution of the command.
Usage
From the CLI prompt, enter:
storage pool detach id=4 options={“label”:"13914848339130932484"}
Where 13914848339130932484 is the vdev_guid of the disk.
storage pool detach id=4 options={"label":"13914848339130932484"}
Expand Command
The expand command increases the pool size to match all available disk space for the pool matching the ID specified. Pools using virtual disks use this option to resize the virtual disks apart from TrueNAS.
Description
The expand command has one required property, id.
Enter the property argument using the = delimiter to separate the property and value.
Enter the command string then press Enter.
Usage
From the CLI prompt, enter:
storage pool expand id=4
Where 4 is the pool ID number assigned by the system.
storage pool expand id=4
[0%]...
[100%]...
Export Command
The export command exports the pool/data for the pool matching the ID specified. Exporting a pool disables services, terminates any processes the pool uses, removes disks from the pool then cleans up after the export.
Use with the options properties to completely destroy the pool and data, remove all attachments, and to restart any services associated with the pool.
Use without the options property argument to just export the pool.
If using on an HA system with failover is enabled, and exporting/disconnecting the last zpool, then this raises an EOPNOTSUPP error.
Failover must be disabled before exporting the last zpool on the system.
Description
The export command has two properties, required ‘id’ and optional ‘options’.
id specifies the pool ID number assigned by the system.
options has three optional properties. See Options Properties below for details and syntax examples.
Use the default value {} if not specifying options property arguments.
Enter property argument using the = delimiter to separate property and values.
Enter the command string then press Enter.
The command returns progress in percentage complete for each part of the export process.
If entering multiple options property arguments, separate each with a comma but no space, for example options={“cascade”:"true",“restart_services”:"false",“destroy”:"true"}.
Property
Description
Syntax Example
cascade
Set cascade to true to remove all attachments from the specified pool. Set to false to not remove . Enter the cascade property argument with the : to separate double-quoted property and value. Enclosed in curly brackets {}.
options={[“cascade”:"true"]}
restart_services
Set restart_services to true to restart any services associated with the specified pool. Set to false to not restart services. Enter the restart_services property argument with the : to separate double-quoted property and value. Enclosed in curly brackets {}.
options={[“restart_services”:"true"]}
destroy
Set destroy to true to destroy the specified pool/data. Set to false to not destroy the pool/data. Enter the destroy property argument with the : to separate double-quoted property and value. Enclosed in curly brackets {}.
options={[“destroy”:"true"]}
Usage
From the CLI prompt, enter:
storage pool export id=5 options={}
Where 5 is the pool ID number assigned by the system.
storage pool export id=6 options={}
[0%] ...
[0%] Disabling pool attachments: Replication...
[1%] Disabling pool attachments: Snapshot Task...
[2%] Disabling pool attachments: SMB Share...
[3%] Disabling pool attachments: CloudSync Task...
[4%] Disabling pool attachments: NFS Share...
[5%] Disabling pool attachments: Rsync Task...
[6%] Disabling pool attachments: Cloud Backup Task...
[7%] Disabling pool attachments: iSCSI Extent...
[8%] Disabling pool attachments: VM...
[9%] Disabling pool attachments: Chart Releases...
[10%] Disabling pool attachments: Kubernetes...
[20%] Terminating processes that are using this pool...
[30%] Removing pool disks from swap...
[80%] Exporting pool...
[90%] Cleaning up after export...
[100%] Cleaning up after export...
Filesystem_Choices Command
The filesystem_choices command lists the dataset paths available on the system. Use the properties to modify the list to only include zvols (volumes) on the system.
Description
The filesystem_choices command has one optional property, types.
See Types Properties table below for details on the types properties and proper syntax.
Enter filesystem_choices then press Enter.
Entering the command without the types property or with the types default property argument lists the all file system paths (datasets and zvols) on the system.
types has two properties, FILESYSTEM and VOLUME. The default value for types includes both properties entered as types=["FILESYSTEM", "VOLUME"].
Property
Description
Syntax Example
FILESYSTEM
Use the FILESYSTEM property to only list dataset paths. Enter the type property argument with FILESYSTEM double-quoted and enclosed in square brackets []
type=["FILESYSTEM"]
VOLUME
Use the VOLUME property to list only the zvols (paths) configured on the system. Enter the type property argument with VOLUME double-quoted and enclosed in square brackets []
type=["VOLUME"]
Usage
From the CLI prompt, enter:
storage pool filesystem_choices
storage pool filesystem_choices
tank
tank/ix-applications
tank/shares
tank/shares/nfs
tank/zvols
tank/zvols/zvol1
tank/zvols/zvol2
tank2/reptests
tank2/snapshots
tank2/snapshots/task1
Get_Disks Command
The get_disks command lists the disks found in the pool matching the ID entered, or if no ID is entered, all disks on the system.
Description
The get_disks has one optional property, id.
Enter the get_disks command without the id property argument to get a list of all disks (names) on the system.
Enter with the id property argument to get the disks in the pool matching the number entered.
id is the number given to the pool by the system at creation.
Enter the command string then press Enter.
The command returns a list of disks (names) in the pool or on the system.
Usage
From the CLI prompt, enter:
storage pool get_disks
or to get the disks used in a specific pool, enter:
storage pool get_disks id=5
Where 5 is the ID number assigned to the pool by the system at creation.
storage pool get_disks
sdc
sda
sdd
sde
Get_Instance Command
The get_instance command returns a table of properties for the pool matching the ID entered.
To view the same properties for all pools on the system use the query command.
Description
The get_instance has one required property, id.
id is the number given to the pool by the system at creation.
Enter the command string then press Enter.
The command returns a table for the pool that includes the ID, name, GUID, path, status, healthy, warning, and status code status; a dictionary value for scan, topology, and autotrim, and storage values for pool size, allocated and free space, fragmentation and freeing, and the string values for size, allocated, free, and freeing.
If the name entered is not found the system returns a validation error.
Usage
From the CLI prompt, enter:
storage pool get_instance=5
Where 5 is the pool ID number assigned by the system at pool creation.
The get_instance_by_name command returns a table of properties for the pool matching the name entered.
Use when you do not have the ID number required to use the get_instance command.
To view properties for all pools on the system use the query command.
Description
The get_instance_by_name has one required property, name.
name is the name given the pool at creation.
Enter the property argument using the = delimiter to separate the property and value.
Double-quote the name if it includes a special character.
Enter the command string then press Enter.
The command returns a table for the pool that includes the ID, name, GUID, path, status, healthy, warning, and status code status; a dictionary value for scan, topology, and autotrim, and storage values for pool size, allocated and free space, fragmentation and freeing, and the string values for size, allocated, free, and freeing.
If the name entered is not found the system returns a validation error.
Usage
From the CLI prompt, enter:
storage pool get_instance_by_name=tank
Where tank is the pool name assigned at pool creation.
The import_find command returns a job id which can be used to retrieve a list of pools available for import. The command returns the name, guid, status, host name details.
Description
The import_find command does not require entering a property argument.
Enter the command then press Enter.
The command returns a table with the name, guid, status and host name for pools available for import.
Usage
From the CLI prompt, enter:
storage pool import_find
storage pool import_find
[0%] ...
[100%] ...
+-------+----------------------+--------+-------------+
| name | guid | status | hostname |
+-------+----------------------+--------+-------------+
| tank2 | 10728262665093888122 | ONLINE | qe-mini2-01 |
+-------+----------------------+--------+-------------+
Import_Pool Command
The import command uses information from the import_find command output to import a pool.
Description
The import_pool command has one required property, pool_import.
pool_import has three required properties, guid, name and enable_attachments.
See Pool_Import Properties below for details.
Enter the command string then press Enter.
The command returns status in percentage and true upon successful completion of the import.
Use the interactive argument editor to enter values for these properties.
Property
Description
guid
Enter the guid provided in the import_find command output.
name
Enter the name provided in the import_find command output.
enable_attachments
Enter true to include any attachments for the pool.
Usage
From the CLI prompt, enter:
storage pool import_pool –
storage pool import_pool --
[100%] …
true
Is_Upgraded
The is_upgraded command indicates if a pool is upgraded with new ZFS feature flags after upgrading SCALE to a new major release.
Use the storage pool query command to obtain pool IDs.
Description
The is_upgraded command has one required property, id.
Enter the property argument using the = to separate the property and value.
Enter the command string then press Enter.
The command returns true if the ZFS feature flags for the pool matching the id entered do not require upgrading.
Usage
From the CLI prompt, enter:
storage pool is_upgraded id=4
Where 4 is the pool ID assigned by the system.
storage pool is_upgraded id=4
true
Offline Command
Use the offline command to take a disk in a pool, matching the ID entered, offline. This command uses the disk vdev_guid to identify the disk.
Use the storage disk query command to locate the vdev_guid for the disk to offline.
Use the storage pool get_disks command to identify the disks in the pool.
Description
The offline command has two required properties, id and options.
id is the number assigned to the pool by the system.
Enter the id property argument using the = delimiter to separate property and value.
options has one required property, label.
label is the vdev_guid assigned to the disk you offline.
Enclose the label property argument in curly brackets {}, enter the property argument using the : dilimter to separate double-quoted property and value.
Enter the command string then press Enter.
The system returns true upon successful completion of the command.
Usage
From the CLI prompt, enter:
storage pool offline id=4 options={“label”:"6515190129612429183"}
Where:
4 is the pool ID number assigned by the system.
6515190129612429183 is the disk vdev_guid assigned by the system.
storage pool offline id=4 options={"label":"6515190129612429183"}
true
Online Command
Use the online command to bring a disk in a pool, matching the ID entered, online. This command uses the disk vdev_guid to identify the disk.
Use the storage disk query command to locate the vdev_guid for the disk to offline.
Use the storage pool get_disks command to identify the disks in the pool.
Description
The online command has two required properties, id and options.
id is the number assigned to the pool by the system.
Enter the id property argument using the = delimiter to separate property and value.
options has one required property, label.
label is the vdev_guid assigned to the disk you offline.
Enclose the label property argument in curly brackets {}, enter the property argument using the : delimiter to separate double-quoted property and value.
Enter the command string then press Enter.
The system returns true upon successful completion of the command.
Usage
From the CLI prompt, enter:
storage pool online id=4 options={“label”:"6515190129612429183"}
Where:
4 is the pool ID number assigned by the system.
6515190129612429183 is the disk vdev_guid assigned by the system.
storage pool online id=4 options={"label":"6515190129612429183"}
true
Processes Command
The processes command lists processes used by the pool matching the ID entered.
Description
The processes command has one required property, id.
Enter the property argument using the = delimiter separating the property and value.
Enter the command string then press Enter.
The command returns a list of processes for the pool or (empty list) if no processes are used.
Usage
From the CLI prompt, enter:
storage pool processes id=4
Where 4 is the pool ID number assigned by the system.
storage pool processes id=4
(empty list)
Query Command
The query command returns a table (dictionary) of all pools on the system.
Description
query does not require entering property arguments.
Enter the command then press Enter.
The query returns a table (dictionary) of all pools on the system.
Information includes the ID, GUID, mount path, status, scan, topology, health and warning status and status code, size including allocated and free, freeing, fragmentation, and the size, allocated, free and freeing string, and the autotrim state.
The remove command removes the ZFS device from the pool matching the ID entered and wipes disks in the pool.
Description
The remove command has two required properties, id and options.
id is the number assigned to the pool by the system.
Enter the id property argument using the = delimiter to separate property and value.
options has one required property, label.
label is the vdev_guid assigned to the disk you remove.
Enclose the label property argument in curly brackets {}, enter the property argument using the : delimiter to separate double-quoted property and value.
Enter the command string then press Enter.
The command returns device removal and disk wiping status indications in percentage complete.
Usage
From the CLI prompt, enter:
storage pool remove id=4 options={“label”:"8533090430494837337"}
Where:
4 is the pool ID assigned by the system.
8533090430494837337 is the disk vdev_guid assigned by the system.
storage pool remove id=4 options={"label":"8533090430494837337"}
[0%] ...
[20%] Initiating removal of '8533090430494837337' ZFS device...
[40%] Waiting for removal of ZFS device to complete...
[60%] Removal of ZFS device complete...
[70%] Wiping disks...
[100%] Successfully completed wiping disks...
Replace Command
The replace command removes a disk and replaces it with the disk matching the vdev_guid entered.
This command performs the same function as the disk replace UI function.
The TrueNAS CLI guide for SCALE is a work in progress!
This command has not been fully tested and validated.
Full documentation is still being developed.
Check back for updated information.
The scrub command has two required properties, id and action.
id specifies the pool ID numbers assigned by the system.
action has three options, START, STOP, and PAUSE.
Enter property arguments using the = delimiter to separate property and value.
Enter the command string then press Enter.
The START command string returns progress status in percentage complete.
Start the scrub in the UI and use the STOP command string to stop the operation. The command string returns progress of the stop action.
Start the scrub in the UI and use the PAUSE command string to paus the operation. The command string returns progress of the pause action.
Use START to resume a paused scrub.
The update command updates properties for the pool matching the ID entered.
The TrueNAS CLI guide for SCALE is a work in progress!
This command has not been fully tested and validated.
Full documentation is still being developed.
Check back for updated information.
Upgrade Command
The upgrade command upgrades the pool matching the ID entered with available ZFS feature flags. Use after updating SCALE to a new release or after importing a pool.
Description
The upgrade command has one required property, id.
Enter the property argument using the = to separate the property and value.
Enter the command string then press Enter.
The command returns true if the pool matching the id is upgraded.
Usage
From the CLI prompt, enter:
storage pool upgrade id=7
Where 7 is the pool ID assigned by the system.
storage pool upgrade id=7
true
Validate_Name Command done
The validate_name command validates the pool name entered.
Description
The validate_name command has one required property, pool_name.
pool_name specifies the pool name to verify.
Enter the command string then press Enter.
The command returns true if the pool name is valid.
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!
Scrub Namespace
The scrub namespace has 7 commands, and is based on data integrity check (scrub) functions found in the SCALE API and web UI.
It provides access to scrub task management methods through the scrub namespace commands.
Scrub Commands
The following scrub namespace commands allow you to manage scheduled scrub task configuration and to start, pause, or stop a scrub.
You can enter commands from the main CLI prompt or from the storage namespace prompt.
Create Command
The create command configures a new scheduled scrub task.
Description
create has one required property, pool, and four optional properties (see Create Properties below).
The value for pool is the pool id number.
Use storage pool query to find the id for the selected pool and enter this integer.
Enter the full command string along with any optional properties you want to configure, or accept the default values, and then press Enter.
create returns an empty line when successful.
Use query to confirm the task is created correctly.
Property
Required
Description
Syntax Example
pool
Yes
Enter the id number for the selected pool. Use storage pool query to find the id numbers for all pools on the system.
pool=1
threshold
No
Enter the number of days before a completed scrub is allowed to run again. Default value is 35. This controls the task schedule. For example, scheduling a scrub to run daily and setting Threshold days to 7 means the scrub attempts to run daily. When the scrub succeeds, it continues to check daily but does not run again until the seven days have elapsed. Using a multiple of seven ensures the scrub always occurs on the same weekday.
threshold=7
description
No
Enter a human-readable name or description for the scrub task.
description= “scrub task 1"
schedule
No
Enter an array of properties that specify the date and time when the scrub task runs. The default setting is to run the task weekly, every Sunday at 00:00 (0 0 * * 0). Enter {} without property arguments to accept default values for schedule properties, or enter each property argument enclosed in square brackets with double-quoted properties and values. Separate each array property argument enclosed in square brackets [] with a comma and space. Properties are:
minute specified in the format of minutes:seconds or use the default 00
hour specified in the format of 00 (0-23) or use the default * for every hour.
dom specifies the day of month in the format of jan through dec or use the default * for every month.
month specifies the month in the format of jan or use the default * for any month.
dow specifies the day(s) of the week as sun, mon, tue, wed, thu, fri, or sat or use the default * for every day of the week.
Command example shows the default values for each property in the object array.
The run command activates a one-time scrub task for the selected pool.
Description
run has one required property, name, and one optional property, threshold.
To find the name of the pool you want to scrub, use storage pool query or storage dataset query id to return the paths of all pools and child datasets on the system.
threshold defaults to 35 days.
To preserve system resources, the scrub runs only if time since the pool was last scrubbed is greater than the threshold value.
To override the threshold and run immediately, you can use threshold=0.
Enter the full command string and then press Enter.
run returns an empty line.
To check if the scrub starts successfully, you can use system alert list to view system alerts.
Usage
From the CLI prompt, enter:
storage scrub run name="tank"
Where tank is the name of the pool you want to scrub.
Press Enter.
storage scrub run name="tank" threshold=35
Scrub Command
The scrub command allows you to start a one-time scrub task for the selected pool and to pause or stop an active scrub.
Description
scrub has two required properties, name and action.
To find the name of the pool you want to scrub, use storage pool query or storage dataset query id to return the paths of all pools and child datasets on the system.
There are three possible values for action:
START
PAUSE
STOP
Enter the full command string and then press Enter.
Returns the percentage status of action.
Usage
From the CLI prompt, enter:
storage scrub scrub name="tank" action=START
Where tank is the name of the selected pool and START is one of the three possible actions.
Press Enter.
The update command allows you to change the configuration of an existing scheduled scrub task.
Description
update has one required property, id, and eight optional properties.
Use query to view the id numbers for existing scheduled scrub tasks.
For optional properties, see the create properties.
Enter the command string with any optional properties you want to update and then press Enter.
Usage
From the CLI prompt, enter:
storage scrub update id=1property=value
Where 1 is the id of the scrub task to update, property is one of the configuration properties, and value is the new setting for that property.
Press Enter.
update returns an empty line.
Use query or get_instance to confirm the new settings are applied.
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!
Snapshot Namespace
The snapshot namespace has 10 commands, and is based on snapshot creation and management functions found in the SCALE API and web UI.
It provides access to storage snapshot methods through the snapshot commands.
Snapshot Commands
The following snapshot commands allow you to create new snapshots and manage existing snapshots.
You can enter commands from the main CLI prompt or from the snapshot namespace prompt.
Interactive Argument Editor (TUI)
Enter the -- flag following any CLI command to open the interactive arguments editor text-based user interface (TUI).
Clone Command
The clone command clones an existing snapshot to a new dataset.
The TrueNAS CLI guide for SCALE is a work in progress!
This command has not been fully tested and validated.
Full documentation is still being developed.
Check back for updated information.
Create Command
The create command takes a snapshot of a given dataset.
Description
The create command has one required property, dataset, and seven optional properties.
The Create Command Optional Properties section below lists the seven optional properties and provides syntax examples.
dataset defines the pool/dataset path for the snapshot you want to create. For example, tank/minio.
Enter a property argument using the = delimiter to separate property and value. Enter string values in double quotes.
Enter the command string then press Enter.
create returns an empty line.
Use the query command to verify the snapshot was created and to view details on the snapshot.
Use these optional properties when creating a snapshot.
Property
Description
Syntax Example
name
Enter a unique snapshot name. Use either name or naming schema in the same snapshot but not both, one or the other is required. Entering a name does not require using double quotes, but if entering a name string (two words or including a special character), enclose the string in double quotes.
name=miniosnaps or name="rep_snaps"
naming_schema
Enter a naming schema to generate a name for the snapshot instead of using name. Enter a new schema in double-quotes, the default auto-%Y-%m-%d_%H-%M schema, or a naming schema from a previously created periodic snapshot task. This allows replication of the snapshot. Naming schema must include the year %Y, month %m,day %d, hour %H, and minute %M. These are replaced with the four-digit year, month, day of month, hour, and minute as defined in strftime(3). For example, snapshots of pool1 entering naming_schema=customsnap-%Y%m%d.%H%M have snapshots named pool1@customsnap-20190315.0527. Use either naming_schema or name in the same snapshot but not both.
naming_schema="customsnap-%Y%m%d.%H%M"
recursive
Enter true to include child datasets of the chosen dataset or false to exclude child datasets.
recursive=true or recursive=false
exclude
Use with recursive=true to enter child datasets to exclude from the snapshot. Enter a child dataset name in double quotes. If entering multiple child datasets, use a comma and space to separate each entry.
exclude="child1", “child2"
suspend_vms
This option is a work in progress.
vmware_sync
Enter true to synchronize the snapshot with VMWare or false if VMWare is not in use or to not synchronize with it.
The delete command deletes a snapshot matching the ID entered.
Use the query command to locate the snapshot ID.
Description
delete has one required property, id.
Enter the property argument using the = delimiter separating the property and value, and the value double-quoted.
Enter the command string, then press Enter.
The get_instance command retrieves information for a snapshot matching the id entered in the command string.
Use to verify properties for the snapshot.
Use the query command to find the list of snapshots and the ID for a snapshot.
Description
get_instance has one required property, id.
Enter the property argument using the = delimiter separating the property and value, and the value double-quoted.
Enter the command string, then press Enter.
get_instance returns a table (dictionary) of properties for the ID entered.
The table (dictionary) includes the properties, pool, id and name, snapshot name, dataset, and the create transfer group.
Use the query command to locate the ID number for the share.
Where tank/minio@auto-2023-08-16_00-00 is the ID number for the snapshot.
sharing nfs get_instance id="tank/minio@auto-2023-08-16_00-00"
+---------------+----------------------------------+
| properties | <dict> |
| pool | tank |
| name | tank/minio@auto-2023-08-16_00-00 |
| type | SNAPSHOT |
| snapshot_name | auto-2023-08-16_00-00 |
| dataset | tank2/reptests |
| id | tank/minio@auto-2023-08-16_00-00 |
| createtxg | 27256 |
+---------------+----------------------------------+
Hold Command
The hold command holds a snapshot matching the ID entered. Holding a snapshot prevents it from being deleted.
Use the query command to locate the snapshot ID.
Use the release command to unlock the snapshot to remove the hold on the snapshot.
Description
hold has one required property, id.
Enter the property argument using the = delimiter separating the property and value, and the value double-quoted.
Enter the command string, then press Enter.
hold returns an empty line.
Usage
From the CLI prompt, enter:
storage snapshot hold id="tank/minio@auto-2023-08-16_00-00"
Where tank/minio@auto-2023-08-16_00-00 is the ID assigned to the share.
storage snapshot hold id="tank/minio@auto-2023-08-16_00-00"
Query Command
The query command returns a table (dictionary) of all snapshots on the system.
Description
query does not require entering property arguments.
Enter the command then press Enter.
The query returns a table (dictionary) of all snapshots on the system.
Information includes the ID, path, aliases, any comments, networks hosts, read only status, maproot user and group, mapall user and group, security, enabled, and locked status.
The release command removes the hold on a snapshot allowing it to be deleted.
Use the query command to locate the snapshot ID.
Description
release has one required property, id.
Enter the property argument using the = delimiter separating the property and value, and the value double-quoted.
Enter the command string, then press Enter.
The remove command removes a snapshot from a given dataset.
Use the query command to locate the snapshot ID.
The TrueNAS CLI guide for SCALE is a work in progress!
This command has not been fully tested and validated.
Full documentation is still being developed.
Check back for updated information.
Rollback Command
The rollback command replaces data in the specified dataset with the information saved in the snapshot matching the ID entered.
rollback has one required property, id.
Enter the property argument using the = delimiter separating the property and value, and the value double-quoted.
Enter the command string, then press Enter.
rollback returns an empty line.
The options property is a work in progress.
Use the query command to locate the ID number for the snapshot.
The TrueNAS CLI guide for SCALE is a work in progress!
This command has not been fully tested and validated.
Full documentation is still being developed.
Check back for updated information.
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 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.
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.
Description
The boot_id command does not require entering properties or arguments.
Enter the command, then press Enter.
The command returns a unique alphanumeric identifier.
Usage
From the CLI prompt, enter:
system 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.
Description
The build_time command does not require entering properties 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.
Usage
From the CLI prompt, enter:
system 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.
Description
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.
Usage
From the CLI prompt, enter:
system 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.
Description
The environment command does not require entering properties or arguments.
Enter the command, then press Enter.
The environment command returns the current environment in which the product is running.
The possible values are DEFAULT or EC2.
Usage
From the CLI prompt, enter:
system 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.
Description
The feature_enabled command uses the feature property 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.
Usage
From the CLI prompt, enter:
system feature_enabled feature=option
Where option is one of the system features, 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.
Description
The host_id command does not require entering properties or arguments.
Enter the command, then press Enter. The host_id command returns a string of alphanumeric characters.
Usage
From the CLI prompt, enter:
system 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
Description
The info command does not require entering properties 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.
Description
The is_stable command does not require entering properties or aguments.
Enter the command, then press Enter. The command returns true if stable, false if not.
Usage
From the CLI prompt, enter:
system 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.
Description
The license_update uses the license property to specify the license to update.
Enclose the license in double quotes.
Enter the command string, then press Enter. The command returns you to the CLI prompt.
Usage
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.
Description
The product_name command does not require entering properties or arguments.
Enter the command, then press Enter. The command returns TrueNAS as the product name.
Usage
From the CLI prompt, enter:
system product_name
system product_name
TrueNAS
Product_Type Command
The product_type command returns the name of the product (SCALE) in use.
Description
The product_type command does not require entering properties or arguments.
Enter the command, then press Enter. The command returns SCALE as the product name.
Usage
From the CLI prompt, enter:
system 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.
Description
The ready command does not require entering properties or arguments.
Enter the command, then press Enter. The command returns true if the boot completed an the system is ready.
Usage
From the CLI prompt, enter:
system 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.
Description
The reboot command does not require entering properties or arguments.
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.
Usage
From the CLI prompt, enter:
system 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.
Description
The shutdown command does not require entering properties or arguments.
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.
Usage
From the CLI prompt, enter:
system 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.
Description
The state command does not require entering properties or arguments.
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.
Usage
From the CLI prompt, enter:
system 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.
Description
The version command does not require entering properties or arguments.
Enter the command, then press Enter.
The command returns the full system software version, name, and number.
Usage
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.
Description
The version_short command does not require entering properties or arguments.
Enter the command, then press Enter.
The command returns only the system software version number.
Usage
From the CLI prompt, enter:
system 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: Introduces the TrueNAS CLI Config namespace that manages general configuration related settings found in the API and web UI.
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: Introduces the TrueNAS CLI general namespace that configures GUI and localization related settings found in the API and web UI.
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: Introduces the TrueNAS CLI Mail namespace that configures system email related settings found in the API and web UI.
NTP_Server: Provides information about the system ntp_server namespace in the TrueNAS CLI. Includes command syntax and common commands.
Reporting: Introduces the TrueNAS CLI Reporting namespace that configures system reporting database related settings found in the API and web UI.
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: Introduces the TrueNAS CLI truenas namespace that configures TrueNAS Enterprise service settings found in the API and web UI.
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.
Alert Namespace
The alert namespace has seven commands and is based on alert functions found in the SCALE API and web UI.
It provides access to alert management methods through the alert commands.
Alert Commands
The following alert commands allow you to view and manage alerts and policies.
You can enter commands from the main CLI prompt or from the alert namespace prompt.
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!
Interactive Argument Editor (TUI)
Enter the -- flag following any CLI command to open the interactive arguments editor text-based user interface (TUI).
Class Command
The class command allows you to view and update the default alert settings.
Description
The class command requires the config property to view current alert settings.
Enter the command then press Enter.
The command returns a table of current alert settings when successful.
Usage
From the CLI prompt, enter:
system alert class config
system alert class config
+---------+--------+
| id | 1 |
| classes | <dict> |
+---------+--------+
Description
The class command requires the update property and classes argument to update default alert settings.
Enter the command then press Enter.
The command returns a blank line when successful.
Usage
From the CLI prompt, enter:
system alert class update classes={"class":{"level":"LEVEL","policy":"POLICY"}}
Where:
class is the alert category class you want to update.
LEVEL is the alert level you want to apply.
POLICY is the alert notification frequency you want to apply.
system alert class update classes={"UPSBatteryLow":{"level":"INFO","policy":"HOURLY"}}
Dismiss Command
The dismiss command dismisses alerts based on alert UUID.
Description
The dismiss command requires the UUID property.
Enter the command then press Enter.
The command returns a blank line when successful.
Usage
From the CLI prompt, enter:
system alert dismiss uuid="alertuuid"
Where alertuuid is the UUID of the alert you want to dismiss.
The list command lists all types of alerts including active and dismissed currently in the system.
Description
The list command has no required properties.
Enter the command then press Enter.
The command returns a table of current alerts when successful.
Usage
From the CLI prompt, enter:
system alert list
system alert list
+--------------------------------------+-----------------+------------------+--------------------+--------------+------------------------+---------------------------+---------------------------+-----------+--------+------------------------------------------------------------------+--------------------------------------+----------+------------------------------------------------------------------+----------+
| uuid | source | klass | args | node | key | datetime | last_occurrence | dismissed | mail | text | id | level | formatted | one_shot |
+--------------------------------------+-----------------+------------------+--------------------+--------------+------------------------+---------------------------+---------------------------+-----------+--------+------------------------------------------------------------------+--------------------------------------+----------+------------------------------------------------------------------+----------+
| 59579a69-55a4-4cad-8d20-3bfceee2c4c5 | USBStorage | USBStorage | /dev/sr0 | Controller A | "/dev/sr0" | 2023-05-24T16:08:04+00:00 | 2023-09-19T19:06:48+00:00 | false | <null> | A USB storage device %r has been connected to this system. Pl... | 59579a69-55a4-4cad-8d20-3bfceee2c4c5 | CRITICAL | A USB storage device '/dev/sr0' has been connected to this sy... | false |
| a9a5ada0-0dde-42a0-b3c4-df878696e38a | | PoolUpgraded | tank | Controller A | "tank" | 2023-09-06T01:13:03+00:00 | 2023-09-06T01:13:03+00:00 | false | <null> | New ZFS version or feature flags are available for pool '%s'.... | a9a5ada0-0dde-42a0-b3c4-df878696e38a | WARNING | New ZFS version or feature flags are available for pool 'tank... | false |
| 949f4fd7-051a-481e-bdc0-d9dab216c9df | EnclosureStatus | EnclosureHealthy | R30 NVMe Enclosure | Controller A | ["R30 NVMe Enclosure"] | 2023-05-24T16:08:02+00:00 | 2023-09-19T19:06:48+00:00 | false | <null> | Enclosure (%s) is healthy. | 949f4fd7-051a-481e-bdc0-d9dab216c9df | INFO | Enclosure (R30 NVMe Enclosure) is healthy. | false |
| bd3afbac-fd91-4461-a346-6f05a8679d8b | | ScrubFinished | tank | Controller A | "tank" | 2023-09-03T07:00:08+00:00 | 2023-09-03T07:00:08+00:00 | false | <null> | Scrub of pool %r finished. | bd3afbac-fd91-4461-a346-6f05a8679d8b | INFO | Scrub of pool 'tank' finished. | true |
| 43f9025e-29c3-4a22-b95f-88186a4fd93b | | ScrubFinished | boot-pool | Controller A | "boot-pool" | 2023-09-18T10:45:04+00:00 | 2023-09-18T10:45:04+00:00 | false | <null> | Scrub of pool %r finished. | 43f9025e-29c3-4a22-b95f-88186a4fd93b | INFO | Scrub of pool 'boot-pool' finished. | true |
+--------------------------------------+-----------------+------------------+--------------------+--------------+------------------------+---------------------------+---------------------------+-----------+--------+------------------------------------------------------------------+--------------------------------------+----------+------------------------------------------------------------------+----------+
List_Categories Command
The list_categories command lists all types of alerts that the system can issue.
Description
The list_categories command has no required properties.
Enter the command then press Enter.
The command returns a table of alert types when successful.
The service command allows you to view and modify alert services.
The service command has seven options, but can only run one at a time. Alert service command options are create, delete, get_instance, list_types, query, test, and update.
Description
The service create command requires the name, type, attributes, level, and enabled properties.
Enter the command then press Enter.
The command returns a blank line when successful.
Property
Required
Description
Syntax Example
name
Yes
The name of the service.
name=name
type
Yes
The service type. View all types using the system alert service list_types command.
type=Type
attributes
Yes
Authentication attributes for the service. Required attributes vary depending on the service. Separate each attribute and value pair with a comma.
system alert service create name=name type=type attributes={"attribute":"value"} level=LEVEL enabled=true/false
Where:
name is the name you want to give the service.
type is the service type.
attributes are the authentication attributes for the service.
level is the alert level you want to assign to the service.
enabled turns the service on (true) or off (false).
service create name=NewAlertService type=PagerDuty attributes={"service_key":"u+Pgbsif8kE5rH5fzpXQ","client_name":"clientname"} level=INFO enabled=false
Description
The service delete command requires the id property.
Enter the command then press Enter.
The command returns a blank line when successful.
Usage
From the CLI prompt, enter:
system alert service delete id=number
Where number is the ID number of the alert service you want to delete.
system alert service delete id=1
Description
The service get_instance command requires the id property.
Enter the command then press Enter.
The command returns a table of settings for the identified alert service.
Usage
From the CLI prompt, enter:
system alert service get_instance id=number
Where number is the ID number of the alert service you want to view.
system alert service get_instance id=1
Description
The service list_types has no required properties.
Enter the command then press Enter.
The command returns a table of alert service types.
The service query command has no required properties.
Enter the command then press Enter.
The command returns a table of alert services when successful.
Usage
From the CLI prompt, enter:
system alert service query
system alert service query
+----+-----------+----------+------------+---------+---------+-------------+
| id | name | type | attributes | enabled | level | type__title |
+----+-----------+----------+------------+---------+---------+-------------+
| 1 | SNMP Trap | SNMPTrap | <dict> | true | WARNING | SNMP Trap |
| 2 | E-Mail | Mail | <dict> | true | WARNING | Email |
+----+-----------+----------+------------+---------+---------+-------------+
Description
Enter the service query command with one of the optional attributes to filter out other attributes from the query return.
See Query Attributes below for the list of seven available query attributes.
Enter the command string then press Enter.
The command returns a table with the specified attribute.
Attribute
Purpose
id
Alert service ID number.
name
Alert service name.
type
Alert service type.
attributes
Alert service authentication attributes.
enabled
Whether service is enabled or disabled.
level
Alert level for the service.
type__title
Alert service type name.
Usage
From the CLI prompt, enter:
system alert service query attribute
Where attribute is the query attribute you want to filter for.
system alert service query name
+-----------+
| name |
+-----------+
| SNMP Trap |
| E-Mail |
+-----------+
Description
The service test command with requires the alert_services_create argument with the name, type, and level attributes.
Enter the command string then press Enter.
The command returns true or false depending on if the test alert succeeded or not.
Usage
From the CLI prompt, enter:
system alert service test alert_services_create{“name”:"name", “type”:"type", “level”:"LEVEL"}
Where
name is the alert service name.
type is the service type.
level is the alert level for the service.
system alert service test alert_service_create={"name":"E-Mail","type":"Mail","level":"WARNING"}
true
Description
The update command requires entering id and has five optional properties.
See Update Command Properties below for details.
After specifying the id of the alert service you want to update, you must include at least one property to update.
Enter the command string, then press Enter.
The command returns nothing when successful.
Attribute
Purpose
id
Alert service ID number.
name
Alert service name.
type
Alert service type.
attributes
Alert service authentication attributes.
level
Alert level for the service.
enabled
Whether service is enabled or disabled.
Usage
From the CLI prompt, enter:
storage disk update id=number property=option
Where:
number is the ID number of the alert service you want to update.
option is any of the properties listed in the Update Command Properties table above.
system alert service update id=1 Name=NewName type=Mail attributes={"email":"newemail@mail.com"} level=INFO enabled=true
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!
Introduces the TrueNAS CLI Config namespace that manages general configuration 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!
Config Namespace
The config namespace has three commands and is based on configuration management functions found in the SCALE API and web UI.
It provides access to configuration management methods through the config namespace commands.
Config Commands
The following config namespace commands allow you to save or upload system configuration files and to reset configuration to default.
You can enter commands from the main CLI prompt or from the system namespace prompt.
Reset Command
The reset command reverts the system database to default configuration values.
Download the current system configuration with save before resetting the configuration to default settings!
If you do not save the system configuration before resetting it, you could lose data that was not backed up, and you cannot revert to the previous configuration.
The reset command can result in unexpected behavior if entered via Shell in the web UI, especially if reboot is set to false.
To avoid instability, only use reset via a direct connection to the console or SSH.
TrueNAS Enterprise
Enterprise High Availability (HA) systems should never reset their system configuration to defaults.
Contact iXsystems Support if a system configuration reset is required.
Customers who purchase iXsystems hardware or that want additional support must have a support contract to use iXsystems Support Services. The TrueNAS Community forums provides free support for users without an iXsystems Support contract.
The reset command has one optional property,options, which has one additional optional property, reboot. If not specified, reboot defaults to true.
Enter the reboot property argument enclosed within {} curly brackets following the options property: options={"reboot":true}. When reboot is true, the system reboots ten seconds after the job is completed.
Enter the command string then press Enter.
After entering the command correctly, the job begins and progress displays.
Usage
From the CLI prompt, enter:
system config reset
system config reset
[0%] ...
[5%] Removing cluster information (if any)...
[15%] Replacing database file...
[25%] Running database upload hooks...
[50%] Updating initramfs...
[95%] Will reboot in 10 seconds...
[100%] Will reboot in 10 seconds...
Save Command
The save command creates a tar file of security-sensitive configuration information and saves it to the specified location.
The configuration file contains sensitive data like system passwords.
Keep the configuration file safe and protect it from unauthorized access!
Description
save has one optional property, configsave, which has four additional optional properties (see table below).
Enclose array properties in {} curly brackets, with the property double-quoted and separated from the boolean value using the : delimiter.
Separate multiple array property arguments within the {} with a comma.
Enter the desired file name and path following a > carrot. Save the config file to a secure location that is accessible, such as an SMB share.
Enter the command string then press Enter.
After entering the command correctly, the cli displays the status of the job then confirms the output file is saved at the specified location.
Property
Required
Description
Syntax Example
secretseed
no
When true, the file includes the password secret seed. Including the password secret seed allows using this configuration file with a new boot device. This also decrypts all system passwords for reuse when the configuration file is uploaded.
"secretseed":true
pool_keys
n/a
pool_keys is ignored and depricated on TrueNAS SCALE systems.
n/a
root_authorized_keys
no
When true, the configuration file includes the “/root/.ssh/authorized_keys” file for the root user.
"root_authorized_keys":true
gluster_config
no
When true, the configuration file includes the directory that stores gluster configuration files.
"gluster_config":true
Usage
From the CLI prompt, enter:
system config save > /mnt/tank/test/FILENAME.tar
Where /mnt/tank/test/FILENAME.tar is the desired file name and save path.
system config save configsave={"secretseed":true,"root_authorized_keys":true,"gluster_config":true} > /mnt/tank/test/FILENAME.tar
[0%] ...
[100%] ...
[100%] Job output (786432 bytes) saved at '/mnt/tank/test/FILENAME.tar'
Upload Command
Do not use. Use the web UI to upload configuration files.
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.
Device Namespace
The device namespace has two commands.
It provides access to device information through the device commands.
Device Commands
The following device commands allow you to view properties for devices in your system.
You can enter commands from the main CLI prompt or from the device namespace prompt.
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!
Interactive Argument Editor (TUI)
Enter the -- flag following any CLI command to open the interactive arguments editor text-based user interface (TUI).
Get_Info Command
The get_info command returns details for a specified device type.
Description
The get_info command has one property, type.
Enter the type property argument using = to separate property and value.
Enter the command string then press Enter.
The command returns a table of device details when successful.
The gpu_pci_ids_choices retrieves choices for GPU PCI IDs in the system.
Description
The gpu_pci_ids_choices command has no required properties.
Enter the commands then press Enter.
The command returns a table of GPU PCI ID choices when successful.
Usage
From the CLI prompt, enter:
system device gpu_pci_ids_choices
+------------------------------------------------+--------------+
| ASPEED Technology, Inc. ASPEED Graphics Family | 0000:03:00.0 |
+------------------------------------------------+--------------+
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!
Introduces the TrueNAS CLI general namespace that configures GUI and localization 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!
General Namespace
The general namespace has 14 commands, and is based on general settings functions found in the SCALE API and web UI.
It provides access to GUI and localization configuration settings through the general namespace commands.
General Commands
The following general namespace commands allow you 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.
Checkin Command
The checkin command accepts pending settings.
Description
checkin does not require entering properties or arguments.
After UI settings are saved with rollback_timeout, see update properties, this method needs to be called within that timeout limit to prevent reverting the pending changes.
Enter the command string and then press Enter.
The command returns an empty line.
Usage
From the CLI prompt, enter:
system general checkin
Press Enter.
system general checkin
Checkin_waiting Command
The checkin_waiting command determines whether the system is waiting for a checkin to confirm pending changes.
Description
checkin_waiting does not require entering properties or arguments.
Enter the command string and then press Enter.
If UI settings are saved with rollback_timeout, see update properties, checkin_waiting returns the remaining time (in seconds) before the automatic rollback.
Returns null if there are no changes pending.
Usage
From the CLI prompt, enter:
system general checkin_waiting
Press Enter.
system general checkin_waiting
44
Config Command
The config command returns current UI configuration.
Description
config does not require entering properties or arguments.
Enter the command string and then press Enter.
Returns a table containing current UI and localization settings.
If UI settings are saved with rollback_timeout enabled, see update properties, the table includes any pending changes.
An automatic rollback reverts pending changes if checkin is not called before the timeout limit.
The country_choices command returns a list of available country options for use in creating certificates. See system certificate for more information.
Description
country_choices does not require entering properties or arguments.
Enter the command string and then press Enter.
Returns a table containing the available country codes for use in certificates.
Usage
From the CLI prompt, enter:
system general country_choices
Press Enter.
system general country_choices
+----+------------------------------------------------------------------+
| AF | Afghanistan |
| AL | Albania |
| DZ | Algeria |
| AD | Andorra |
| AO | Angola |
| AG | Antigua and Barbuda |
| AR | Argentina |
| AM | Armenia |
...
| SJ | Svalbard |
| AC | Ascension |
| TA | Tristan da Cunha |
| AQ | Australian Antarctic Territory + Ross Dependency + Peter I Is... |
+----+------------------------------------------------------------------+
Kbdmap_choices Command
The kbdmap_choices command returns a list of available keyboard map options.
Description
kbdmap_choices does not require entering properties or arguments.
Enter the command string and then press Enter.
Returns a table containing the available keyboard maps.
Usage
From the CLI prompt, enter:
system general kbdmap_choices
Press Enter.
system general kbdmap_choices
+-------------------------------+------------------------------------------------------+
| custom | A user-defined custom Layout |
| gh.akan | Akan |
| al | Albanian |
| al.plisi | Albanian (Plisi) |
| al.veqilharxhi | Albanian (Veqilharxhi) |
| et | Amharic |
| ara | Arabic |
...
| vn.us | Vietnamese (US) |
| sn | Wolof |
| ru.sah | Yakut |
| ng.yoruba | Yoruba |
+-------------------------------+------------------------------------------------------+
Language_choices Command
The language_choices command returns a list of available language translation options for the TrueNAS SCALE web UI.
Description
English is the default language in TrueNAS SCALE.
However, users can contribute text string translations for the TrueNAS web interface to help make TrueNAS available in other languages.
For all language options, the web UI defaults to English text if a translated string is not available.
See Web Interface Translations for more information.
language_choices does not require entering properties or arguments.
Enter the command string and then press Enter.
Returns a table containing the available languages.
Usage
From the CLI prompt, enter:
system general language_choices
Press Enter.
system general language_choices
+---------+----------------------+
| af | Afrikaans |
| ar | Arabic |
| ast | Asturian |
...
| ur | Urdu |
| vi | Vietnamese |
| zh-hans | Simplified Chinese |
| zh-hant | Traditional Chinese |
+---------+----------------------+
Local_url Command
The local_url command returns the current local URL configuration for the TrueNAS SCALE web UI.
Description
local_url does not require entering properties or arguments.
Enter the command string and then press Enter.
Returns the configured URL in the format of protocol://host:port.
Usage
From the CLI prompt, enter:
system general local_url
Press Enter.
system general local_url
https://8.8.8.8:443
Timezone_choices Command
The timezone_choices command returns a list of available timezone options for system localization.
Description
timezone_choices does not require entering properties or arguments.
Enter the command string and then press Enter.
Returns a table containing all available timezones.
The ui_restart command restarts the HTTP Server for the TrueNAS SCALE web UI.
This does not shut down and reboot the full system.
Description
New UI settings, configured via update, are not applied automatically.
Use ui_restart to apply settings, include the optional delay property to apply settings after an amount of time (in seconds), for example the amount of time you need to receive the response for your settings update request, or use the update property ui_restart_delay.
ui_restart has one available property, delay.
Enter the command string and press Enter.
The command returns a blank line.
After any specified delay is exceeded, the web server restarts.
The screen briefly displays a “Connecting to TrueNAS…” dialogue, then the UI returns.
Usage
From the CLI prompt, enter:
system general ui_restart delay=30
Where 30 is the amount of time (in seconds) to wait before the web server restarts.
Press Enter.
system general ui_restart delay=30
Ui_v6address_choices Command
The ui_v6address_choices command returns IPv6 address choices for the TrueNAS SCALE web UI.
Description
ui_v6address_choices does not require properties or arguments.
Enter the command string and then press Enter.
The command returns a table containing available addresses.
Usage
From the CLI prompt, enter:
system general ui_v6address_choices
Press Enter.
system general ui_v6address_choices
+----+----+
| :: | :: |
+----+----+
Update Command
The update command allows users to configure UI and localization settings for the TrueNAS SCALE web UI.
Description
update has 18 available properties, see the table below.
Connect properties and value pairs using an = sign, for example property=value.
Enclose values using special characters in double quotes, for example ui_address="0.0.0.0".
Separate multiple property and value pairs using a space.
List properties can accept a single value, for example ui_httpsprotocols="TLSv1.3", multiple values enclosed in square brackets [] and separated by a comma and space, for example ui_httpsprotocols=["TLSv1.2", “TLSv1.3”], or an empty list [] to clear current configuration, for example ui_httpsprotocols=[].
Enter the command string with all properties you want to update and press Enter.
update returns an empty line. Use config to confirm pending changes.
UI settings are not applied automatically.
Use ui_restart to apply new settings or set the ui_restart_delay property to automatically apply settings after a set time (in seconds).
Incorrect UI configuration can result in lost web UI or even API connectivity!
To avoid problems, specify a rollback_timeout in seconds.
If a checkin is not called before the rollback_timeout expires, the UI server automatically restarts and pending updates are reverted to previous settings.
Note: The automatic rollback only reverts UI settings. It does not affect localization properties, such as language or timezone.
Property
Required
Description
Syntax Example
ui_httpsport
No
Sets the port number for HTTPS connection to the web UI.
ui_httpsport=443
ui_httpsredirect
No
If true, all HTTP requests are redirected to HTTPS for enhanced security. A GUI SSL Certificate is required for HTTPS. Activating this also sets the HTTP Strict Transport Security (HSTS) maximum age to 31536000 seconds (one year). This means that after a browser connects to the web interface for the first time, the browser continues to use HTTPS and renews this setting every year.
List. Sets the port number for HTTP connection to the web UI.
ui_port=80
ui_address
No
List. Sets the IPv4 address for access to the web UI. Use ui_address_choices to view available options.
ui_address="0.0.0.0"
ui_v6address
No
List. Sets the IPv6 address for access to the web UI. Use ui_v6address_choices to view available options.
ui_v6address="::"
ui_allowlist
No
List. Sets IP addresses and Networks that are allowed to access the API and web UI. If this list is empty, then all IP addresses are allowed.
ui_allowlist=["8.8.8.8", “1.2.3.4”]
ui_consolemsg
No
Set to true to display console messages in real-time at the bottom of the web UI browser.
ui_consolemsg=true
ui_x_frame_options
No
Set to configure the UI <iframe> (inline frame) permissions. An <iframe> allows you to deploy the SCALE UI inside an HTML document. Options are SAMEORIGIN, DENY, and ALLOW_ALL.
ui_x_frame_options=ALLOW_ALL
kbdmap
No
Sets the keyboard map the UI uses. Use kbdmap_choices to view available options.
kbdmap=us
language
No
Sets the UI language option. Use language_choices to view available options.
language=en
timezone
No
Sets the timezone for localization purposes. Use timezone_choices to view available options.
timezone="US/Eastern"
usage_collection
No
Set to true to enable sending anonymous usage statistics to iXsystems. If set to null, config reports usage_collection as true and usage_collection_is_set as false.
usage_collection=true
birthday
No
Sets the epoch used for system time reference. Defaults to the Unix epoch, 1970-01-01T00:00:00+00:00. We suggest you do not change the default value.
ds_auth
No
Set to true to allow configured Directory Service users to log in to the web UI or use the API.
ds_auth=true
ui_certificate
No
Sets the SSL certificate the system uses to enable encrypted web interface connections. Identify the certificate using the integer associated with it in the results of ui_certificate_choices.
ui_certificate=1
rollback_timeout
No
Sets a timeout limit (in seconds) for you to review pending UI settings. If a checkin is not called before the rollback_timeout expires, the UI server automatically restarts and pending updates are reverted to previous settings.
Note: The automatic rollback only reverts UI settings. It does not affect localization properties, such as language or timezone.
rollback_timeout=60
ui_restart_delay
No
Sets a delay time (in seconds), such as the time needed to receive the response to your settings update request, after which the UI automatically restarts to apply pending changes. Set to 0 to restart immediately after the update command completes.
ui_restart_delay=20
Usage
From the CLI prompt, enter:
system general update property=value
Where property is the property to update and value is its configured value.
Press Enter.
system general update language=en timezone="US/Eastern" rollback_timeout=60 ui_restart_delay=5
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!
Init_shutdown Namespace
The init_shutdown namespace has 5 commands, and is based on init/shutdown script functions found in the SCALE API and web UI.
It provides access to init/shutdown script management methods through the init_shutdown namespace commands.
Init/shutdown scripts are capable of making OS-level changes and can be dangerous when done incorrectly. Use caution before creating script or command tasks.
The following init_shutdown namespace commands allow you to create, view, update, and delete init/shutdown script tasks.
You can enter commands from the main CLI prompt or from the system namespace prompt.
Create Command
The create command creates a new init/shutdown script task.
Init/shutdown scripts allow you to run scripted tasks before or after initialization (start-up), or at shutdown.
All init/shutdown scripts run using sh(1).
Description
create has two required properties, type and when, and three optional properties (see Create Properties below).
type has two possible values, SCRIPT or COMMAND, that each require one additional property.
SCRIPT requires either the script or script_text property.
COMMAND requires the command property.
Enter all required and any optional properties you want, surround string values with double quotes ", and then press Enter.
Property
Required
Description
Syntax Example
type
Yes
Specifies the type of init/shutdown task. Options are SCRIPT or COMMAND.
type=SCRIPT
command
Yes*
Required when type is COMMAND. Enter a command with any options you want or the path to a command stored on the system.
command="touch /mnt/tank/data/cmdTest.txt"
script_text
Yes*
Either script_text or script is required when type is SCRIPT. Enter the full text for the script.
script_text="touch /mnt/tank/data/ScriptTest.txt"
script
Yes*
Either script_text or script is required when type is SCRIPT. Enter the path to a script stored on the system.
Enter when the script should execute. Options are:
PREINIT – early in the boot process, before services have started
POSTINIT – late in the boot process, when most services have started
SHUTDOWN – on shutdown
when=SHUTDOWN
enabled
No
Set to false to create the script but not enable it. Defaults to true.
enabled=true
timeout
No
Enter the time (in seconds) that the system should wait for the script or command to execute. Default value is 10.
Note: A hard timeout limit is configured by the base OS, so when a script or command is set to execute on SHUTDOWN, the timeout specified by script or command is added to the base timeout, so that it is not interrupted by the base limit.
timeout=10
comment
No
Enter a human-readable description for the command or script.
comment="Shutdown Task"
Usage
From the CLI prompt, enter:
system init_shutdown_script create type=SCRIPTscript="path/to/file.sh" when=SHUTDOWN
Where SCRIPT is the task type, script is the property for defining the task, path/to/file.sh is the path to an executable script, and SHUTDOWN is when the task executes.
Press Enter.
Returns an empty line when successful.
Use query to confirm the task was created.
Always test the script to verify it executes and achieves the desired results.
system init_shutdown_script create type=SCRIPT script="path/to/file.sh" when=SHUTDOWN comment="Shutdown Task"
Delete Command
The delete command removes an existing init/shutdown script task.
Description
delete has one required property, id.
Use query to view the id numbers for existing script or command tasks.
Enter the command string and press Enter.
Deletes the task matching id.
Usage
From the CLI prompt, enter:
system init_shutdown_script delete id=1
Where 1 is the id of the task to delete.
Press Enter.
delete returns an empty line.
Use query or get_instance to confirm the task is deleted.
system init_shutdown_script delete id=1
Get_instance Command
The get_instance command returns configured settings for an existing init/shutdown script task.
Description
get_instance has one required property, id.
Use query to view the id numbers for existing script or command tasks.
Enter the command string and press Enter.
get_instance returns a table containing information about the task matching id.
The update command modifies configured settings for an existing init/shutdown script task.
Description
update has one required property, id, and eight optional properties.
Use query to view the id numbers for existing script or command tasks.
For optional properties, see the create properties.
Enter the command string with any optional properties you want to update and then press Enter.
Usage
From the CLI prompt, enter:
system init_shutdown_script update id=1property=value
Where 1 is the id of the task to update, property is one of the configuration properties, and value is the new setting for that property.
Press Enter.
update returns an empty line.
Use query or get_instance to confirm the task is deleted.
[truenas] system init_shutdown_script> update id=1 when=PREINIT
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!
Introduces the TrueNAS CLI Mail namespace that configures system email 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!
Mail Namespace
The mail namespace has three commands and is based on configuration management functions found in the SCALE API and web UI.
It provides access to email configuration methods through the system namespace commands.
Mail Commands
The following mail commands allow you to view or edit mail settings and to send an email using configured settings.
You can enter commands from the main CLI prompt or from the system namespace prompt.
Config Command
The config command displays the current system email configuration.
Description
config does not require entering properties or arguments.
Enter the command and then press Enter.
The command returns a table containing current email configuration settings.
The send command sends an email from the system. A valid email send method must be configured before sending an email.
Description
The send command has one required property, mail_message, which has two required sub-properties, subject and text, and nine optional sub-properties (see chart below), and one optional property, mail_update, which uses the same properties as the update command.
Enter mail_message or mail_update properties as an array enclosed in curly brackets {}.
Enclose properties and values in double quotes, do not double quote boolean values, separate properties from values using a colon, and separate property/value pairs using a comma.
Property
Required
Description
Syntax Example
subject
Yes
Enter a subject for the email.
“subject”:"test"
text
Yes*
Required if html is not set. Enter the email body text. Text is formatted to HTML using Markdown and rendered using the default email template.
“text”:"Test message"
html
Yes*
Required if text is not set. Enter the email body text and HTML formatting.
“html”:"Some HTML"
to
No
Enter the address to receive the email. If not set, defaults to the configured admin email address.
“to”:"test@email.com"
cc
No
Enter an address to carbon copy (CC) on the email.
“cc”:"test@email.com"
interval
No
Use to define a minimum interval in seconds for the email job to forbid duplicate emails within a given time frame. Defaults to null.
“interval”:"60"
channel
No
Enter the name of the channel to receive the email, if needed.
“channel”:"notifications"
timeout
No
Enter the send operation timeout limit in seconds. If not set, timeout defaults to 300, or five minutes.
“timeout”:"300"
attachments
No
Full documentation for this property is being developed.
queue
No
Set true to allow email queuing or false to disallow. Defaults to true.
“queue”:false
extra_headers
No
Use to specify any additional email headers, such as to designate the email priority.
“extra_headers”:{"priority":"urgent"}
Usage
From the CLI prompt, enter:
system mail send mail_message={“subject”:"test",“text”:"Test message"}
Where test is the email subject and Test message is the email body text.
Press Enter.
system mail send mail_message={"subject":"test","text":"Test message."}
[0%] ...
[100%] ...
true
Update Command
The update command configures the system email send method using either SMTP or OAuth.
Description
update has 9 optional properties (see the tables in Update Properties below).
Enter the command followed by one or more property/value pairs.
Enclose any values using special characters, for example a period . or @ in double quotes.
Separate multiple property/value pairs with a space.
To configure the system email using SMTP, enter the mail update command followed by the SMTP properties.
To configure using OAuth, first obtain a valid OAuth token from your email provider.
For example, see Authenticating with Google services.
Enter the mail update command with the property OAuth followed by an array containing the client_id, client_secret, and refresh_token properties and values from the token.
The TrueNAS SCALE web UI provides a streamlined experience for Gmail OAuth authentication. See Setting Up System Email for details.
Press Enter.
The command returns an empty line.
Use config to view updated configuration and send to confirm configuration by sending a test email.
The name to show in front of the sending email address, for example: TrueNAS.
fromname=TrueNAS
outgoingserver
Yes
Host name or IP address of SMTP server to use for sending emails.
outgoingserver="smtp.mailserver.com"
port
Yes
SMTP port number. Typically 25, 465 (secure SMTP), or 587 (submission).
port=587
security
No
Enter the security type to use. Options are PLAIN (no encryption), SSL (Implicit TLS), or TLS (STARTTLS). See email encryption for more information on types.
security=TLS
smtp
No
Set to true to enable SMTP AUTH using PLAIN SASL. Requires a valid user name and password.
smtp=true
user
Yes*
Required when smtp is true. The user name for the sending email account, typically the full email address.
user="test@test.com"
pass
Yes*
Required when smtp is true. The password for the sending email account.
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!
Introduces the TrueNAS CLI Reporting namespace that configures system reporting database 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!
Reporting Namespace
The reporting namespace has 3 commands, and is based on system reporting functions found in the SCALE API and web UI.
It provides access to reporting database configuration methods through the reporting namespace commands and the child namespaces and their commands.
To view reporting graphs, go to Reporting in the TrueNAS SCALE web UI.
Reporting Commands
The following reporting namespace commands allow you to configure the system reporting database.
You can enter commands from the main CLI prompt or from the system namespace prompt.
Clear Command
The clear command erases all existing data from the system reporting database.
Description
clear does not require entering properties or arguments.
Enter the command string and then press Enter.
Usage
From the CLI prompt, enter:
system reporting clear
Press Enter.
The command returns an empty line.
system reporting clear
Config Command
The config command returns the current system reporting configuration.
Description
config does not require entering properties or arguments.
Enter the command string and then press Enter.
Usage
From the CLI prompt, enter:
system reporting config
Press Enter.
Returns a table containing current configuration properties.
The update command allows you to change system reporting configuration settings.
Description
update has 5 optional properties, see table below.
Separate multiple properties with a single space.
Enter the full command string and then press Enter.
Property
Required
Description
Syntax Example
graphite
No
Graphite integration is deprecated in TrueNAS SCALE 23.10 (Cobia).
graphite_separateinstances
No
Graphite integration is deprecated in TrueNAS SCALE 23.10 (Cobia).
graph_age
No
Sets the maximum age of stored reporting graphs in months. Requires the confirm_rrd_destroy=true flag to erase existing reporting data.
graph_age=12
graph_points
No
Sets the number of points for each hourly, daily, weekly, monthly, and yearly graph. Requires the confirm_rrd_destroy=true flag to erase existing reporting data.
graph_points=1200
confirm_rrd_destroy
Yes*
Required for either graph_age or graph_points. Erases all existing reporting database data.
confirm_rrd_destroy=true
Usage
From the CLI prompt, enter:
system reporting update graph_age=12 graph_points=1200 confirm_rrd_destroy=true
Where 12 is the maximum age of stored graphs in months and 1200 is the number of points for each graph.
Press Enter.
The command returns an empty line.
Use config to confirm changes.
system reporting update graph_age=12 graph_points=1200 confirm_rrd_destroy=true
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!
Introduces the TrueNAS CLI truenas namespace that configures TrueNAS Enterprise service 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!
TrueNAS Namespace
TrueNAS Enterprise
On licensed systems, use the truenas namespace for viewing or modifying Enterprise customer service details.
Systems without an Enterprise license do not use this namespace.
The truenas namespace has five commands and is based on TrueNAS Enterprise functions found in the SCALE API and web UI.
It provides access to Enterprise customer management methods through the truenas namespace commands.
TrueNAS Commands
The following truenas namespace commands allow you to accept the TrueNAS EULA, modify Enterprise customer information, and control system production status.
You can enter commands from the main CLI prompt or from the system namespace prompt.
Interactive Argument Editor (TUI)
Enter the -- flag following any CLI command to open the interactive arguments editor text-based user interface (TUI).
accept_eula does not require entering properties or arguments.
Enter the command then press Enter.
The command returns an empty line.
Usage
From the CLI prompt, enter:
system truenas accept_eula
system truenas accept_eula
Get_customer_information Command
The get_customer_information command returns a table of stored customer information.
Description
get_customer_information does not require entering properties or arguments.
Enter the command then press Enter.
The command returns a table containing Enterprise customer information.
The is_production command returns if the system is marked as a production system.
Description
is_production does not require entering properties or arguments.
Enter the command then press Enter.
The command returns either a true or false output.
True indicates the system is a production system. False indicates the system is not.
Usage
From the CLI prompt, enter:
system truenas is_production
system truenas is_production
true
Set_production Command
The set_production command adds or removes in-production status from the system and creates a ticket to notify iXsystems Support that the system is ready for use in production.
Description
set_production has one required property, production, and one optional property, attach_debug, to include in the command string.
The production property uses a boolean value to set production as true or false.
The attach_debug property uses a boolean value to include a debug file in the support ticket.
If attach_debug is set to true, TrueNAS automatically creates and attaches a debug file to the ticket.
Enter the property argument using the = delimiter to separate the property and value. Separate multiple property arguments with a space.
Enter the command string then press Enter
Usage
From the CLI prompt, enter:
system truenas set_production production=true attach_debug=true
The update_customer_information command modifies stored customer information.
The TrueNAS CLI guide for SCALE is a work in progress!
This command has not been fully tested and validated.
Full documentation is still being developed.
Check back for updated information.
Description
update_customer_information has one required property, customer_information_update.
customer_information_update has seven properties, four of which have additional configurable properties (see the Customer_information_update Properties below).
If entering a command string, enter the command then press Enter.
When making complex changes, enter update_customer_information -- to use the interactive arguments editor.
The command returns a chart of stored customer information.
Property
Required
Description
Syntax Example
company
no
Enter the company name for the customer.
“company”:"Name"
administrative_user
no
Enter identification information for the system administrator. Properties:
first_name
last_name
title
office_phone
mobile_phone
primary_email
secondary_email
address
city
state
zip
country
Use the interactive arguments editor.
technical_user
no
Enter identification information for the system technical user or a second adminstrative contact person. Properties:
first_name
last_name
title
office_phone
mobile_phone
primary_email
secondary_email
address
city
state
zip
country
Use the interactive arguments editor.
reseller
no
Enter identification information for the system reseller, if applicable. Properties:
company
first_name
last_name
title
office_phone
mobile_phone
Use the interactive arguments editor.
physical_location
no
Enter the physical location of the system. Properties:
address
city
state
zip
country
contact_name
contact_phone_number
contact_email
Use the interactive arguments editor.
primary_use_case
no
Enter the primary use-case for the system.
“primary_use_case”:"use1"
other_primary_use_case
no
Enter the another primary or a secondary use-case for the system.
“primary_use_case”:"use2"
Usage
From the CLI prompt, enter:
system truenas update_customer_information customer_information_update={“company”:"Name", “primary_use_case”:"use1", “other_primary_use_case”:"use2"}
Where Name is the customer company, use1 is the primary use-case for the system, and use2 is the other primary or secondary use-case for the system.
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!
The update namespace allows users to locate pending updates or available trains and to update the TrueNAS SCALE release using the CLI. to find existing ACL templates, create new or
Update Commands
The update namespace has 10 commands and is based on functions found in the SCALE API and web UI.
You can enter commands from the main CLI prompt or from the update namespace prompt.
Check_Available Command
Use the check_available command to see if updates are available for the release train specified.
Use the get_trains command to see the current and selected train dictionary for the system.
The TrueNAS CLI guide for SCALE is a work in progress!
This command has not been fully tested and validated.
Full documentation is still being developed.
Check back for updated information.
Download Command
The download command downloads the updates for the selected train.
Description
The download command does not require entering a property or argument
Enter the command, then press Enter.
The command begins downloading any updates from the current train and shows the status in percentage downloaded.
If an update is not available the system displays an error, then the CLI prompt.
Usage
From the command prompt, enter:
system update download
system update download
[0%]...
[0%] Retrieving update manifest...
File Command
The file command updates the system using an uploaded file.
The TrueNAS CLI guide for SCALE is a work in progress!
This command has not been fully tested and validated.
Full documentation is still being developed.
Check back for updated information.
Get_Auto_Download Command
The get_auto_download command returns the status of the auto download function is enabled.
Description
The get_auto_download command does not require entering a property or argument.
Enter the command, then Enter.
The command returns true if auto download is enabled, false if not.
Usage
From the command prompt, enter:
system update get_auto_download
system update get_auto_download
true
Get_Pending Command
The get_pending command returns a table with a list of packages already downloaded and ready to apply.
The TrueNAS CLI guide for SCALE is a work in progress!
This command has not been fully tested and validated.
Full documentation is still being developed.
Check back for updated information.
Description
The get_pending command has one optional property, path.
Enter a property argument using = to separate property and value.
Enter the command or command string, then press Enter.
The command returns a table listing the operation, old and new upgrade packages (files).
Usage
From the command prompt, enter:
system update get_pending
system update get_pending
+-----------+--------+--------+
| operation | old | new |
+-----------+--------+--------+
| upgrade | <dict> | <dict> |
+-----------+--------+--------+
Get_Trains Command
The get_trains command shows the available trains dictionary, the currently configured train and the train of the current boot environment on the system.
The `get_trains command does not require entering properties or arguments.
Enter the command, then press Enter.
The command returns a table with the trains dictionary, currently configured train, and selected train of the current boot environment on the system.
Usage
From the command prompt, enter:
system update get_trains
system update get_trains
+----------|--------------------------|
| trains | <dict> |
| current | TrueNAS-SCALE-Cobia-BETA |
| selected | TrueNAS-SCALE-Cobia-BETA |
+----------|--------------------------|
Manual Command
The manual command updates the system using a manual update file downloaded from the SCALE release train and uploaded to the system using a file transfer program.
The TrueNAS CLI guide for SCALE is a work in progress!
This command has not been fully tested and validated.
Full documentation is still being developed.
Check back for updated information.
Update Command
The update command downloads an update, if not already in the cache, and then applies it.
Description
The update command does not require entering a property or argument.
Enter the command, then press Enter.
The system begins the download and upgrade process.
If an update is not available the screen shows an error, aborts the process, and returns to the CLI prompt.
Usage
From the command prompt, enter:
system update update
system update update
[0%]
[0%] Retrieving update manifest...
Introduces the TrueNAS CLI task namespace and provides access to child namespaces and commands including cloud_sync, cron_job, replication, rsync, smart_test, and snapshot.
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.
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 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.
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!
Snapshot Namespace
The snapshot namespace has 11 commands and is based on snapshot creation and management functions found in the SCALE API and web UI.
It provides access to periodic snapshot task methods through the snapshot commands.
Snapshot Commands
The following snapshot commands allow you to create new and manage existing periodic snapshot tasks.
You can enter commands from the main CLI prompt or from the task snapshot namespace prompt.
Interactive Argument Editor (TUI)
Enter the -- flag following any CLI command to open the interactive arguments editor text-based user interface (TUI).
Create Command
The create command creates a periodic snapshot task for a given dataset at the specified schedule.
Description
create has six required properties and two optional properties.
The Create Command Properties section below lists the properties and provides syntax examples.
Enter a property argument using the = delimiter to separate property and value. Enter string values in double quotes.
Alternatively, enter -- after entering task snapshot create to use the interactive arguments editor (TUI) and simplify entering the required and optional command properties.
Enter the command string then press Enter.
create returns an empty line.
Use the query command to verify the snapshot task was created and to view details on the task.
Use these properties when creating a snapshot.
Property
Required
Description
Syntax Example
dataset
Yes
Enter the dataset path (pool/dataset) the task takes a snapshot of. Enclose the path in double quotes.
dataset="tank/minio"
recursive
Yes
Enter true to include child datasets of the chosen dataset or false to exclude child datasets.
recursive=true or recursive=false
exclude
No
Used with recursive=true to enter child datasets to exclude from the snapshot. Enter a child dataset name in double quotes. If entering multiple child datasets, use a comma and space to separate each entry.
exclude="child1", “child2"
lifetime_value
Yes
Use with lifetime_unit to define the lifetime of the snapshot, the length of time to keep the snapshot on this system. After the time expires, the system removes snapshot. Snapshots replicated to other systems are not affected. lifetime_unit defines the unit of measure and lifetime_value specifies the duration. For example, lifetime_value=2 and lifetime_unit=weeks retains the snapshot for two weeks.
lifetime_value=365
lifetime_unit
Yes
Use with lifetime_value to define the lifetime of the snapshot, the length of time to keep the snapshot on this system. After the time expires, the system removes the snapshot. Snapshots replicated to other systems are not affected. lifetime_unit defines the unit of measure and lifetime_value specifies the duration. For example, lifetime_value=364 and lifetime_unit=DAY retains the snapshot for 364 days. Lifetime units are HOUR, DAY, WEEK, MONTH, and YEAR.
lifetime_unit=DAY
naming_schema
Yes
Enter a naming schema to generate a name for the snapshot instead of using name. Enter a new schema in double-quotes, the default auto-%Y-%m-%d_%H-%M schema, or a naming schema from a previously created periodic snapshot task. This allows replication of the snapshot. Naming schema must include the year %Y, month %m,day %d, hour %H, and minute %M. This adds the four-digit year, month, day of month, hour, and minute as defined in strftime(3).
naming_schema="custom-%Y-%m-%d_._%H-%M"
schedule
Yes
Enter an array of properties that specify the date and time when the task runs and creates the snapshot. The default setting is to run the task daily at 00:00 (0 0 * * *). Enter {} without property arguments to accept default values for schedule properties, or enter each property argument enclosed in square brackets with double-quoted properties and values. Separate each array property argument enclosed in square brackets [] with a comma and space. Properties are:
minute specified in the format of minutes:seconds or use the default 00:00
hour specified in the format of 00 (0-23) or use the default * for every hour.
dom specifies the day of month in the format of jan through dec or use the default * for every month.
month specifies the month in the format of jan or use the default * for any month.
dow specifies the day(s) of week as sun, mon, tue, wed, thu, fri, or sat or use the default * for every day of the week.
begin specifies the earliest time the task starts in hour:minute or use the default 00:00.
end specifies the latest time the task can end in hour:minute or use the default 00:00.
Command example shows the default values for each property in the object array.
Enter true to create dataset snapshots even when there are no changes to the dataset from the last snapshot. Recommended for creating long-term restore points, multiple snapshot tasks pointed at the same datasets, or to be compatible with snapshot schedules or replications created in TrueNAS 11.2 and earlier. For example, allowing empty snapshots for a monthly snapshot schedule allows taking that monthly snapshot, even when a daily snapshot task has already taken a snapshot of changes to the dataset. Enter false to only take snapshots of datasets with data changes.
allow_empty=true or allow_empty=false
enabled
No
Enter true to activate this periodic snapshot task schedule or false to disable this task without deleting it.
The delete command deletes a snapshot task matching the ID entered.
Use the query command to locate the snapshot task ID.
To disable a task but not delete it, use the update command enable=false property argument.
Description
delete has one required property, id.
Enter the property argument using the = delimiter separating the property and value.
Enter the command string then press Enter.
The delete_will_change_retention_for command returns a list of snapshots that have their retention influenced by deleting a given snapshot.
Use this command before the delete command to verify other snapshot tasks on the system that might be adversely affected.
Description
delete_will_change_retention_for has one required property, id.
Enter the property argument using the = delimiter separating the property and value.
Enter the command string then press Enter.
The forseen_count command returns a list of snapshots that change the retention of the periodic snapshot task for the ID specified.
The TrueNAS CLI guide for SCALE is a work in progress!
This command has not been fully tested and validated.
Full documentation is still being developed.
Check back for updated information.
Get_Instance Command
The get_instance command retrieves information for a snapshot task matching the id entered in the command string.
Use to verify properties for the snapshot.
Use the query command to find the list of snapshots and the ID for a snapshot task.
Description
get_instance has one required property, id.
Enter the property argument using the = delimiter separating the property and value.
Enter the command string then press Enter.
get_instance returns a table (dictionary) of properties for the ID entered.
The table (dictionary) includes the task ID, dataset, lifetime value and unit, naming schema, and schedule, and the state for recursive, enabled, allow_empty, vmware_sync, and the entries for exclude and state.
Use the query command to locate the ID number for the share.
The max_count command returns the maximum number of snapshots per dataset the system can sustain.
Description
max_count does not require entering property arguments.
Enter the command then press Enter.
max_count returns a numeric value.
Usage
From the CLI prompt, enter:
task snapshot max_count
task snapshot max_count
512
Max_Total_Count Command
The max_total_count command returns the maximum number of snapshots the system can sustain.
Description
max_total_count does not require entering property arguments.
Enter the command then press Enter.
max_total_count returns a numeric value.
Usage
From the CLI prompt, enter:
task snapshot max_total_count
task snapshot max_total_count
10000
Query Command
The query command returns a table (dictionary) of all snapshot tasks on the system.
Description
query does not require entering property arguments.
Enter the command then press Enter.
The query returns a table (dictionary) of all snapshot tasks on the system.
Information includes the snapshot task ID, dataset path, recursive and encludes settings, lifetime value and unit settings, enabled, allow_empty and vmware_sync on/off state, naming schema, and state status.
The run command starts the snapshot task for the task ID entered.
Use the query command to locate the snapshot task ID.
Description
The run command has one required property, id.
Enter the property argument using the = delimiter separating the property and value.
Enter the command string then press Enter.
run returns an empty line.
Usage
From the CLI prompt, enter:
task snapshot run id=11
Where 11 is the ID assigned to the snapshot task.
task snapshot run id=11
Update Command
The update command updates the task matching the task ID entered.
Use the query command to find the list of snapshot tasks and the task ID.
Use the get_instance command to list the properties of the task ID before and after making changes to verify the task configuration.
The TrueNAS CLI guide for SCALE is a work in progress!
This command has not been fully tested and validated.
Full documentation is still being developed.
Check back for updated information.
The update has one required property, id.
Enter any of the property arguments found in the Create Command Properties table to change the task settings.
Enter the property argument for id using = to separate the property and value.
Enter property arguments with string values with the value double-quoted.
Enclose property arguments with array values in curly brackets {}, then enclose each property argument in square brackets [] and separate each with a comma and space.
Double-quote each property and value and using the = delimiter to separate them.
Alternatively, enter the -- after the id property to open the interactive arguments editor (TUI).
Enter the command string then press Enter.
update returns an empty line.
Use the get_instance command to verify the changes made to the task.
Usage
To add or change a comment for a share, from the CLI prompt, enter:
The update_will_change_retention_for command returns a list of snapshots that have their retention influenced by deleting a given snapshot.
The TrueNAS CLI guide for SCALE is a work in progress!
This command has not been fully tested and validated.
Full documentation is still being developed.
Check back for updated information.
