snapmirror restore

Restore a Snapshot copy from a source volume to a destination volume

Availability: This command is available to cluster and Vserver administrators at the admin privilege level.

Description

The snapmirror restore command restores the entire contents of a Snapshot copy or one or more files, LUNs or NVMe namespaces of a Snapshot copy from one volume to another volume.

The source of the restore can be a volume that is:

The following cannot be used as either the source or destination volume of a restore:

A SnapMirror relationship of type RST is created from the source volume to the destination volume by the snapmirror restore command. This relationship lasts for the duration of the restore operation and is deleted when the command completes successfully.

The following paragraphs describe the behavior when restoring the entire contents of a Snapshot copy to a destination volume.

By default the snapmirror restore will copy the latest Snapshot copy from the source volume to the destination volume. A specific Snapshot copy can be selected with the -source-snapshot parameter.

Any quota rules defined for the destination volume are deactivated prior to restoring the entire contents of a Snapshot copy. Run the command volume quota modify -vserver destination-volume-vserver -volume destination-volume-name -state on to reactivate quota rules after the entire contents of the Snapshot copy have been restored.

If the destination volume is an empty data protection volume, the snapmirror restore command performs a baseline restore. For a baseline restore the following steps are performed:

If the destination volume is a read-write volume, an incremental restore is performed. The incremental restore fails if it cannot find a common Snapshot copy between the source and destination volumes. Restoring a Snapshot copy to an empty read-write volume is not supported. Incremental restore from a non-Data ONTAP endpoint to a Data ONTAP volume is not supported.

An incremental restore preserves all Snapshot copies on the destination volume but does not preserve changes to the active file system since the latest Snapshot copy. To preserve changes to the destination volume since the latest Snapshot copy use the volume snapshot create command. Restore is a disruptive operation so client access of the destination volume is not advised for the duration of the operation.

For an incremental restore the following steps are performed:

If snapmirror restore fails or is aborted, the RST relationship remains. Use the snapmirror show command with the destination volume name to display the reason for the error. An EMS is also generated when a failure occurs. There are two options to recover when restore fails or is aborted:

When specifying -clean-up-failure to cancel an incremental restore request, the following steps are performed:

When specifying -clean-up-failure to cancel a baseline restore request, the following steps are performed:

The following paragraphs describe the behavior and requirements when restoring one or more files, LUNs or NVMe namespaces to the destination volume.

The destination volume must be a read-write volume. Restoring files, LUNs or NVMe namespaces to a data protection volume is not supported. When restoring files, LUNs or NVMe namespaces the source and destination volumes are not required to have a common Snapshot copy. If a common Snapshot copy exists, an incremental restore is performed for those files, LUNs or NVMe namespaces being restored which exist in the common Snapshot copy.

The contents of the files, LUNs or NVMe namespaces to which data is being restored on the destination volume are not preserved by this command. To preserve the contents of the destination files, LUNs or NVMe namespaces, create a Snapshot copy on the destination volume prior to running this command. Client I/O is not allowed to a file, LUN or NVMe namespace to which data is being restored on the destination volume.

The -source-snapshot parameter is required when restoring files, LUNs or NVMe namespaces. It identifies the Snapshot copy on the source volume from which the files, LUNs or NVMe namespaces to be restored are copied. If all files, LUNs or NVMe namespaces to be restored do not exist in this Snapshot copy the command fails.

The source path for each file, LUN or NVMe namespace being restored is required. The source path of a file, LUN or NVMe namespace is from the root of the source Snapshot copy of the source volume. The file is restored to the same path on the destination volume unless an optional destination path is specified. The destination path is from the root of the destination volume. If a file, LUN or NVMe namespace to which data is being restored on the destination volume does not exist, the file, LUN or NVMe namespace is created. If any directory in the path of the file, LUN or NVMe namespace being restored does not exist on the destination volume, the command fails. Overwriting the contents of an existing file with the contents of a different file is supported. Similarly, overwriting the contents of an existing LUN or NVMe namespace with the contents of a different LUN or NVMe namespace is supported. However, overwriting a file with the contents of a LUN or NVMe namespace is not supported. Overwriting a LUN with the contents of a file or NVMe namespace is not supported. Overwriting an NVMe namespace with the contents of a file or LUN is not supported. Client I/O is not allowed to all files, LUNs and NVMe namespaces to which data is being restored on the destination volume.

