Backup VM

Use the backup vm command to start a full backup of a virtual machine.

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

Backing up VMware virtual machines

Use the backup vm command to back up VMware virtual machines.

One or more virtual machines are backed up by the IBM Spectrum Protect data mover node. Data mover node is the name that is given to a configuration where the backup-archive client runs on a vStorage backup server and is configured to protect the virtual machines in a Virtual Center or ESX/ESXi server. You must configure the VMware virtual machine before you use this command. For information about configuring the VMware virtual machine, see Preparing the environment for full backups of VMware virtual machines.

A full VM backup stores a backup copy of all virtual disk images and configuration information for a virtual machine. Full VM backups enable a complete restore of a virtual machine, but they take more time and more server space than an incremental backup.

If you set vmenabletemplatebackups option to yes, a backup vm operation includes the template VMs, but only if the vStorage backup server is connected to a vCenter Server, and not to an ESX or ESXi host.

If a snapshot fails during backup processing, the client attempts to back up the VMware virtual machine one more time. To control the number of total snapshot attempts, set the INCLUDE.VMSNAPSHOTATTEMPTS option in the client options file.

Data protection tags are used to configure the backup policy of virtual machines in VMware objects. The tags and categories are created when you use one of the following methods:

Enable tagging support on the data mover node with the vmtagdatamover option and run the backup vm command.
Use the IBM Spectrum Protect vSphere Client plug-in to manage IBM Spectrum Protect backups.
Run the set vmtags command on any data mover node.

When the vmtagdatamover option is set to yes, all tags that are assigned to a virtual machine are backed up during backup vm operations. The tags are restored when the restore vm command is run. Tags that are assigned to other inventory objects are not backed up and cannot be restored.

For more information about data protection tags, see Data protection tagging overview.

A Full VM backup uses VMware Changed Block Tracking (CBT) to create content-aware (used-block only) backups. The client enables changed block tracking (CBT) on an ESX or ESXi server when a backup begins. VMware CBT requires an ESX 4.1 (or later) host, with virtual hardware 7 (or later). You cannot perform incremental or full VM content-aware backups on virtual machines that do not support CBT.

When CBT is enabled, it tracks disk changes when I/O operations are processed by the ESX or ESXi server storage stack on the following disks:

A virtual disk that is stored on VMFS; the disk can be an iSCSI disk, a local disk, or a disk that is on a SAN.
A virtual disk that is stored on NFS.
An RDM that is in virtual compatibility mode.

When I/O operations are not processed by the ESX or ESXi storage stack, changed block tracking cannot be used to track disk changes. The following disks cannot use CBT:

An RDM that is in physical compatibility mode.
A disk that is accessed directly from inside a VM. For example, vSphere cannot track changes that are made to an iSCSI LUN that is accessed by an iSCSI initiator in the virtual machine.

Complete information about changed block tracking requirements is described in the VMware Virtual Disk API Programming Guide in the VMware product documentation. In the guide, search for Low Level Backup Procedures and read the Changed Block Tracking on Virtual Disks section.

For VMware servers that do not support CBT, both the used and the unused areas of the disk are backed up and an informational message is logged in the dsmerror.log file. Use the -preview option on the backup vm command to view the current CBT status. CBT status has three values:

Off: Indicates the CBT configuration parameter (ctkEnabled) is not enabled in the virtual machine's configuration parameters. Off is the default state.
Not Supported: Indicates that the virtual machine does not support CBT. Changed-block only backups are not possible.
On: Indicates the virtual machine supports CBT and that CBT is enabled in the virtual machine's configuration parameters (ctkEnabled=true).; The client turns on CBT (it sets ctkEnable=true) with each backup attempt. After the client turns on CBT, it remains on, even if the virtual machine is deleted from the IBM Spectrum Protect server. With CBT enabled, after the first full VM backup is performed, only the changed blocks on the disk are backed up or restored.; If you are no longer performing IBM Spectrum Protect backups of a virtual machine, you can turn off CBT. To turn off CBT, right-click the virtual machine that you want to turn off CBT for in the vSphere client. Click Edit Settings > Options > General > Configuration Parameters. Then, set the ctkEnabled configuration parameter to false.

Tip: You can use the compression option with backups only if the backup is being saved to a storage pool that was enabled for client-side deduplication.

Windows operating systems For more information about compression, see Compression and encryption processing.

You specify the -vmbackuptype and -mode options to indicate how the backups are to be performed. For full VM backups, use -vmbackuptype=fullvm, and specify any of the following mode options:

IFFull: Incremental-forever-full mode. In this mode, a snapshot of all used blocks on a virtual machine’s disks are backed up to the server. You must be licensed to use IBM Spectrum Protect for Virtual Environments: Data Protection for VMware, or IBM Spectrum Protect for Virtual Environments: Data Protection for Microsoft Hyper-V to use this option.
IFIncremental: Incremental-forever-incremental. In this mode, a snapshot is created of the blocks that changed since the last backup. You must be licensed to use IBM Spectrum Protect for Virtual Environments: Data Protection for VMware, or IBM Spectrum Protect for Virtual Environments: Data Protection for Microsoft Hyper-V to use this option.

