Restore VM

Use the restore vm command to restore a virtual machine (VM) that was previously backed up.

This feature is available only if the client operates as a data mover for IBM Spectrum Protect™ for Virtual Environments.

Restore VM for VMware virtual machines

The restore vm command can be used to restore VMware virtual machines or VMware virtual machine templates.

If the backup-archive client is installed on a separate system that is configured as a vStorage backup server, you can restore full virtual machine backups to the ESX or ESXi server that they came from, or to a different server. To restore a full virtual machine backup to a different server, use the -host option. The backup-archive client copies the data from the IBM Spectrum Protect server over either the LAN or SAN. The client then writes the data directly to the ESX server, by using the transport method that is specified in the client options file.

Restoring a full virtual machine backup creates a new virtual machine; the configuration information and content of the new machine is identical to what it was when the backup occurred. All virtual machine disks are restored to the specified point-in-time, as virtual disks in the newly created virtual machine.

When you restore a specific disk, by using the :vmdk= syntax, an existing virtual machine is updated with the specified virtual disk data. Only the specified disks are restored to the existing virtual machine; other disks in the virtual machine are not altered. The existing virtual machine that you are restoring the disk to must be powered off before you initiate the restore operation.

To create a new virtual machine, specify the -vmname parameter and provide a name for the new virtual machine. The -vmname parameter creates a new virtual machine with a configuration that is identical to what it was when the backup occurred. If you also specify the :vmdk= syntax, data is restored to any disks that are included in the :vmdk= parameters; disks that are not included are restored, but only as unformatted disks that do not contain data.

Virtual machines are restored to their original resource pool, cluster, or folder if the containers exist. During a restore operation, if the destination target (a vCenter or ESXi host) does not have the required containers, the virtual machine is restored to the top-level default location on the target ESXi host. If you use the command-line client to restore a virtual machine, and if the virtual machine cannot be restored to its original inventory location, an informational message (ANS2091I) is displayed. If you use the Java™ GUI to restore a virtual machine, and if the virtual machine cannot be restored to its original inventory location, the informational message is not displayed, but the virtual machine is still restored to the top-level default location.

Data protection tags that were backed up with the run backup vm command are restored with the virtual machine. Data protection tags are used to exclude virtual machines from backups and to specify the retention policy of backups.

Windows operating systems Full virtual machine backups that were previously created by using VMware Consolidated Backup (VCB) can still be restored by using the original VCB restore steps. To restore full virtual machine backups that were created by VCB, see Restoring full VM backups that were created with VMware Consolidated Backup. If you use VCB to restore a virtual machine, use the VMware converter program on the client to move the restored files to a running state on a VMware server. If the backup-archive client is running in a virtual machine, and if you performed a file-level backup of the virtual machine's files with the version 7.1 or earlier client, you can restore the backup versions to the virtual machine by using the command-line interface or the Java GUI.

Supported Clients

Linux operating systems This command is valid on supported Linux clients that are installed on a vStorage backup server for a VMware virtual machine.

Windows operating systems This command is valid on supported Windows clients that are installed on a vStorage backup server for a VMware virtual machine.

Syntax


               .-;---------------------------.   
               V .-vmname1,vmname2---------. |   
>>-REStore VM----+-------------------------+-+------------------>
                 +-VM=vmname1,vmname2------+     
                 +- -VM=vmname1,vmname2----+     
                 +-vmname:vmdk=all-vmdk----+     
                 +-vmname:vmdk=cnfg--------+     
                 +-vmname:vmdk=disk_label--+     
                 +-vmname:-vmdk=disk_label-+     
                 '-VMHost=host1,host2------'     

>--+----------------------------+--+-----------+--+---------+--->
   +- -VMNAme=--+-newVMname---+-+  '- -PREView-'  '-options-'   
   |            +-*-----------+ |                               
   |            +-<timestamp>-+ |                               
   |            +-<date>------+ |                               
   |            '-<time>------' |                               
   +-DATACENTER="myDatacenter"--+                               
   +-HOST="myHost"--------------+                               
   '-DATASTORE="myDatastore"----'                               

