Pool

20 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!

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).
Click for more information

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.

Using the Attachments Command

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.

Command Example

storage pool attachments id=4
+---------------+------------+--------------------------+
| type          | service    | attachments              |
+---------------+------------+--------------------------+
| snapshot Task | <null>     | tank/minio               |
|               |            | tank/minio               |
|               |            | tank/snapshots           |
| NFS Share     | nfs  >     | /mnt/tank/share/nfs      |
|               |            | /mnt/tank/share/nfs/nfs2 |
|               |            | /mnt/tank/share/nfs/nfs3 |
|               |            | /mnt/tank/share/nfs/nf42 |
| Rsync Task    | <null>     | /mnt/tank/minio          |
| Kubernetes    | kubernetes | tank                     |
+---------------+------------+--------------------------+

Create Command

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.

Using the Detach Command

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.

Command Example

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.

Using the Expand Command

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.

Command Example

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.

Using the Export Command

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.

Options Properties

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.

Command Example

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.

Using the Filesystem_Choices Command

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 Properties

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

Command Example

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.

Using the Get_Disks Command

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.

Command Example

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.

Using the Get_Instance_By_Name 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.

Command Example

storage pool get_instance_by_name=tank
+---------------+--------------------+
|            id | 5                  |
|          name | tank2              |
|          guid | 981158589697766753 | 
|          path | /mnt/tank2         |
|        status | ONLINE             |
|          scan | <dict>             |
|      topology | <dict>             |
|       healthy | true               |
|       warning | false              |
|   status_code | OK                 |
| status_detail | true               |
|          size | 2989297238016      |
|     allocated | 3194880            |
|          free | 2989294043136      |
|       freeing | 0                  |
| fragmentation | 0                  |
|      size_str | 2989297238016      |
| allocated_str | 3194880            |
|      free_str | 2989294043136      |
|   freeing_str | 0                  |
|      autotrim | <dict>             |
+---------------+--------------------+

Get_Instance_By_Name Command

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.

Using the Get_Instance_By_Name 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.

Command Example

storage pool get_instance_by_name=tank
+---------------+--------------------+
|            id | 5                  |
|          name | tank2              |
|          guid | 981158589697766753 | 
|          path | /mnt/tank2         |
|        status | ONLINE             |
|          scan | <dict>             |
|      topology | <dict>             |
|       healthy | true               |
|       warning | false              |
|   status_code | OK                 |
| status_detail | true               |
|          size | 2989297238016      |
|     allocated | 3194880            |
|          free | 2989294043136      |
|       freeing | 0                  |
| fragmentation | 0                  |
|      size_str | 2989297238016      |
| allocated_str | 3194880            |
|      free_str | 2989294043136      |
|   freeing_str | 0                  |
|      autotrim | <dict>             |
+---------------+--------------------+

Import_Find Command

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.

Using the Import_Find Command

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

Command Example

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.

Using the Import_Pool Command

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.

Pool_Import Properties

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 –

Command Example

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.

Using the Is_Upgraded Command

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.

Command Example

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.

Using the Offline Command

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.

Command Example

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.

Using the Offline Command

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.

Command Example

storage pool online id=4 options={"label":"6515190129612429183"}
true

Processes Command

The processes command lists processes used by the pool matching the ID entered.

Using the Processes Command

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.

Command Example

storage pool processes id=4
(empty list)

Query Command

The query command returns a table (dictionary) of all pools on the system.

Using the Query Command

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.

Usage

From the CLI prompt, enter:

`storage pool query'

Command Example

storage pool query
+----+-------+---------------------+------------+---------+--------+----------+---------+---------+-------------+---------------+---------------+------------+------------+ +-------+---------------+---------------+---------------+-------------+----------+
| id | name  | guid                | path       | status  | scan   | topology | healthy | warning | status_code | status_detail | size          | allocated  | free       | freeing | fragmentation | size_str      | allocated_str | freeing_str | autotrim |
+----+-------+---------------------+------------+---------+--------+----------+---------+---------+-------------+---------------+---------------+------------+------------+ +-------+---------------+---------------+---------------+-------------+----------+
| 4  | tank  | 1016066042284556131 | /mnt/tank  | ONLINE  | <dict> | <dict>   | true    | false   | OK          | <null>        | 2989297238016 | 4627304448 | 2984669933568 | 0       | 0             | 2989297238016 | 4627304448    | 0           | <dict>   |
| 5  | tank2 | 98111585897766753   | /mnt/tank2 | ONLINE  | <dict> | <dict>   | true    | false   | OK          | <null>        | 2989297238016 | 31994880   | 2989294043136 | 0       | 0             | 2989297238016 | 31994880   | 0           | <dict>   |
+----+-------+---------------------+------------+---------+--------+----------+---------+---------+-------------+---------------+---------------+------------+------------+ +-------+---------------+---------------+---------------+-------------+----------+

Remove Command

The remove command removes the ZFS device from the pool matching the ID entered and wipes disks in the pool.

Using the Remove Command

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.

Command Example

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.

Scrub Command

The scrub command starts a scrub for the pool matching the ID entered. This command performs the same function as running a pool data integrty check (scrub) operation.

Using the Scrub Command

Description

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.

Usage

From the CLI prompt, enter:

storage pool scrub id=4 action=START

Where:

4 is the pool ID assigned by the system.
START begins the scrub operation.

Command Example

storage pool scrub id=4 action=START
[0%] ...
[0%] Scrubbing...
[3%] Scrubbing...
[5%] Scrubbing...
[8%] Scrubbing...
[12%] Scrubbing...
...
[100%] Scrub finished...

Update Command

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.

Using the Upgrade Command

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.

Command Example

storage pool upgrade id=7
true

Validate_Name Command done

The validate_name command validates the pool name entered.

Using the Validate_Name Command

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.

Usage

From the CLI prompt, enter:

storage pool validate_name pool_name=tank2

Where 7 is the pool ID assigned by the system.

Command Example

storage pool validate_name pool_name=tank2
true

Pool

Snapshot Namespace

Snapshot Commands

Interactive Argument Editor (TUI)

Attach Command

Attachments Command

Description

Usage

Create Command

Detach Command

Description

Usage

Expand Command

Description

Usage

Export Command

Description

Usage

Filesystem_Choices Command

Description

Usage

Get_Disks Command

Description

Usage

Get_Instance Command

Description

Usage

Get_Instance_By_Name Command

Description

Usage

Import_Find Command

Description

Usage

Import_Pool Command

Description

Usage

Is_Upgraded

Description

Usage

Offline Command

Description

Usage

Online Command

Description

Usage

Processes Command

Description

Usage

Query Command

Description

Usage

Remove Command

Description

Usage

Replace Command

Scrub Command

Description

Usage

Update Command

Upgrade Command

Description

Usage

Validate_Name Command done

Description

Usage

Related CLI Storage Articles

Related Pool Articles

Related Disk Articles