Restore

Use this vmcli command to restore backups of your VMs or VM templates.

Syntax

The vmcli -f restore command uses this syntax:

You must issue the vmcli -f restore command as tdpvmware user, and not as root.

Parameters

The vmcli -f restore command requires that the VE_VCENTER_NODE_NAME is set correctly in the vmcliprofile. You cannot overwrite this parameter with a command-line entry.

The data mover system (the vStorage Backup Server where the data mover is installed) must not set the ASNODENAME option.

-I restoreObjectListFile

Specify the file that contains the list of VMs to restore. Each line can contain only one VM identifier.

The restoreObjectListFile uses the following keyword:

backupid: Each line must begin with the backupid. The syntax is backupid:your_backup_ID. Specify the IBM Storage Protect Object ID for a specific VM backup. Locate the Object ID by using the vmcli -f inquire_detail command. This keyword is required for a restore operation.

The restoreObjectListFile uses the following keywords:

vmname

Specify the name of the VM that was originally backed up. If this keyword is not specified, the name vmname is used for the restore.

Restriction: Restrictions: When you specify a keyword in the restoreObjectListFile, Data Protection for VMware does not differentiate between a colon (:) used as a keyword separator or a colon that is used in a keyword value. Therefore, use caution when you specify keyword values. In addition, Data Protection for VMware support for VM restore operations is limited to VM names and VMware datacenter names that contain English 7-bit ASCII characters only. VM names and datacenter names that use other language characters are not currently supported. Additional character restrictions are listed in Troubleshooting.

vmname

Specify the name that you want the restored VM to be named. This keyword is the second entry. Existing VMs are not overwritten. Therefore, either rename the VM (by using this keyword) or delete the original VM before you issue the vmcli -f restore command.

-vmdk=cnfg

Specify that the virtual machine configuration information is restored. The configuration information is always restored when the entire virtual machine is restored. However, by default the configuration is not restored when you restore only selected disks with the vmdk=disk label option.

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 ESX server was deleted, and you want to use the backed up configuration to re-create it.

For example, this entry in restoreObjectListFile restores all VMDKs for virtual machine VM1 and keeps the same name:

backupid:26801107 vmname:VM1:-vmdk=cnfg

vmdk=disk label

If Change Block Tracking (CBT) is enabled on the target VM, SAN transport is not supported. If a VM with multiple disks has been backed up using Data Protection for VMware and a restore is done from one or more disks to the existing VM using SAN transport method, this restore will fail if Change Block Tracking (CBT) is enabled for this VM.

In vSphere mode, specify the disk label of a virtual disk to include in the restore operation. Use this parameter only if you want to restore one or more specific disks, but not all disks. Repeat this parameter for each disk that you want to restore.

For example, this entry in restoreObjectListFile restores the VMDKs named Hard Disk 1 and Hard Disk 2 as a new virtual machine.

backupid:26801107 
vmname:myvm:vmdk=Hard Disk 1:vmdk=Hard Disk 2::vmname:newname

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 run the dsmc dsmc restore vm command with the -preview parameter to identify the original disk label, capacity, and datastore. The -preview output does not include provisioning information.
- The existing disk must be at least as large as the disk you want to restore.
- The existing disk label must be the same as the disk 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.

-vmdk=disk label

Specify the disk label of one or more virtual disks to exclude from the restore operation.

For example, this entry in restoreObjectListFile restores all VMDKs except the one named Hard Disk 1 as a new virtual machine:

backupid:26801107 
vmname:myvm:-vmdk=Hard Disk 4::vmname:newname

This entry restores VMDKs for the virtual machine as a new virtual machine without configuration information:

backupid:26801107 
vmname:oldvmname:-vmdk=cnfg::vmname:newname

newdatacentername

When you want the restore destination to be a different datacenter, specify the name of that datacenter with this keyword.

newesxhostname

When you want the restore destination to be a different ESX host, specify the name of that ESX host with this keyword.

newdatastoreurl

Specify the name (not the URL) of the VMware datastore where the VM is to be restored. For example, a datastore name such as datastore1 is supported. A datastore URL such as sanfs://vmfs_uuid:4d90pa2d-e9ju45ab-065d-00101a7f1a1d/ is not supported. The datastore can be on a SAN, NAS, iSCSI device, or VMware virtual volume (vVol).

vmtempdatastore

When you want to issue an instant restore operation, specify a temporary datastore on the ESX host. This temporary datastore contains the configuration information and data of the VM that is created during the operation.

vmautostartvm

When a VM is created for instant access (vmrestoretype instantaccess), specify whether to automatically start the VM:

YES: The VM created for instant access is automatically started.
NO: The VM created for instant access is not automatically started. It must be manually started by the user. This value is the default.

vmdiskprovision

Specify the type of provisioning for the VM disk that is restored during an instant restore process (vmrestoretype instant):

THICK: The disk is created with thick provisioning. This value is the default.
THIN: The disk is created with thin provisioning.

An example restoreObjectListFile:

# restore of VM "678912345" named "vmName6" to new vmname "vm6newName" to datacenter
"DataCenter2" to ESX esxhostname:esxHost1Name to new datastore "datastore2"
backupid:678912345 vmname:vmName6::vmname:vm6newName newdatacentername:DataCenter2 
newesxhostname:esxHost1Name newdatastoreurl:datastore2 vmtempdatastore:datastore2temp
 vmdiskprovision:thin

Each restore specification must be on a single line. However, for the sake of page formatting, the restore specification in this example is on multiple lines.