>--+---------------------+-------------------------------------><
   '-destinationfilespec-'

Parameters

Any parameter that contains spaces must be enclosed in quotation marks (" ").

vmname

Specify the name of one or more virtual machines that you want to restore. The name is the virtual machine display name. Separate multiple VM names with commas (for example, vm1,vm2,vm5). If you backed up template VMs, the vmname parameter can specify the name of a template VM to restore.

Wildcard characters can be used to select VMs names that match a pattern. An asterisk (*) matches any sequence of characters. A question mark (?) matches any single character. For example:

restore vm VM_TEST* restores all VMs that have names that begin with "VM_TEST".
restore vm VM?? restores any VM that has a name that begins with the letters "VM", followed by 2 characters.

Specifying one or more VMs to restore is required.

vm=vmname

The vm= keyword specifies that the next set of values is a list of virtual machine names. The vm= keyword is the default and is not required.

Wildcard characters can be used in VM names. For the specification of the vmname parameter, see vmname .

In the following example, vm= is specified and commas are used to separate two machine names.

restore vm vm=my_vm1,my_vm2

-vm=vmname

You can exclude a virtual machine from a restore operation by specifying the exclude operator (-) before the vm= keyword.

Use the -vm= keyword to exclude a list of virtual machines from a larger group of VM backups, such as a group of VMs that begin with a VM name pattern. For example, if you need to restore all the VMs that start with Dept99_ but prevent vm2 from being restored, issue the following command:

restore vm vm=Dept99_*;-vm=vm2

Wildcard characters can be used with the -vm= keyword to exclude VM names that match a pattern. For example:

Exclude all files that have test in the host name:
```
-vm=*test*
```
Include all virtual machines with names such as: test20, test25, test29, test2A:
```
vm=test2?
```

Note: You cannot use the exclude operator (-) to exclude a VM host domain. The exclude operator works only at the virtual machine name level.

vmname:vmdk=all-vmdk

This option specifies that all virtual disks (*.vmdk files) are included when the virtual machine is restored. This parameter is the default for vmdk specifications.

Note: This parameter is not valid for restoring VMware virtual machines that were backed up using VCB.

vmname:vmdk=cnfg

This option specifies that the virtual machine configuration information is restored. The configuration information is always restored when a new virtual machine is created. However, by default the configuration is not restored when you update an existing virtual machine with selected virtual disks.

Ordinarily, restoring configuration information to an existing virtual machine fails because the restored configuration information conflicts with the existing virtual machine configuration information. Use this option if the existing configuration file for a virtual machine on the ESXi server has been deleted, and you want to use the backed-up configuration to re-create it.

Note: This parameter is not valid for restoring VMware virtual machines that were backed up using VCB.

vmname:vmdk=disk_label

This option is used to specify the disk label of the virtual disks to include in the restore operation. You specify this option only if you want to selectively restore data from specific disks.

Required: On the restore vm command, the label names of the vmdk files that you want to include (with the vmname:vmdk=disk_label parameter) in a restore VM operation must be specified as the English-language label name. The label name must be as it is displayed in the output of the Backup VM vmname -preview command. Examples of the English vmdk labels are "Hard Disk 1", "Hard Disk 2", and so on.

Note: This parameter is not valid for restoring VMware virtual machines that were backed up using VCB.

vmname:-vmdk=disk_label

This option is used to specify the disk label of one or more virtual disks to exclude from the restore operation.

Note: This parameter is not valid for restoring VMware virtual machines that were backed up using VCB.

vmhost=hostname

This option restores all virtual machines that are defined to the Virtual Center or to the ESX server that is specified on the vmchost option. The host name that you specify must match the fully qualified host name or IP address, as it is specified in the vCenter server Hosts and Clusters view.

Separate multiple host names with commas (for example, host1,host2,host5).

This parameter can include multiple ESX servers that are separated by commas.

When you connect directly to an ESXi or ESX host, the vmchost option applies only if the vmhost is the server that you connect to. If it is not, a warning level message is sent to the console and is recorded in the dsmerror.log file; it is also recorded as a server event message.

If you backed up VM templates, they are included in the restore operation.

VMName=

