TrueNAS SCALETrueNAS SCALE Version Documentation
This content follows the TrueNAS SCALE 23.10 (Cobia) releases. Use the Product and Version selectors above to view content specific to different TrueNAS software or major version.

General

  12 minute read.

Last Modified 2024-03-19 08:38 EDT

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.

Usage

From the CLI prompt, enter:

system general config

Press Enter.

system general config
+-------------------------+---------------------------+
|                      id | 1                         |
|                language | en                        |
|                  kbdmap | us                        |
|                birthday | 1970-01-01T00:00:00+00:00 |
|                timezone | America/Los_Angeles       |
|             wizardshown | false                     |
|        usage_collection | true                      |
|                 ds_auth | false                     |
|              ui_address | 0.0.0.0                   |
|            ui_v6address | ::                        |
|            ui_allowlist | <empty list>              |
|                 ui_port | 80                        |
|            ui_httpsport | 443                       |
|        ui_httpsredirect | false                     |
|       ui_httpsprotocols | TLSv1.2                   |
|                         | TLSv1.3                   |
|      ui_x_frame_options | SAMEORIGIN                |
|           ui_consolemsg | false                     |
|          ui_certificate | <dict>                    |
| usage_collection_is_set | false                     |
+-------------------------+---------------------------+

Country_choices Command

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.

Usage

From the CLI prompt, enter:

system general timezone_choices

Press Enter.

system general timezone_choices
+----------------------------------+----------------------------------+
|                   Africa/Abidjan | Africa/Abidjan                   |
|                     Africa/Accra | Africa/Accra                     |
|               Africa/Addis_Ababa | Africa/Addis_Ababa               |
|                   Africa/Algiers | Africa/Algiers                   |
|                    Africa/Asmara | Africa/Asmara                    |
...
|                              UTC | UTC                              |
|                        Universal | Universal                        |
|                             W-SU | W-SU                             |
|                              WET | WET                              |
|                             Zulu | Zulu                             |
+----------------------------------+----------------------------------+

UI_address_choices Command

The ui_address_choices command returns IPv4 address options for the TrueNAS SCALE UI.

Description

ui_address_choices does not require entering properties or arguments.

Enter the command string and then press Enter.

Returns a table containing the available addresses.

Usage

From the CLI prompt, enter:

system general ui_address_choices

Press Enter.

system general ui_address_choices
+---------+---------+
| 0.0.0.0 | 0.0.0.0 |
+---------+---------+

Ui_certificate_choices Command

The ui_certificate_choices command returns a list of certificates which can be used for configuring ui_certificate (see update properties).

Description

ui_certificate_choices does not require entering properties or arguments.

Enter the command string and then press Enter.

The command returns a table containing available certificate options.

Usage

From the CLI prompt, enter:

system general ui_certificate_choices

Press Enter.

system general ui_certificate_choices
+---+-----------------+
| 1 | truenas_default |
+---+-----------------+

Ui_httpsprotocols_choices Command

The ui_httpsprotocols_choices command returns a table of available HTTPS protocols for the TrueNAS SCALE web UI.

Description

ui_httpsprotocols_choices does not require entering properties or arguments.

Enter the command string and press Enter.

The command returns a table containing available protocols.

Usage

From the CLI prompt, enter:

system general ui_httpsprotocols_choices

Press Enter.

system general ui_httpsprotocols_choices
+---------+---------+
|   TLSv1 | TLSv1   |
| TLSv1.1 | TLSv1.1 |
| TLSv1.2 | TLSv1.2 |
| TLSv1.3 | TLSv1.3 |
+---------+---------+

Ui_restart Command

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.

PropertyRequiredDescriptionSyntax Example
ui_httpsportNoSets the port number for HTTPS connection to the web UI.ui_httpsport=443
ui_httpsredirectNoIf 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.ui_httpsredirect=true
ui_httpsprotocolsNoList. Sets the Transport Layer Security (TLS) versions TrueNAS SCALE can use for connection security. Use ui_httpsprotocols_choices to view available options.ui_httpsprotocols=["TLSv1", “TLSv1.1”, “TLSv1.2”, “TLSv1.3”]
ui_portNoList. Sets the port number for HTTP connection to the web UI.ui_port=80
ui_addressNoList. 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_v6addressNoList. Sets the IPv6 address for access to the web UI. Use ui_v6address_choices to view available options.ui_v6address="::"
ui_allowlistNoList. 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_consolemsgNoSet to true to display console messages in real-time at the bottom of the web UI browser.ui_consolemsg=true
ui_x_frame_optionsNoSet 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
kbdmapNoSets the keyboard map the UI uses. Use kbdmap_choices to view available options.kbdmap=us
languageNoSets the UI language option. Use language_choices to view available options.language=en
timezoneNoSets the timezone for localization purposes. Use timezone_choices to view available options.timezone="US/Eastern"
usage_collectionNoSet 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
birthdayNoSets 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_authNoSet to true to allow configured Directory Service users to log in to the web UI or use the API.ds_auth=true
ui_certificateNoSets 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_timeoutNoSets 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_delayNoSets 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

Related CLI System Articles

Related System Settings Articles