snapmirror restore

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 destination volume of a extended data protection (XDP) relationship
• the destination volume of a data protection (DP) relationship with "Relationship Capability" of "8.2 and above"
• a data-protection volume which is not the destination endpoint of any SnapMirror relationship
• a read-write volume.
• an AltaVault endpoint. In this case the destination must be an empty Data ONTAP volume.

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

• a volume that is the source or destination endpoint of a SnapMirror load-sharing relationship.
• a volume that is the destination endpoint of a SnapMirror relationship with the "Relationship Capability" of "Pre 8.2".
• a SolidFire endpoint.

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:

• Create the RST SnapMirror relationship.
• The entire contents of the Snapshot copy selected to be restored are copied to the active file system of the destination volume.
• The destination volume is made read-write.
• The RST SnapMirror relationship is deleted.

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:

• Create the RST SnapMirror relationship.
• The active file system of the destination volume is reverted to the latest Snapshot copy on the destination volume and the destination volume is made read-only.
• This Snapshot copy is the exported Snapshot copy and it is the view to which clients are redirected when accessing the destination volume.
• The contents of the Snapshot copy selected to be restored are copied to the active file system of the destination volume.
• The destination volume is made read-write.
• The RST SnapMirror relationship is deleted.

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:

• Take corrective action suggested by the EMS and reissue the original command.
• Use the original command with -clean-up-failure to cancel the request.

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

• If the Snapshot copy has not been restored to the destination volume, all data copied to the active file system by snapmirror restore to the destination volume is reverted.
• The destination volume is made read-write.
• The RST SnapMirror relationship is deleted.

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

• If the Snapshot copy has been restored to the destination volume, the volume is made read-write.
• The RST SnapMirror relationship is deleted.

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:

• Create the RST SnapMirror relationship.
• If any file, LUN or NVMe namespace being restored does not exist on the destination volume, create all such files, LUNs or NVMe namespaces.
• Prevent client I/O to files, LUNs or NVMe namespaces to which data is being restored on the destination volume.
• Revoke locks and space reservations held by NAS clients for files being restored.
• Copy the contents of all source files, LUNs or NVMe namespaces to the corresponding file, LUN or NVMe namespace on the destination volume.
• Allow client I/O to files, LUNs or NVMe namespaces to which data has been restored on the destination volume.
• Delete the RST SnapMirror relationship.

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:

• Take corrective action suggested by the EMS and reissue the original command.
• Use snapmirror restore -clean-up-failure along with specifying the destination volume to cancel the request.

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

• Any files to which client I/O is not allowed are removed.
• Any Snapshot copy created for use during a file restore operation is deleted.
• The RST SnapMirror relationship is deleted.

• Use the snapmirror restore command to restore data to the LUN. Once the command completes successfully, client I/O to the LUN is allowed.
• Delete the LUN using the lun delete command with the -force-fenced parameter.

• Use the snapmirror restore command to restore data to the NVMe namespace. Once the command completes successfully, client I/O to the NVMe namespace is allowed.
• Delete the NVMe namespace using the vserver nvme namespace delete command with the -skip-mapped-check parameter.

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.

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