Specifies the new name for the virtual machine after it is restored, if you do not want to use the name specified by the VM= parameter.

newVMname

Specify a new VM name to use for the restored VM.

The following characters are not supported in names of restored VMs:

: ; ' \ / " ? , < > |

A restore command that includes unsupported characters will fail with error message ANS9117E.

VMware does not support VM names of greater than 80 characters in length.

*

Use the * (asterisk) symbol as a wildcard to represent the original name of the VM that is being restored. Placing valid characters before or after the asterisk creates a prefix or suffix in the name of the restored VM.

The following characters are not supported in names of restored VMs:

: ; ' \ / " ? , < > |

A restore command that includes unsupported characters will fail with error message ANS9117E.

VMware does not support VM names of greater than 80 characters in length.

You can use the * symbol in the following manner:

Use the original VM name for the restored VM name by specifying vmname=*.
Append a suffix to the original VM name for the restored VM. For example, if the original VM name is VM1, you can append the suffix "_restored" to VM1 by specifying the following command:
```
dsmc restore vm VM1 -VMName=*_restored
```
The name of the restored VM is VM1_restored.
Insert a prefix before the original VM name for the restored VM. For example, if the original VM name is VM2, you can insert the prefix "new_" to VM2 by specifying the following command:
```
dsmc restore vm VM2 -vmname=new_*
```
The name of the restored VM is new_VM2.

<timestamp>

Appends a timestamp with the date and time of the restore operation to the name of the restored VM. The <timestamp> parameter is a keyword, and must include the bracket symbols ("<" and ">"). The format for the timestamp string is determined by the DATEFORMAT and TIMEFORMAT options in the dsm.opt file. A dash is used as a delimiter for the timestamp that is returned by the <timestamp> parameter.

For example, to restore two VMs named VM5 and VM6, and append the date and time of restore to the restored VM names, issue the following command:

dsmc restore vm VM5,VM6 -vmn=*_<timestamp>

The names of the restored VMs are VM5_06-22-2017_14-56-55 and VM6_06-22-2017_14-56-55.

<date>

Appends the date of the restore operation to the name of the restored VM. The <date> parameter is a keyword, and must include the bracket symbols ("<" and ">"). The format of the date string is determined by the DATEFORMAT option in the dsm.opt file. A dash is used as a delimiter for the date that is returned by the <date> parameter.

For example, to insert the prefix "new_" before the VM named VM3, and append the restore date to the restored VM name, issue the following command:

dsmc restore vm VM3 -vmname=new_*_<date>

The name of the restored VM is new_VM3_06-22-2017.

<time>

Appends the time of the restore operation to the name of the restored VM. The <time> parameter is a keyword, and must include the bracket symbols ("<" and ">"). The format of the time string is determined by the TIMEFORMAT option in the dsm.opt file. A dash is used as a delimiter for the time that is returned by the <time> parameter.

For example, to append the suffix "_today_" after the VM named VM8, and add the restore time to the restored VM name, issue the following command:

dsmc restore vm VM8 -vmn=*_today_<time>

The name of the restored VM is VM8_today_14-56-55.

Note: This parameter is not valid for restoring VMware virtual machines that are backed up using VCB or if the FROM parameter specifies LOCAL.

DATACENTER

Specifies the name of the data center to restore the virtual machine to as it is defined in the vSphere vCenter. If the data center is contained in a folder, you must specify the -datacenter option when you restore the virtual machine and include the folder structure of the data center in the data center name. For example, the following syntax is valid:

-datacenter=folder_name/datacenter_name

When you restore a virtual machine by using the GUI, you must restore the virtual machine to a different location. If you restore to the original location, you cannot specify the folder name of the data center. Without a folder name to help locate the original data center, the restore operation fails.

Note: This parameter is not valid for restoring VMware virtual machines that were backed up using VCB.

HOST

Specifies the domain name of the ESX host server to restore to as it is defined in the vSphere vCenter.

This parameter is case-sensitive and must be the same value as the host name that is shown in the VMware vSphere Web Client. To confirm the host name in the vSphere Web client, select a host and click Manage > Networking > TCP/IP configuration > DNS.

