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. Storage
  8. /
  9. Snapshot
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

  8 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 10 commands, and is based on snapshot creation and management functions found in the SCALE API and web UI. It provides access to storage snapshot methods through the snapshot commands.

Snapshot Commands

The following snapshot commands allow you to create new snapshots and manage existing snapshots.

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

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.

Clone Command

The clone command clones an existing snapshot to a new dataset.

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.

Create Command

The create command takes a snapshot of a given dataset.

Using the Create Command

Description

The create command has one required property, dataset, and seven optional properties. The Create Command Optional Properties section below lists the seven optional properties and provides syntax examples. dataset defines the pool/dataset path for the snapshot you want to create. For example, tank/minio. Enter a property argument using the = delimiter to separate property and value. Enter string values in double quotes.

Enter the command string then press Enter.

create returns an empty line. Use the query command to verify the snapshot was created and to view details on the snapshot.

Create Command Optional Properties

Use these optional properties when creating a snapshot.

PropertyDescriptionSyntax Example
nameEnter a unique snapshot name. Use either name or naming schema in the same snapshot but not both, one or the other is required. Entering a name does not require using double quotes, but if entering a name string (two words or including a special character), enclose the string in double quotes.name=miniosnaps or name="rep_snaps"
naming_schemaEnter 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. These are replaced with the four-digit year, month, day of month, hour, and minute as defined in strftime(3). For example, snapshots of pool1 entering naming_schema=customsnap-%Y%m%d.%H%M have snapshots named pool1@customsnap-20190315.0527. Use either naming_schema or name in the same snapshot but not both.naming_schema="customsnap-%Y%m%d.%H%M"
recursiveEnter true to include child datasets of the chosen dataset or false to exclude child datasets.recursive=true or recursive=false
excludeUse 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"
suspend_vmsThis option is a work in progress.
vmware_syncEnter true to synchronize the snapshot with VMWare or false if VMWare is not in use or to not synchronize with it.vmware_sync=true or vmware_sync=false
propertiesThis option is a work in progress.

Usage

From the CLI prompt, enter:

storage snapshot create dataset="tank/minio" name=miniosnaps

Where:

  • tank/minio is the path to the dataset you want to create a snapshot of.
  • miniosnaps is the name for the snapshot.

If using additional optional property arguments, for example, including/excluding child datasets, enter:

storage snapshot create dataset="tank/minio" name=miniosnaps recursive=true exclude="child1", “child3"

Where:

  • tank/minio is the path to the dataset you want to create a snapshot of.
  • miniosnaps is the name for the snapshot.
  • true for recursive includes child datasets in the snapshot of the specified dataset. false excludes child datasets.
  • child1 and child3 are child datasets excluded from the snapshot.

Command Example 
storage snapshot create dataset="tank/minio" name=miniosnaps

Delete Command

The delete command deletes a snapshot matching the ID entered. Use the query command to locate the snapshot ID.

Using the Delete Command

Description

delete has one required property, id. Enter the property argument using the = delimiter separating the property and value, and the value double-quoted. Enter the command string, then press Enter.

delete returns an empty line.

Usage

From the CLI prompt, enter:

storage 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 
storage snapshot delete id="tank/minio@auto-2023-08-17_00-00"

Get_Instance Command

The get_instance command retrieves information for a snapshot 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.

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, and the value double-quoted. Enter the command string, then press Enter. get_instance returns a table (dictionary) of properties for the ID entered. The table (dictionary) includes the properties, pool, id and name, snapshot name, dataset, and the create transfer group.

Use the query command to locate the ID number for the share.

Usage

From the CLI prompt, enter:

storage snapshot get_instance id="tank/minio@auto-2023-08-16_00-00"

Where tank/minio@auto-2023-08-16_00-00 is the ID number for the snapshot.

Command Example 
sharing nfs get_instance id="tank/minio@auto-2023-08-16_00-00" 
+---------------+----------------------------------+
|    properties | <dict>                           |
|          pool | tank                             |
|          name | tank/minio@auto-2023-08-16_00-00 |
|          type | SNAPSHOT                         |
| snapshot_name | auto-2023-08-16_00-00            |
|       dataset | tank2/reptests                   |
|            id | tank/minio@auto-2023-08-16_00-00 |
|     createtxg | 27256                            |
+---------------+----------------------------------+

Hold Command

The hold command holds a snapshot matching the ID entered. Holding a snapshot prevents it from being deleted. Use the query command to locate the snapshot ID. Use the release command to unlock the snapshot to remove the hold on the snapshot.

Using the Hold Command

Description

hold has one required property, id. Enter the property argument using the = delimiter separating the property and value, and the value double-quoted. Enter the command string, then press Enter.

hold returns an empty line.

Usage

From the CLI prompt, enter:

storage snapshot hold id="tank/minio@auto-2023-08-16_00-00"

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

Command Example 
storage snapshot hold id="tank/minio@auto-2023-08-16_00-00"

Query Command

The query command returns a table (dictionary) of all snapshots 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 snapshots on the system. Information includes the ID, path, aliases, any comments, networks hosts, read only status, maproot user and group, mapall user and group, security, enabled, and locked status.

Usage

From the CLI prompt, enter:

`storage snapshot query'

Command Example 
storage snapshot query
+------------+-------+--------------------------------------+----------+-----------------------+----------------+-------------------------------------+-----------+
| properties | pool  | name                                 | type     | snapshot_name         | dataset        | id                                  | createtxg | 
+------------+-------+--------------------------------------+----------+-----------------------+----------------+-------------------------------------+-----------+
| <dict>     | tank  | tank/minio@auto-2023-08-16_00-00     | SNAPSHOT | auto-2023-08016_00-00 | tank/minio     | tank/minio@auto-2023-08-16_00-00    | 111001    |
| <dict>     | tank2 | tank2/reptest@auto-2023-08-17_00-00  | SNAPSHOT | auto-2023-08-17_00-00 | tank2/reptests | tank2/reptest@auto-2023-08-17_00-00 | 111001    |
+------------+-------+--------------------------------------+----------+-----------------------+----------------+-------------------------------------+-----------+

Release Command

The release command removes the hold on a snapshot allowing it to be deleted. Use the query command to locate the snapshot ID.

Using the Release Command

Description

release has one required property, id. Enter the property argument using the = delimiter separating the property and value, and the value double-quoted. Enter the command string, then press Enter.

release returns an empty line.

Usage

From the CLI prompt, enter:

storage snapshot release id="tank/minio@auto-2023-08-16_00-00"

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

Command Example 
storage snapshot release id="tank/minio@auto-2023-08-16_00-00"

Remove Command

The remove command removes a snapshot from a given dataset. Use the query command to locate the snapshot ID.

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.

Rollback Command

The rollback command replaces data in the specified dataset with the information saved in the snapshot matching the ID entered.

Use the query command to locate the snapshot ID.

Using the Rollback Command

Description

rollback has one required property, id. Enter the property argument using the = delimiter separating the property and value, and the value double-quoted. Enter the command string, then press Enter. rollback returns an empty line. The options property is a work in progress.

Use the query command to locate the ID number for the snapshot.

Usage

From the CLI prompt, enter:

storage snapshot rollback id=tank/minio@auto-2023-08-16_00-00"

Where tank/minio@auto-2023-08-16_00-00 is the ID number for the snapshot.

Command Example 
storage snapshot rollback id=tank/minio@auto-2023-08-16_00-00

Update Command

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