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. Task
  8. /
  9. Snapshot (Task)
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.

Snapshot (Task)

  12 minute read.

Last Modified 2024-03-15 13:07 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

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.

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.

PropertyRequiredDescriptionSyntax Example
datasetYesEnter the dataset path (pool/dataset) the task takes a snapshot of. Enclose the path in double quotes.dataset="tank/minio"
recursiveYesEnter true to include child datasets of the chosen dataset or false to exclude child datasets.recursive=true or recursive=false
excludeNoUsed 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_valueYesUse 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_unitYesUse 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_schemaYesEnter 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"
scheduleYesEnter 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_emptyNoEnter 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
    enabledNoEnter 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.

    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).