Note: This parameter is not valid for restoring VMware virtual machines that were backed up using VCB.

DATASTORE

Specifies the VMware datastore to restore the virtual machine to. The datastore can be on a SAN, NAS, iSCSI device, or VMware virtual volume (VVOL). You can specify only one datastore when you restore a virtual machine. If you do not specify a datastore parameter, the virtual machine's VMDK file is restored to the datastore it was on when the backup was created.

Note: This parameter is not valid for restoring VMware virtual machines that were backed up using VCB.

-PREView

Use this parameter to verify the results of a restore operation without restoring any VMs. The -preview parameter provides a list of VMs that will be restored and information about the VMs, such as labels of the hard disks in the VM, and the management class for a VM.

When you issue the -preview parameter with the restore vm command, the restore operation does not start. The restore operation starts only if the -preview parameter is removed from the command.

For more information, see Preview virtual machine restore operations.

destinationfilespec

This parameter applies only to VMware VCB restore operations. It specifies the location where VCB full virtual machine image files are restored. If this option is not specified, the vmbackdir option is used.

Table 1. Restore VM command: Related options used for restoring VMware virtual machines
Option	Where to use
datacenter	Command line or options file. This parameter is not valid for restoring VMware virtual machines that were backed up using VCB.
datastore	Command line or options file. This parameter is not valid for restoring VMware virtual machines that were backed up using VCB.
host	Command line or options file. This parameter is not valid for restoring VMware virtual machines that were backed up using VCB.
inactive	Command line.
pick	Command line. This parameter is not valid for restoring VMware virtual machines that were backed up using VCB.
pitdate	Command line. This parameter is not valid for restoring VMware virtual machines that were backed up using VCB.
pittime	Command line. This parameter is not valid for restoring VMware virtual machines that were backed up using VCB.
vmautostartvm This parameter is only valid when instantaccess is specified as the vmrestoretype value.	Command line or client options file.
vmbackdir	Command line or client options file.
vmbackuplocation	Command line.
vmbackuptype	Command line or client options file.
vmdefaultdvportgroup	Command line or client options file
vmdefaultdvswitch	Command line or client options file
vmdefaultnetwork	Command line or client options file
vmdiskprovision This parameter is only valid when instantrestore is specified for the vmrestoretype value.	Command line or client options file.
vmiscsiserveraddress This parameter is only valid when either instantaccess or instantrestore is specified for the vmrestoretype value.	Command line or client options file.
vmmaxrestoresessions	Command line or client options file.
vmrestoretype	Command line.
vmtempdatastore This parameter is only valid when instantrestore is specified for the vmrestoretype value.	Command line or client options file.
vmvstortransport	Command line or client options file. This parameter is not valid for restoring VMware virtual machines that were backed up using VCB.

Examples

Task

To perform an instant restore or instant access operation from the command line, see Scenarios for running full VM instant access and full VM instant restore from the backup-archive client command line.

Task

Restore the most recent backup version of myVM to its original name. Use the VMware management interface to delete the original virtual machine, before you restore it using this syntax.

dsmc restore vm myvm

Task

Restore the most recent backup version of myvm to a new virtual machine that is created with the name "Test Machine", and with the restore target for the data center, ESX host, and datastore all specified on the command.

dsmc restore vm myvm -vmname="Test Machine" 
  -datacenter="myDatacenter" -host="myHostName" 
   -datastore="myDatastore"

Task

Restore the most recent backup version of myvm with the new name myvm_restored.

dsmc restore vm myvm -vmname="*_restored" 
  -datacenter="myDatacenter" -host="myHostName" 
   -datastore="myDatastore"

Task

Restore the most recent backup version of myvm with a new name, showing date and time, similar to myvm_03-22-2017_14-41-24.

dsmc restore vm myvm -vmname="*_<timestamp>" 
  -datacenter="myDatacenter" -host="myHostName" 
   -datastore="myDatastore"

Task

Restore the most recent backup version of myvm. Restore to a data center named mydatacenter. The data center is within the vCenter; the relative path within the vCenter is dirA/datacenters/.

