Get a Quote     (408) 943-4100   TrueNAS Discord VendOp_Icon_15x15px Commercial Support
TrueNAS.com Software Systems Company Community Security iX Portal Download
TrueNAS CORE TrueNAS Enterprise TrueNAS SCALE Compare Editions TrueCommand Software Status FreeNAS
Compare Systems F-Series M-Series X-Series R-Series Mini Series
About iXsystems Our Clients Reviews Careers Awards iX Blog & News iX Website Contact Us
Community Forum Discord TrueNAS GitHub TrueNAS Merch Store
Application Analytics Backup and Archival Cloud Data Mobility File Sharing iX Storj Media Creation Video Surveillance Virtualization
Industry Automotive Education Gaming Government Healthcare MSP Manufacturing Research & AI Media & Entertainment
Download TrueNAS CORE Download TrueNAS SCALE Get TrueNAS Enterprise Compare TrueNAS Editions Where to Buy
  1. Documentation Hub
  2. /
  3. TrueNAS SCALE
  4. /
  5. CLI Reference Guide
  6. /
  7. System
  8. /
  9. Boot
Edit page
TrueNAS SCALETrueNAS SCALE Nightly Development Documentation
This content follows experimental early release software. Use the Product and Version selectors above to view content specific to a stable software release.

Boot

  7 minute read.

Last Modified 2024-04-24 11:56 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!

Boot Namespace

The boot namespace has eight commands and is based on boot pool management functions found in the SCALE API and web UI. It provides access to system boot pool methods through the boot commands.

Boot Commands

The following boot commands allow you to run jobs related to the boot pool and manage the boot pool.

You can enter commands from the main CLI prompt or from the boot namespace prompt.

Interactive Argument Editor (TUI)

Enter the -- flag following any CLI command to open the interactive arguments editor text-based user interface (TUI).

Click for more information

The interactive argument editor is a text user interface (TUI) that can help enter complex commands with multiple configurable properties. It shows expected properties, defaults, input types (string, boolean, integer, or array), and can include command instructions or warnings.

Optional properties, indicated by the # symbol, are disabled by default. Required properties are enabled. Do not disable properties that are enabled by default.

To configure required properties, enter a space after the colon then add the value.

To enable optional properties, delete # from the corresponding line.

Some required properties are disabled if they are part of a pair of properties where one or the other is required. Select one property to enable and enter a value.

Press F2 or click Save to save the modified file.

Press F10, Esc, or click Quit to exit the TUI. The command automatically executes upon exit.

Attach

The attach command runs a job that attaches a device (disk) to the boot pool.

Before running this command, use these commands:

Using the Attach Command

Description

The attach command has two required properties, dev and options. dev is the disk name found in the output of the storage disk query command. options has one required property, expand, that is set to true by default. Enter the property argument using the = delimiter to separate property and value. Use the default options property argument, options={}. Enter the command string then press Enter. The command returns progress status in percentage of job completed, returns an error if the disk entered does not have enough space to hold the required partitions.

Usage

From the CLI prompt, enter:

system boot attach dev=sdd options={}

Where sdd is the name of the disk (device) to add to the boot pool.

Command Example 
system boot attach dev=sdd options={}
[0%] ...
[100%] ...

Detach Command

The detach command runs a job that removes a device (disk) from the boot pool. Use to remove additional boot devices. Use system boot replace to change the boot pool disk.

Before running this command, use system boot get_disks to get the name(s) of the boot pool disk(s).

Using the Detach Command

Description

The detach command has one required property, dev. dev is the vdev label for the device, which is the device name and the digit 3. 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.

To verify the disk is removed, use the system boot get_disks command.

Usage

From the CLI prompt, enter:

system boot detach dev=sdd3

Where sdd is the name of the vdev disk (device) to remove from the boot pool.

Command Example 
system boot detach dev=sdd3

Get_Disks Command

Use the get_disks command to obtain the name(s) of the disk(s) in the boot pool.

Using the Get_Disks Command

Description

The get_disks command does not require entering a property argument. Enter the command then press Enter. The command returns the names of disks in the boot pool.

Usage

From the CLI prompt, enter:

system boot get_disks

Command Example 
system boot get_disks
xvda

Get_Scrub_Interval Command

