TrueNAS Documentation Archive
This content follows the TrueNAS 23.10 (Cobia) releases. Archival documentation is provided for reference only and not actively maintained. Use the Product and Version selectors above to view content specific to different TrueNAS software or major version.

Snapshot (Task)

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

Create Command

The create command creates a periodic snapshot task for a given dataset at the specified schedule.

Using the Create Command

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.

Create Command Properties

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.	`schedule={[“minute”=“00”], [“hour”="”], [“dom”=""], [“month”=""], [“dow”=""], [“begin”=“00:00”], [“end”=“00:00”]}`
`allow_empty`	No	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.	`enabled=true` or `enabled=false`

Usage

From the CLI prompt, enter:

task snapshot create dataset="tank/minio" recursive=false lifetime_value=1 lifetime_unit=WEEK naming_schema="new-%d-%m-%Y_%H-%M" schedule={}

Where:

tank/minio is the name/path of the dataset to snapshot.
false sets recursive to not include child datasets in the snapshot. true includes child datasets.
1 and WEEK set the length of time (lifetime of) the snapshot remains on the system.
new-%d-%m-%Y_%H-%M creates a naming schema new that includes the day-month-Year_Hour-Minute in the name.
{} is the default value for a task schedule that uses all default values schedule properties.

Command Example

task snapshot create dataset="tank/minio" recursive=false lifetime_value=1 lifetime_unit=WEEK naming_schema="new-%d-%m-%Y_%H-%M" schedule={}

Delete Command

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.

Using the Delete Command

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.

delete returns an empty line.

Usage

From the CLI prompt, enter:

task snapshot delete id="tank/minio@auto-2023-08-17_00-00"

Where tank/minio@auto-2023-08-17_00-00 is the ID assigned to the share.

Command Example

task snapshot delete id="tank/minio@auto-2023-08-17_00-00"

Delete_Will_Change_Retention_For Command

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.

Using the Delete_Will_Change_Retention_For Command

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.

delete returns a list of snapshot tasks.

Usage

From the CLI prompt, enter:

task snapshot delete_will_change_retention_for id=11

Where 11 is the ID assigned to the snapshot task.

Command Example

task snapshot delete_will_change_retention_for id="tank/minio@auto-2023-08-17_00-00"
+------------+-----------------------+
| tank/minio | auto-2023-08-16_00-00 |
|            | auto-2023-08-21_00-00 |
|            | auto-2023-08-21_00-00 |
+------------+-----------------------+

Forseen_Count Command

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.

Using the Get_Instance Command

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.

Usage

From the CLI prompt, enter:

task snapshot get_instance id=11

Where 11 is the ID number of the snapshot task.

Command Example

sharing nfs get_instance id=11 
+----------------+--------------------+
|             id | 11                 |
|        dataset | tank/minio         |
|      recursive | false              |
| lifetime_value | 1                  |
|  lifetime_unit | DAY                |
|        enabled | true               |
|        exclude | <empty list>       |
|  naming_schema | new-%d-%m-%Y_%H-%M |
|    allow_empty | true               |
|       schedule | <dict>             |
|    vmware_sync | false              |
|          state | <dict>             |
+----------------+--------------------+

Max_Count Command

The max_count command returns the maximum number of snapshots per dataset the system can sustain.

Using the Max_Count Command

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

Command Example

task snapshot max_count
512

Max_Total_Count Command

The max_total_count command returns the maximum number of snapshots the system can sustain.

Using the Max_Total_Count Command

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

Command Example

task snapshot max_total_count
10000

Query Command

The query command returns a table (dictionary) of all snapshot tasks 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 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.

Usage

From the CLI prompt, enter:

`task snapshot query'

Command Example

storage snapshot query
+----+-----------------+-----------+----------------+---------------+---------+--------------+-----------------------------+-------------+----------+-------------+--------+
| id | dataset         | recursive | lifetime_value | lifetime_unit | enabled | exclude      | naming_schema               | allow_empty | schedule | vmware_sync | state  | 
+----+-----------------+-----------+----------------+---------------+---------+--------------+-----------------------------+-------------+----------+-------------+--------+
| 9  | tank/minio      | false     | 2              | DAY           | true    | <empty list >| auto-2023-08-16_00-00       | true        | <dict>   | false       | <dict> |
| 10 | tank/minio      | false     | 2              | DAY           | true    | <empty list >| customsnap-2023-08-16_00-00 | true        | <dict>   | false       | <dict> |
| 11 | tank2/snpashots | false     | 2              | DAY           | true    | <empty list >| new-2023-08-16_00-00        | true        | <dict>   | false       | <dict> |
| 12 | tank/snapshots  | false     | 2              | DAY           | true    | <empty list >| auto-2023-08-16_00-00       | true        | <dict>   | false       | <dict> |
+----+-----------------+-----------+----------------+---------------+---------+--------------+-----------------------------+-------------+----------+-------------+--------+

Run Command

The run command starts the snapshot task for the task ID entered. Use the query command to locate the snapshot task ID.

Using the Run Command

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.

Command Example

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.

Using the Update Command

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:

task snapshot update id=11 dataset="newDatasetName"

Where

11 is the ID number of the snapshot task to update.
dataset is any of the editable properties and newDatasetName is the new dataset name/path to snapshot.

Command Example

task snapshot update id= dataset="tank2/snapshots"

Update_Will_Change_Retention_For Command update

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.

Use Cases

Industry

Support

Resources

Snapshot (Task)

Snapshot Namespace

Snapshot Commands

Interactive Argument Editor (TUI)

Create Command

Description

Usage

Delete Command

Description

Usage

Delete_Will_Change_Retention_For Command

Description

Usage

Forseen_Count Command

Get_Instance Command

Description

Usage

Max_Count Command

Description

Usage

Max_Total_Count Command

Description

Usage

Query Command

Description

Usage

Run Command

Description

Usage

Update Command

Usage

Update_Will_Change_Retention_For Command update

Related CLI Task Articles

Related Snapshot Articles