If quota rules have been defined for the destination volume, resource usage is updated during file restore, but limits of quota rules are not enforced. Therefore, resource limits might be exceeded during a file restore.

Multiple concurrent snapmirror restore commands, restoring one or more files, LUNs or NVMe namespaces to the same destination volume, are not supported. The destination volume of a snapmirror restore to which one or more files, LUNs or NVMe namespaces are being restored, can simultaneously be the source volume of a snapmirror update.

For a file, LUN or NVMe namespace restore the following steps are performed:

Note: Some file restore operations require a Snapshot copy to be created. This Snapshot copy is temporary, it is deleted before the operation completes.

Since client I/O is not allowed to files, LUNs or NVMe namespaces being restored, client I/O to files, LUNs or NVMe namespaces being restored should be quiesced. Mapped LUNs or NVMe namespaces remain mapped throughout the operation. SAN clients do not need to rediscover a mapped LUN that has been restored. Restoring an NVMe namespace on top of another NVMe namespace with a different attribute relevant to NVMe protocol accessibility (like size) is not supported.

If snapmirror restore fails or is aborted, the RST relationship remains. Use the snapmirror show command with the destination volume to display the reason for the error. An EMS is also generated when a failure occurs. There are two options to recover when restore fails or is aborted:

When specifying -clean-up-failure to cancel a file restore request, the following steps are performed:

Note: LUNs to which client I/O is not allowed remain. For LUNs to which client I/O is not allowed, do one of the following:
Note: Similarly, NVMe namespaces to which client I/O is not allowed remain. For NVMe namespaces to which client I/O is not allowed, do one of the following:

The snapmirror restore command must be used from the destination Vserver or cluster.

Parameters