For information about the incremental-forever backup strategy, see Incremental-forever backup strategy.

Supported Clients

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

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

Syntax


                .-,------.     
                V        |     
              .---vmname-+-.   
>>-Backup VM--+------------+------------------------------------>

>--+--------------------------------+--------------------------->
   | .-,--------------------------. |   
   | V                            | |   
   '---vmname--:vmdk=--disk_label-+-'   

>--+----------------------+--+-----------------------+---------><
   '- -VMBACKUPUPDATEGUID-'  '- -PREView-- --options-'

Parameters

vmname

Specify the name of one or more virtual machines that you want to back up. The name is the virtual machine display name. Separate multiple virtual machine names with commas. If you set the vmenabletemplatebackups option to yes, vmname can specify the name of a template VM to back up.

VMware vCenter allows for two or more virtual machines to have the same display name. However, the backup-archive client requires that all virtual machine names in a vCenter server configuration be unique. To prevent errors during processing, ensure that all virtual machines have a unique display name.

Wildcard characters can be used in virtual machine names that are specified as this parameter. However, wildcard processing differs, depending on which backup mode is used.

For backups that use mode=iffull or mode=ifincremental, wildcards can be used to match VM name patterns. For example:
- backup vm VM_TEST* includes all virtual machines that have names that begin with VM_TEST
- backup vm VM?? includes any virtual machine that has a name that begins with the letters VM, followed by 2 characters

If you do not specify vmname, you can identify the virtual machine with the domain.vmfull option.

:vmdk=disk_label

This keyword is an extension to the vmname. It specifies the label (name) of the virtual machine disk to include in the backup operation. You can exclude a disk by preceding the keyword with the exclusion operator (-). For more ways to include or exclude disks from processing, see Domain.vmfull, Exclude.vmdisk, Include.vmdisk.

-VMBACKUPUPDATEGUID

To use this option, you must have a license agreement to use IBM Spectrum Protect for Virtual Environments: Data Protection for VMware.

This option updates the globally unique identifier (GUID) for the virtual machine that you are backing up. This parameter is intended for use only in the following scenario:

You want to restore a previously backed up virtual machine named ORION. But, before you shut down and replace the copy of ORION that is running in your production environment, you want to verify the configuration of the restored virtual machine before you use it to replace the existing ORION.

You restore the ORION virtual machine and give it a new name: dsmc restore vm Orion -vmname=Orion2
You update and verify the ORION2 virtual machine and determine that it is ready to replace the existing virtual machine that is named ORION.
You power down and delete ORION.
You rename ORION2 so that it is now named ORION.
The next time that you backup ORION, by using either an incremental-forever full, or incremental-forever-incremental backup, you add the -VMBACKUPUPDATEGUID parameter to the backup vm command. This option updates the GUID, on the IBM Spectrum Protect server, so the new GUID is associated with the stored backups for the ORION virtual machine. The chain of incremental backups is preserved; there is no need to delete existing backups and replace them with new backups.

-PREView

This option displays information about a virtual machine, including the labels of the hard disks in the virtual machine, and the management class information for a virtual machine.

You can use the disk labels with the :vmdk= or :-vmdk= keywords to include or exclude disks from a backup operation. The following text is sample output from the -preview parameter:

backup vm vm1 -preview
Full BACKUP VM of virtual machines 'VM1'

vmName:vm1
VMDK[1]Label: Hard disk 1
VMDK[1]Name: [ds5k_svt_1] tsmcetlnx14/tsmcetlnx14.vmdk
VMDK[1]Status: Included
VMDK[2]Label: Hard disk 2
VMDK[2]Name: [ds5k_svt_1] tsmcetlnx14/tsmcetlnx14_1.vmdk
VMDK[2]Status: Excluded - user,Independent,pRDM

This example output from -preview shows that VMDK 2 was excluded by the previous backup. Disks that were included in a backup have a status of Included. Disks that were excluded from the backup have a status of Excluded, followed by a reason code. The reason codes can be any of the following:

user: Indicates that the disk was skipped because it was excluded on a domain.vmfull statement, on the command line, or in the client options file.
Independent: Indicates that the disk is an independent disk. Independent disks cannot be part of a snapshot, so they are excluded from backup vm operations. Ensure that the vmprocessvmwithindependent option is set to yes or the entire virtual machine is bypassed by a backup operation if it contains one or more independent disks.
pRDM: Indicates that the disk is a physical Raw Device Mapped (pRDM) disk. pRDM disks cannot be part of a snapshot, so they are excluded from backup vm operations. Ensure that the vmprocessvmwithprdm option is set to yes or the entire virtual machine is bypassed by a backup operation if it contains one or more raw device mapping (RDM) volumes that are provisioned in physical-compatibility mode (pRDM).

