Restore VM

If the VM that you are restoring exists on the Hyper-V host server, it is shut down and deleted before it is restored from the image that is stored on the IBM Spectrum Protect server. The restore operation then creates the VM such that its content and configuration is identical to what it was when the backup occurred. Even though the VM is shut down before it is deleted, manually shutting down the VM before you run the restore vm command is a good practice to bring any in-progress application activities to an orderly stop.

Parameters

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

vmname

Specify the name of one or more VMs that you want to restore. The name is the VM 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.

You must specify one or more VMs to restore.

vm=vmname

The vm= keyword specifies that the next set of values is a list of VM 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 VM from a restore operation by specifying the exclude operator (-) before the vm= keyword.

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

restore vm vm=Dept99_*;-vm=Dept99_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 VMs with names such as: test20, test25, test29, and test2A:

  vm=test2?

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

vmname:vhdx=disk_location

This parameter specifies the VM hard disk (VHDX) to include in Hyper-V VM restore operations. Specify this option only if you want to restore one or more specific disks, but not all disks.

The vmname variable specifies the name of the VM to restore. Wildcard characters can be used to select VM names that match a pattern. An asterisk (*) matches any sequence of characters. A question mark (?) matches any single character.

The :vhdx=disk_location keyword specifies the location of the VM disk to include in the restore operation. The disk location is specified in the format "controller_type controller_number disk_location_number_inside_controller". The controller type must be "SCSI" or "IDE". For example:

dsmc restore vm "vm1:vhdx=IDE 1 0"

If you specify multiple VM disks to include, the vhdx= keyword and associated values must be separated by colons, with no intervening space characters. For example:

dsmc restore vm "*:vhdx=IDE 1 0:vhdx=SCSI 0 1"

If you specify multiple VM names and VM disks, the VM name and associated values must be separated by semicolons, with no intervening space characters. For example:

dsmc restore vm "vm1:vhdx=IDE 1 0:vhdx=SCSI 0 1;vm2:vhdx=IDE 1 0:vhdx=SCSI 0 1"

The following considerations apply to each disk that you want to restore:

• The disk must exist on the VM before you initiate the restore operation. If the disk does not exist, you must create it. You can use the -preview parameter to identify the original disk name and capacity.
• The existing disk must be at least as large as the disk that you want to restore.
• The existing disk location must be the same as the disk that you want to restore.
• Any data on the existing disk is overwritten.

Only the specified disks are restored. Other disks on the VM are not altered.

The VM that you are restoring the disk to must be powered off before you initiate the restore operation.

vmname:-vhdx=disk_location

The vmname variable specifies the name of the VM to restore. Wildcard characters can be used to select VM names that match a pattern. An asterisk (*) matches any sequence of characters. A question mark (?) matches any single character.

This -vhdx=disk_location option is used to specify the disk location of one or more virtual disks to exclude from restore operations. For example, use -vhdx= to exclude a VM disk from the restore operation of a VM:

dsmc restore vm "vm1:-vhdx=IDE 1 0:-vhdx=SCSI 0 1"

If you specify multiple VM disks to exclude, the -vhdx= keyword and associated values must be separated by colons, with no intervening space characters. For example:

dsmc restore vm "*:-vhdx=IDE 1 0:-vhdx=SCSI 0 1"

If you specify multiple VM names and VM disks, the VM name and associated values must be separated by semicolons, with no intervening space characters. For example:

dsmc restore vm "vm1:-vhdx=IDE 1 0:-vhdx=SCSI 0 1;vm2:-vhdx=IDE 1 0:-vhdx=SCSI 0 1"

-VMName=

Specifies the new name for the VM after it is restored, if you do not want to use the name specified by the VM= parameter. Ensure that you enclose the new VM name in double quotation marks.

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.

*

The * (asterisk) symbol is a metacharacter that represents 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.

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 names are VM1 and VM2, you can append the suffix "_restored" to the original VM names by specifying the following command:

  dsmc restore vm VM1,VM2 -VMName="*_restored"

  The names of the restored VMs are VM1_restored and VM2_restored.

• Insert a prefix before the original VM name for the restored VM. For example, if the original VM name is VM3, you can insert the prefix "new_" to VM3 by specifying the following command:

  dsmc restore vm VM3 -vmname="new_*"

  The name of the restored VM is new_VM3.

<timestamp>

Appends a time stamp 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 time stamp string is determined by the DATEFORMAT and TIMEFORMAT options in the dsm.opt file. A dash is used as a delimiter for the time stamp 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.

-targetpath=

Specifies the path that you want to restore the VM to.

This parameter is required if the -vmname parameter is used and optional otherwise. Use this parameter to restore the VM to an alternative path.

-PREView

Use this parameter to verify the results of a restore operation without restoring VMs. The -preview parameter provides a list of VMs that will be restored and information about the VMs, such as the names of virtual hard disks and the size of the disks.

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.