{ [-source-path | -S {<[vserver:][volume]>|<[[cluster:]//vserver/]volume>|<hostip:/lun/name>|<hostip:/share/share-name>}] - Source Path
Specifies the source endpoint in one of three formats. The basic format includes the names of the Vserver (vserver) and volume (volume). A format which also includes the name of the cluster (cluster) is supported for consistency with other snapmirror commands. The form of the pathname which includes the cluster name is not valid when operating in a Vserver context. A non-Data ONTAP source endpoint (for example, AltaVault) can be specified in the form hostip:/share/share-name.
| [-source-cluster <Cluster name>] - Source Cluster
Specifies the cluster in which the source volume resides. This parameter is not needed; it is provided for consistency with other snapmirror commands. If this parameter is specified, the -source-vserver and -source-volume parameters must also be specified. This parameter is not valid when operating in a Vserver context. This parameter is not supported if the source is a non-Data ONTAP endpoint.
[-source-vserver <vserver name>] - Source Vserver
Specifies the source Vserver of the SnapMirror relationship. If this parameter is specified, the -source-volume parameter must also be specified. This parameter is not supported if the source is a non-Data ONTAP endpoint.
[-source-volume <volume name>]} - Source Volume
Specifies the source volume of the SnapMirror relationship. If this parameter is specified, the -source-vserver parameter must also be specified. This parameter is not supported if the source is a non-Data ONTAP endpoint.
{ -destination-path {<[vserver:][volume]>|<[[cluster:]//vserver/]volume>|<hostip:/lun/name>|<hostip:/share/share-name>} - Destination Path
Specifies the destination endpoint in one of two formats. The basic format includes the names of the Vserver (vserver) and volume (volume). A format that also includes the name of the cluster (cluster) is supported for consistency with other snapmirror commands. The form of the pathname which includes the cluster name is not valid when operating in a Vserver context.
| [-destination-cluster <Cluster name>] - Destination Cluster
Specifies the cluster in which the destination volume resides. This parameter is not needed; it is provided for consistency with other snapmirror commands. If this parameter is specified, the -destination-vserver and -destination-volume parameters must also be specified. This parameter is not valid when operating in a Vserver context. This parameter is only applicable for relationships with "Relationship Capability" of "Pre 8.2".
-destination-vserver <vserver name> - Destination Vserver
Specifies the destination Vserver. If this parameter is specified, the -destination-volume parameter must also be specified.
-destination-volume <volume name>} - Destination Volume
Specifies the destination volume. If this parameter is specified, the -destination-vserver parameter must also be specified.
[-source-snapshot | -s <text>] - Source Snapshot
When restoring the entire contents of a Snapshot copy, this optional parameter identifies the Snapshot copy to be restored from the source volume to the destination volume. The default value is the latest snapshot on the source volume. When restoring one or more files, LUNs or NVMe namespaces from a Snapshot copy, this parameter is required.
[-throttle | -k <throttleType>] - Throttle (KB/sec)
This optional parameter limits the network bandwidth used for the restore transfer when the source and destination volumes belong to different clusters. It sets the maximum rate (in Kbytes/sec) at which data can be transferred between the clusters during the operation. To fully use the network bandwidth available between the clusters, set the throttle value to unlimited or 0. The minimum throttle value is four Kbytes/sec, so if you specify a throttle value between 1 and 4, it will be treated as if you specified 4.
[-transfer-priority {low|normal}] - Transfer Priority
This optional parameter specifies the priority at which the transfer runs. The default value for this parameter is normal.
[-disable-storage-efficiency [true]] - Disable Storage Efficient Transfer
The default behavior of restore is to preserve storage efficiency when possible. Use this optional parameter to turn off storage efficiency for data transferred over the wire and written to the destination volume.
[-clean-up-failure [true]] - Clean up after Failure
Use this optional parameter to recover from an aborted or failed restore operation. Any temporary RST relationship is removed from the destination Vserver. An attempt is made to remove any temporary RST relationship from the source Vserver. If cleaning up an incomplete restore of the entire contents of a Snapshot copy and the destination volume was read-write prior to the failed or aborted restore operation, it is converted back to read-write if necessary, while removing all data transferred or copied during the restore operation. If cleaning up an incomplete restore of one or more files, LUNs or NVMe namespaces of a Snapshot copy, any file to which client I/O is not allowed is deleted.
[-tries <unsigned32_or_unlimited>] - Tries Limit
Specifies the total number of attempts to transfer data in cases where a transfer is interrupted by an error that SnapMirror can recover from. The value of this parameter must be a positive integer or unlimited.
[-force | -f [true]] - Force
If this parameter is specified, the command proceeds without prompting for confirmation.
[-on-demand [true]] - On Demand
This optional parameter specifies that data will be pulled from the object store only when the file system is accessed.
[-file-list <<source path>[,@<destination path>]>, ...] - File List
Specifies the files, LUNs or NVMe namespaces to be restored. The list can contain specifications for up to 8 files, LUNs or NVMe namespaces. Specification for each file, LUN or NVMe namespace consists of a source_path and an optional destination_path, and is of the form 'source_path[,@destination_path]'. source_path is required and is the path of the file from the source Snapshot copy, e.g. /dira/file1 or /lun1. The source path does not include the Snapshot name nor the source volume name. The path to each file to be restored in the active file system of the destination volume is the same as the path specified by source_path, unless an optional destination_path is specified. destination_path begins with the @ symbol followed by the path of the file from the root of the active file system of the destination volume, e.g. @/file1 or @/dira/lun1. Each source_path and destination_path is a separate entity in the list of paths. A destination_path is associated with the source_path that immediately precedes it. If this parameter is specified, -source-snapshot must also be specified. Examples:
/dira/file1
/dira/file1,@/dirb/file2
/dira/file1,@/dirb/file2,/dirc/file3
[-use-network-compression [true]] - Use Network Compression
Use this optional parameter to use network compression for data transfer over the wire. This parameter is not supported for relationships with non-Data ONTAP endpoints.

Examples

The following example does an incremental restore between the restore source volume vs2.example.com:dept_eng_dp_mirror2 and the restore destination volume vs1.example.com:dept_eng:

vs1.example.com::> snapmirror restore
     -destination-path vs1.example.com:dept_eng
     -source-path vs2.example.com:dept_eng_dp_mirror2
     -source-snapshot snap3
Warning: All data newer than Snapshot copy snap6 on volume
         vs1.example.com:dept_eng will be deleted.
Do you want to continue? {y|n}: y
[Job 34] Job is queued: snapmirror restore from source
vs2.example.com:dept_eng_dp_mirror2 for the snapshot snap3.
vs1.example.com::>

The following example restores /file3 from the source Snapshot copy snap3 on the source volume vs2.example.com:dept_eng_dp_mirror2 to the active file system of the restore destination volume vs1.example.com:dept_eng:

vs1.example.com::> snapmirror restore
     -destination-path vs1.example.com:dept_eng
     -source-path vs2.example.com:dept_eng_dp_mirror2
     -source-snapshot snap3
     -file-list /file3
Warning: This command will overwrite any file on destination
"vs1.example.com:dept_eng" that has the same path as any of
the files to be restored.
Do you want to continue? {y|n}: y
[Job 35] Job is queued: snapmirror restore from source
"vs2.example.com:dept_eng_dp_mirror2" for the snapshot snap3.
vs1.example.com::>

The following example restores /file3 from the source Snapshot copy snap3 on the source volume vs2.example.com:dept_eng_dp_mirror2 to /file3.new in the active file system of the restore destination volume vs1.example.com:dept_eng:

vs1.example.com::> snapmirror restore
     -destination-path vs1.example.com:dept_eng
     -source-path vs2.example.com:dept_eng_dp_mirror2
     -source-snapshot snap3
     -file-list /file3,@/file3.new
Warning: This command will overwrite any file on destination
"vs1.example.com:dept_eng" that has the same path as any of
the files to be restored.
Do you want to continue? {y|n}: y
[Job 36] Job is queued: snapmirror restore from source
"vs2.example.com:dept_eng_dp_mirror2" for the snapshot snap3.
vs1.example.com::>

The following example restores /file1, /file2, and /file3 from the source Snapshot copy snap3 on the source volume vs2.example.com:dept_eng_dp_mirror2 respectively to /file1.new, /file2, and /file3.new in the active file system of the restore destination volume vs1.example.com:dept_eng:

vs1.example.com::> snapmirror restore
     -destination-path vs1.example.com:dept_eng
     -source-path vs2.example.com:dept_eng_dp_mirror2
     -source-snapshot snap3
     -file-list /file1,@/file1.new,/file2,/file3,@/file3.new
Warning: This command will overwrite any file on destination
"vs1.example.com:dept_eng" that has the same path as any of
the files to be restored.
Do you want to continue? {y|n}: y
[Job 36] Job is queued: snapmirror restore from source
"vs2.example.com:dept_eng_dp_mirror2" for the snapshot snap3.
vs1.example.com::>

The following example deletes data from an incomplete file restore, captured in a Snapshot copy which was later promoted to the active file system of a volume.

vs1.example.com::> snapmirror restore
     -destination-path vs1.example.com:dept_eng
     -file-restore-clean-up
Operation is queued: snapmirror restore with "-file-restore-clean-up"
on volume "vs1.example.com:dept_eng".
vs1.example.com::>