Get a Quote     (408) 943-4100   TrueNAS Discord VendOp_Icon_15x15px Enterprise Support
TrueNAS.com Software Systems Company Community Security iX Portal Download
TrueNAS Enterprise TrueNAS SCALE TrueNAS CORE Compare Editions TrueCommand Software Status FreeNAS
Compare Systems F-Series M-Series H-Series R-Series Mini Series
Contact Us iXsystems Careers Clients Reviews
TrueNAS GitHub Community Forum Discord TrueNAS Merch Store
Use Cases Analytics Backup and Archival Cloud Data Mobility File Sharing iX Storj Media Creation Surveillance Virtualization
Industry Education Government Healthcare Research / AI / ML Media & Entertainment
Enterprise Support Community Support Documentation TrueNAS Security FAQ ZFS Overview
TrueNAS Blog Solution Guides Datasheets Case Studies Videos TrueCommand Cloud
Download TrueNAS SCALE Download TrueNAS CORE Get TrueNAS Enterprise Compare TrueNAS Editions Contact an Enterprise Specialist
  1. TrueNAS SCALE 23.10
  2. /
  3. CLI Reference Guide
  4. /
  5. Storage
  6. /
  7. Snapshot
Edit page
TrueNAS SCALETrueNAS SCALE Version Documentation
This content follows the TrueNAS SCALE 23.10 (Cobia) releases. Use the Product and Version selectors above to view content specific to different TrueNAS software or major version.

Snapshot

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

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.

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.

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

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.

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.

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.

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.

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.

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.

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'

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.

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.

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.

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.

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 CLI Storage Articles

Related Snapshot Articles

Have more questions or want to discuss your specific configuration? 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).