The restoreObjectListFile uses the following keywords for mount operations:

vmostype

Specify the type of operating system for the backed up VM.

AUTOMATIC: The operating system of the backed up VM is automatically detected. This value is the default.
LINUX: The operating system of the backed up VM is Linux.
WINDOWS: The operating system of the backed up VM is Windows.

exportfs

Exports the mounted file system to the location specified by the value of the exportparameter.

YES: The mounted file system is exported.
NO: The mounted file system is not exported. This value is the default.

exportparameter

The location where the file system is exported.

IP or machine name: The IP address or name of the machine that mounts the exported file system.
user name: The user name that is allowed to access Windows Share. It is the user's responsibility to be aware of which users and groups have access to their shared files.

mountpoint mount point path

Specify the path of the mount point.

The default value is /mnt/vmname.

The default value is D:\tsmvemount\vmname.

mounttag string

This string is text that you enter to make the mount point name easier to identify when you search on the local file system. Specify this string as part of the mount path.

The full path to a disk is /mount root/tag/vmname/snapshot date and time/file system number. For example:

/mnt/tickel-4711/VM1/2013-12-12-12:12:12/disk1

The full path to a disk is mount root\tag\vmname\snapshot date and time\file system number. For example:

C:\Users\Admin\tickel-4711\VM1\2013-12-12-12:12:12\disk1

An example restoreObjectListFile for mount operations:
Linux operating systems


backupid:1167852  vmname:VM-Lin4 mounttag:limor exportparameters:9.123.456.78
exportfs:yes vmostype:linux  mountpoint:/tmp/tsm-mounts

backupid:1167850  vmname:VM-Name3 mounttag:limor exportparameters:WinUser1
exportfs:yes vmostype:windows  mountpoint:C:\temp\mnt

An example restoreObjectListFile is provided here:


# restore of VM "678912345" named "vmName6" to new vmname "vm6newName" to datacenter
"DataCenter2" to ESX esxhostname:esxHost1Name to new datastore "datastore2"
backupid:678912345 vmname:vmName6::vmname:vm6newName newdatacentername:DataCenter2 
newesxhostname:esxHost1Name newdatastoreurl:datastore2 vmtempdatastore:datastore2temp
 vmdiskprovision:thin

Each restore specification must be on a single line. However, for the sake of page formatting, the restore specification in this example is on multiple lines.

Tip: To make sure that correct information is specified in the restoreObjectListFile, you can issue the inquire_detail command. Inquire_detail provides current configuration information about the backup environment.

-d datacenternodename

Specify the datacenter node name.

-o datamovernodename

Specify the data mover node name. This name is for the backup-archive client node that is installed on the vStorage Backup Server. This node performs the data movement.

[-s tsmserverhostname]

Specify the host name or IP address of the IBM Storage Protect server. If this parameter is not specified, the value in the profile is used.

[-n vmclinodename]

Specify the VMCLI node name. This name is the node that connects the Data Protection for VMware command-line interface to the IBM Storage Protect server and the data mover node. If this parameter is not specified, the value in the profile is used.

[-p tsmserverport]

Specify the port of the IBM Storage Protect server.

If this parameter is not specified in the Data Protection for VMware command-line interface and not specified in the profile, the default port (1500) is used.
If this parameter is not specified in the Data Protection for VMware command-line interface but is specified in the profile, the value in the profile is used.

In a vSphere environment, specify this option to switch between the following operations: existing restore, instant access, or instant restore. Instant access and instant restore capability is supported only for VMware VMs that are hosted on VMware ESXi 5.1 servers, or later versions. The vmrestoretype parameter uses the following keywords:

noninstant: A full VM restore is issued.
instantrestore: The VM is started during the restore process.
instantaccess: The VM might be started but it is not restored.
mount: The volumes of the VM defined in the input file are mounted in read-only mode on the data mover. On Linux, all the volumes of the VM are mounted as a Network File System (NFS). On Windows, all the volumes of the VM are mounted as a Common Internet File System (CIFS).
vmcleanup: Components that are no longer needed are cleaned up.
vmfullcleanup: The VM and all its components are cleaned up, regardless of the current state.
mountcleanup: All mounted volumes of the selected VM are cleaned up. This cleanup task includes removing file systems that were exposed for the restore operation and the file shares (CIFS, NFS).

Restriction: When an instant restore or instant access operation that is issued from the data mover (dsmc) is followed by an instant restore or instant access operation that is issued from the Data Protection for VMware command-line interface (vmcli) or Data Protection for VMware vSphere GUI, the TDPVMwareMount service must be restarted. This situation applies only when the Data Protection for VMware command-line interface accesses the IBM Storage Protect server with a node name different from the one used by the data mover. This restriction applies to any order of operations between the two products.

Restart the service by going to Start > Administrative Tools > Computer Management > Services and Applications > Services. Look for service name IBM Storage Protect recovery agent in the Services window. The path to the Services window might vary depending on your operating system.

The service does not have to be restarted when the VMware datacenter name is specified with the asnodename option in the dsm.opt file.

-w vmBackupLocation

Specifies the location of the backups from which to restore the VM. You can specify one of the following values:

SERVER: The VM is restored from the IBM Storage Protect server. This value is the default.
LOCAL: The VM is restored from a persisted snapshot on the hardware storage. By restoring from a local snapshot, you can only revert an existing VM. You cannot restore a deleted VM, and you cannot restore a VM to a different name or location.

This parameter is not valid when the vmrestoretype parameter is also specified, unless the vmrestoretype is set to mountcleanup.