Use the get_scrub_interval command to obtain the number of days between boot pool scrubs.

The system advanced config result also shows the boot_scrub interval.

Using the Get_Scrub_Interval Command

Description

The get_scrub_interval command does not require entering a property argument. Enter the command then press Enter. The command returns the number of days between boot scrubs.

Usage

From the CLI prompt, enter:

system boot get_scrub_interval

Command Example 
system boot get_scrub_interval
8

Get_State Command

The get_state command provides information on the boot pool.

Using the Get_State Command

Description

The get_state command does not require entering a property argument. Enter the command then press Enter. The command returns the boot pool name, path, online status, healthy and warning settings, status code and status detail, boot pool size including allocated and free space, and fragmentation information. It includes dictionary mentions for the scan, topology, and autotrim settings.

Usage

From the CLI prompt, enter:

system boot get_state

Command Example 
system boot get_state
+---------------+------------------------------------------------------------------+
|          name | boot-pool                                                        |
|          path | /                                                                |
|        status | ONLINE                                                           |
|          scan | <dict>                                                           |
|      topology | <dict>                                                           |
|       healthy | true                                                             |
|       warning | true                                                             |
|   status_code | FEAT_DISABLED                                                    |
| status_detail | Some supported features are not enabled on the pool. The pool... |
|          size | 20401094656                                                      |
|     allocated | 10421198848                                                      |
|          free | 9979895808                                                       |
|       freeing | 0                                                                |
| fragmentation | 12                                                               |
|      size_str | 20401094656                                                      |
| allocated_str | 10421198848                                                      |
|      free_str | 9979895808                                                       |
|   freeing_str | 0                                                                |
|      autotrim | <dict>                                                           |
+---------------+---------------------------------------------------------------

Replace Command

Use the replace command to remove a device (drive) from the boot pool and replace it with a device of at least the same size. This command resilvers the boot pool and installs the boot loader on the new device.

Before running this command, use these commands:

Using the Replace Command

Description

The replace command has two required property arguments, label and dev. label is the vdev name for the current device (drive in the pool). This is the disk name and the digit 3. Use the UI Replace option on the System > Boot > Boot Status screen to view a list of device options and the names. dev is the name of the disk replacing the device in the boot pool. Enter the command string then press Enter. The command returns progress in percentage complete as it replaces the device, resilvers the boot pool, and installs the boot loader on the new device.

Usage

From the CLI prompt, enter:

system boot get_state

Command Example 
system boot replace label=sda3 dev=sdd
[0%] ...
[0%] Formatting sdd...
[0%] Replacing sda3 with sdd...
[3%] Resilvering boot pool, 30 seconds left...
[99%] Resilvering boot pool, unknown seconds left...
[100%] Installing boot loader...

Scrub Command

Use the scrub command to initiate a manual boot pool scrub.

Using the Scrub Command

Description

The scrub command does not require entering a property argument. Enter the command then press Enter. The command returns progress in percentage complete the boot pool scrub operation.

Usage

From the CLI prompt, enter:

system boot scrub

Command Example 
system boot scrub
[0%] ...
[0%] Scrubbing...
[2%] Scrubbing...
[3%] Scrubbing...
[5%] Scrubbing...
[6%] Scrubbing...
[7%] Scrubbing...
[8%] Scrubbing...
...
[98%] Scrubbing...
[99%] Scrubbing...
[100%] Scrub finished...

Set_Scrub_Interval Command

Use the set_scrub_interval to set or change the interval (in days) between boot pool scrub operations.

You can also use the system advanced update boot_scrub= command to set the boot pool scrub interval.

Using the Set_Scrub_Interval Command

Description

The set_scrub_interval command has one required property, interval. interval is the number of days between boot pool scrubs. Enter the command string then press Enter. The command returns the number now set for the interval.

Usage

From the CLI prompt, enter:

system boot set_scrub_interval interval=8

Command Example 
system boot set_scrub_interval interval=8
8

Related Content

SCALE CLI Reference
SCALE Tutorials
SCALE UI Reference

Have more questions?

For further discussion or assistance, see these resources:

Found content that needs an update?  You can suggest content changes directly! To request changes to this content, click the Feedback button located on the middle-right side of the page (might require disabling ad blocking plugins).