The output from the -preview parameter also shows the management class name that is associated with the virtual machine, along with information about where the management class was set. This information can help you verify whether the domain and tag values are set correctly for the management class. For example:

backup vm -preview
Full BACKUP VM of virtual machines specified in DOMAIN.VMFULL option.

  1. vmName: tag_vm_2
       DomainKeyword:  all-vm
       toolsRunningStatus: guestToolsNotRunning
       toolsVersionStatus: guestToolsNotInstalled
       consolidationNeeded: No
       Change Block Tracking: On
       managementClassName: STANDARD
       managementClassLocation: Node Default

       VMDK[1]Label:   'Hard disk 1' (Hard Disk 1)
       VMDK[1]Name:    '[Raid1-lannds2] tag_vm_2/tag_vm_2.vmdk'
       VMDK[1]Status:  Included
...

12. vmName: vm-jean
       DomainKeyword:  all-vm
       toolsRunningStatus: guestToolsNotRunning
       toolsVersionStatus: guestToolsNotInstalled
       consolidationNeeded: No
       Change Block Tracking: On
       managementClassName: MGMTCLASS1 (invalid)
       managementClassLocation: VM Tag Management Class (IBM Spectrum Protect)

       VMDK[1]Label:   'Hard disk 1' (Hard Disk 1)
       VMDK[1]Name:    '[Raid1-lannds2] vm-jean/vm-jean.vmdk'
       VMDK[1]Status:  Included

where:

managementClassName

Displays the name of the management class that the virtual machine is bound to.

If the "(invalid)" label is shown next to the management class name, either the name was incorrectly specified, the management class was removed on the IBM Spectrum Protect server, or no backup copy group was found in the management class on the server. When the management class name is invalid, the virtual machine backup operation fails.

managementClassLocation

Displays where the management class was set. The following locations are possible:

Node Default: The management class is set on the default domain of the VMware datacenter node.
VMMC option: The management class is set with the vmmc option.
VMCTLMC option: The management class is set with the vmctlmc option.
INCLUDE.VM option: The management class is set with the include.vm option.
VM Tag Management Class (IBM Spectrum Protect): The management class is set as a tag value of the Management Class (IBM Spectrum Protect) tag category. Tag values can be set with data protection settings in the IBM Spectrum Protect vSphere Client plug-in in the vSphere Web Client, or by using tools such as VMware vSphere PowerCLI version 5.5 R2 or later.

Important: In order to display the management class information that is set by tags, you must set the vmtagdatamover yes option in the client options file, or you must include the -vmtagdatamover=yes parameter when you run the dsmc backup vm command. If you did not set the vmtagdatamover option or if it is set to no, the client ignores any management class tag values, and displays the management class definition that is set in the default domain of the datacenter node, the vmmc option, or the include.vm option.

Return codes for virtual machine backup operations

Backup operations for virtual machines can complete with the return codes that are shown in the following table.

Return code	Description
0	A command to back up one or more virtual machines completed successfully.
8	A command to back up multiple virtual machines succeeded for only some of the virtual machines that were targeted by the command. Examine the log file to determine the processing status for each of the targeted virtual machines.
12	Indicates that either of the following error conditions occurred: The backup command could not back up any of the virtual machines that were targets of the backup operation. The backup command failed and it stopped before all virtual machines that were specified were inspected. Examine the log file to determine the reason for the failure.

vStorage API for data protection example commands

Perform an IFIncremental backup of two VMs named vm3 and vm4.

dsmc backup vm vm3,vm4 -vmbackuptype=fullvm -mode=ifincremental

Perform an IFFull backup of a VM named vm1.

dsmc backup vm vm1 -vmbackuptype=fullvm -mode=iffull

Perform an IFFull VM backup of a VM named vm1, but include only Hard Disk 1 in the backup operation.

dsmc backup vm "vm1:vmdk=Hard Disk 1" -vmbackuptype=fullvm -mode=iffull

Perform an incremental-forever backup of a virtual machine that is named vm1, but exclude Hard Disk 1 and Hard Disk 4 from the backup operation.

dcmc backup vm "vm1:-vmdk=Hard Disk 1:-vmdk=Hard Disk 4" 
  -vmbackuptype=fullvm -mode=iffull

Perform an incremental-forever-full backup of two virtual machines that are named vm1 and vm2. On vm1, back up only Hard Disk 2 and Hard Disk 3. On vm2, back up all virtual disks.

dsmc backup vm "vm1:vmdk=Hard Disk 2:vmdk=Hard Disk 3",
  vm2 -vmbackuptype=fullvm -mode=iffull

Perform parallel incremental-forever-full backups of the VMware virtual machines that are selected for backup by using the selection criteria (domain parameters) on the domain.vmfull statement. Set the maximum number of parallel backups to 5 virtual machines and 10 sessions and limit the backups to 5 VMs per host and 5 VMs per datastore.

dsmc backup vm –vmbackuptype=fullvm –mode=iffull –vmmaxparallel=5 
  –vmmaxbackupsessions=10 –vmlimitperhost=5 –vmlimitperdatastore=5