dsmc restore vm myvm -vmname="Test Machine" 
  -datacenter="dirA/datacenters/myDatacenter" 
  -host="myHostName" -datastore="myDatastore"

Task

Restore a virtual machine template back to the same location and name.

dsmc restore vm vmTemplateName

Task

Restore a virtual machine template to a new location.

dsmc restore vm vmTemplateName -vmname=newName 
  -datastore=newDatastore -host=newHost 
   -datacenter=newDatacenter

Task

Restore only Hard Disk 2 and Hard Disk 3 to the existing virtual machine that is named vm1.

dsmc restore vm "vm1:vmdk=Hard Disk 2:vmdk=Hard Disk 3"

Task

Restore all disks to the existing virtual machine named vm1, but do not restore the data from Hard Disk 4.

dsmc restore vm "vm1:-vmdk=Hard Disk 4"

Task

Restore only the data from Hard Disk 1 to the existing virtual machine vm1; do not update any configuration information.

Note: When you restore an existing virtual machine, the default behavior is to not update the configuration information.

dsmc restore vm "vm1:vmdk=Hard Disk 1:-vmdk=cnfg"

Task

Restore all disks to the existing virtual machine named vm1.

dsmc restore vm "vm1:vmdk=all-vmdk"

This command updates all virtual disks on an existing virtual machine, named vm1. Note that this action is different from the action that is performed by dsmc restore vm vm1, which creates a new virtual machine named vm1 (vm1 must not exist in order for dsmc restore vm vm1 to succeed).

Task

Set a maximum of three sessions to be used for restore operations for virtual disks in the VM vm1:

dsmc restore vm vm1 -vmmaxrestoresessions=3

Task

Restore the VM named Accounts and all VMs that begin with Dept99:

dsmc restore vm Accounts,Dept99*

Task

Restore all VMs that begin with the word "Payroll" but exclude any VMs that contain the word "temp" in the name:

dsmc restore vm vm=Payroll*;-vm=*temp*

Task

Restore the virtual machines VM1, VM2, and VM3 with new VM names that are based on the original VM names. Append the suffix "_restored_" and the date and time of the restore operation to the VM name:

dsmc restore vm vm=VM1,VM2,VM3 -vmname=*_restored_<timestamp>

The restored VMs are named VM1_restored_07-28-2017_13-28-00, VM2_restored_07-28-2017_13-28-00, and VM2_restored_07-28-2017_13-28-00.

Task

Restore all VMs from the host esx03 that were backed up to the IBM Spectrum Protect server, and of all the VMs being restored, restore the VM named esx03-02 without the VM disk Hard Disk 1:

dsmc restore vm VMHOST=esx03.example.com;esx03-2:-vmdk=Hard Disk 1

Task

Restore all virtual machines on ESXi hosts named brovar, doomzoo, and kepler:

dsmc restore vm 
vmhost=brovar.example.com,doomzoo.example.com,kepler.example.com

Task

Verify that the VM named Dept99_VM1 is restored correctly without restoring the VM:

dsmc restore vm VM=Dept99_VM1 -vmname=*_restored -preview

Important: For Windows virtual machines: If you attempt to run a full VM restore of an application protection backup that was created with 2 or more snapshot attempts, the system provider snapshot is present on the restored VM. As the application writes to the disk, the shadow storage space grows until it runs out of disk space.

In general, if application protection was used during a backup, use only application protection restore. When you restore the application, the volume is automatically reverted. However, if you must restore the full VM, you must either revert or delete the shadow copy.

After you restore the entire VM, verify that the restore was successful, and the data is not corrupted. If the data is not corrupted, delete the shadow copy. If the data is corrupted, revert the shadow copy to restore data integrity.

You can determine which shadow copy to delete or revert by looking for the dsmShadowCopyID.txt file in the root directory of each restored volume. This file contains the snapshot IDs of the shadow copies that were created during the snapshot attempts. You can use the diskshadow command delete shadows to delete these IDs, or the revert command to revert the shadow copy. After the delete or revert is completed, you can also delete the dsmShadowCopyID.txt file.

For more information, see INCLUDE.VMSNAPSHOTATTEMPTS.