Backing Up and Restoring Virtual Machines in ESX Server 3

Overview

 This document describes how to back up and restore virtual machines on the ESX Server 3 service console command prompt. It walks users through the process of configuring the VCB/service console command line utilities and give an example of how to use vcbMounter and vcbRestore to back up and restore virtual machines from the service console.

General Configuration for VCB/Service Console Utilities

While it is possible to specify all options for vcbMounter and vcbRestore using command line options, it is highly recommended to use the configuration file /etc/vmware/backuptools.conf to set the most common parameters for these tools.

This configuration file is parsed as a bourne shell script, hence it complies with the syntax of the bourne shell:

  • Everything after a # in a line is considered being a comment.
  • No spaces are allowed in variable assignments. FOO="bar" will work, but FOO ="bar" or FOO = "bar", for example, will not.
  • In order to specify "special characters," such as $"'`\, they have to be escaped with a preceding backslash. For example, to specify a the string $erver, \$erver has to be used in the configuration file.
Administrators who are familiar with bourne shell script programming can use all the standard bourne shell mechanisms, such as command execution (for example: 'foo' or use environment variables.

Settable Options

The following options can be set in this configuration file:

VCHOST
The URL of the VirtualCenter instance used to manage the host the backup/restore operation is being performed on. If this host is managed by a VirtualCenter instance, you should make VCHOST point to this VirtualCenter instance. If the ESX Server host the backup/restore operation is being performed on is a standalone host, just specify localhost.

You can use the -h command line option for any VCB/service console command line utility to override this setting.

USERNAME
The user name to use to log into the VirtualCenter instance specified by VCHOST. Note that this user must have sufficient privileges to register/create virtual machines.

You can use the -u command line option for any VCB/COS command line utility to override this setting.

PASSWORD
The password credentials corresponding to USERNAME. While specifying a password in a configuration file in plain text can be an inherent security risk, this mechanism is provided here to allow backups of virtual machines to be performed in a non-interactive way.

Also, the service console should be off-limits for anyone but the ESX Server administrator, which minimizes the potential security risk involved in using this setting.

You can use the -p command line option for any VCB/COS command line utility to override this setting.

VMNAMECACHE
The most common way of identifying a virtual machine for backup purposes is by its DNS name or by its IP address.

Unfortunately, when backing up virtual machines from a stand-alone ESX server, the IP address of a virtual machine is only known to the ESX server when the virtual machine is powered on and running VMware Tools.

In order to be able to perform future backups of a virtual machine on a stand along ESX host even when the virtual machine is powered off, a cache file is maintained. Whenever a virtual machine is backed up, its IP address is added to this cache. This will enable future backups of this virtual machine to be performed regardless of its power state.

VMware recommends that you do not change the default setting.

You can use the -c command line option for vcbMounter to override this setting. vcbRestore does not use this setting.

TEMPDIR
If you are using the secure copy capabilities of the VCB/service console Command Line Utilities, you can use this variable to specify a temporary holding space for your virtual machine data.

This holding space must have enough free storage to hold the largest of your virtual machines.

This setting cannot be overridden from the command line.

Backing up Virtual Machines

 vcbMounter can be used to back up entire virtual machines in the service console. A quiesced snapshot of the virtual machine will be created. This snapshot will then be exported into a set of files contained in a directory that contain enough information to restore the virtual machine later on.

Any file-based third party backup software can be used to back up this set of files.

In order to back up a virtual machine using vcbMounter, two things have to be specified:

  • Which virtual machine should be backed up? There are various ways of identifying a virtual machine. See the section on identifying virtual machines below.
  • Where should the backup go to? VCB/COS supports different transport plugins to either back up the virtual machine to a local directory or back it up to a remote directory using scp. See the section on using transport plugins below.
Performing A Backup

If you have set all the command line options in /etc/vmware/backuptools.conf as described in the section General Configuration for VCB/Service Console Utilities, only the following command line options have to be passed to vcbMounter in order to perform a virtual machine backup:

     vcbMounter -a <virtual_machine_identifier> -r <backup_destination>
For information on identifying virtual machines, see the section on Identifying Virtual Machines below. For information on how to specify a backup destination, see the section on Identifying Where a Virtual Machine Backup Should Go To.

Examples

  • Backing up the virtual machine vm37.company.com to local directory /home/VMs/vm37:

        vcbMounter -a ipaddr:vm37.company.com -r /home/VMs/vm37
  • Backing up the virtual machine vm37.company.com to the directory /backups/VMs/vm37 on the remote server backups.company.com using the user ID vmware:

        vcbMounter -a ipaddr:vm37.company.com -r scp://vmware@backups.company.com:/backups/VMs/vm37
  • Backing up a virtual machine on a standalone ESX host with its .vmx file located in /vmfs/volumes/vol0/vm37.vmx to local directory /home/VMs/vm37:

        vcbMounter -a moref:/vmfs/volumes-vol0/vm37.vmx -r /home/VMs/vm37
Identifying Virtual Machines

The VCB/COS command line utilities can use different mechanisms to specify a virtual machine.

Identifying a Virtual Machine by DNS Name/IP Address

This is the most common case for backup purposes. In order to specify a virtual machine by its DNS Name, or IP address, the following construct can be used:

     ipaddr:<DNS name or IP address>
Example

To refer to the virtual machine vm37.company.com with the IP address 10.17.5.12, either one of the following constructs can be used:

     ipaddr:vm37.company.com
     ipaddr:10.17.5.12

Identifying a Virtual Machine By its MoRef

Internally, VirtualCenter and ESX refer to objects by Managed Object References (MoRef, for short). In general, it is not recommended to use MoRefs to identify virtual machines.

The only exception to this rule is when backing up virtual machines from a standalone ESX host. In this case, the MoRef of the virtual machine will be identical to the path to its .vmx configuration file.

Example

To back up a virtual machine with its .vmx file under /vmfs/volumes/vol0/vm37/vm37.vmx use:

     moref:/vmfs/volumes/vol0/vm37/vm37.vmx
Identifying Where a Backup Should Go

You can either back up a virtual machine to a local directory or to a remote server using scp.

Backing up to a Local Directory

In order to back up a virtual machine to a local directory, you can just specify the path to the directory or use the file transport plugin descriptor.

Example
To back up a virtual machine to local directory /home/VMs/vm37 you can use either one of the following specifiers:

     /home/VMs/vm37
     file:///home/VMs/vm37
Note: In the case of backup, the destination directory must not exist, since it will be created by the backup operation. For the example above this means that the directory /home/VMs has to exist before starting a backup. The directory /home/VMs/vm37 on the other hand must not exist and will be created during backup.

Using scp to Back up To a Remote Server


In order to back up a virtual machine to a remote server using scp, the corresponding scp plugin can be used. In general, the following syntax has to be used for the scp plugin:

     scp://<user>@<host>:<path>
In order to be able to back up virtual machines using scp in an automated way, VMware recommends to use RSA key based authentication to avoid being prompted for a password by scp during backup.

Example

In order to back up a virtual machine to the directory /backup/VMs/vm37 on the remote server backups.company.com using user ID vmware on the remote server, use:

     scp://vmware@backups.company.com:/backups/VMs/vm37
Note: Prior to backup, the directory /backups/VMs must exist on the remote server, while the directory /backups/VMs/vm37 will be created during backup.

Restoring Virtual Machines

Restoring a Virtual Machine to its Original Location

If you have set all the command line options in /etc/vmware/backuptools.conf as described here, only the following command line options have to be passed to vcbRestore in order to perform a virtual machine restore:

     vcbRestore -s <backup_directory>
For information on how to specify a backup directory, see the section on Identifying Where a Virtual Machine Backup Should Go.

Examples

  • Restoring a virtual machine from a local backup directory named /home/VMs/vm37: 
         vcbRestore -s /home/VMs/vm37
  • Restoring a virtual machine from remote server backup.company.com, directory /backups/VMs/vm37, user ID vmware:

         vcbRestore -s scp://vmware@backup.company.com:/backups/VMs/vm37
Restoring a Virtual Machine to a Different Location

When a virtual machine is supposed to be restored to a different location or to a different ESX host, the following configuration information needs to be modified accordingly:

Datastore
The datastore identifies where all the files that a virtual machine is comprised of are supposed to be stored.
The virtual machine's folder path
The folder path defines where the virtual machine will be placed in the VirtualCenter folder hierarchy.
The virtual machine's resource pool
This host-specific configuration item will determine the virtual machine's behavior with respect to DRS (Distributed Resource Scheduling). This will also control on which host the virtual machine will run on in the case of using multiple ESX servers managed by VirtualCenter.
Modifying these settings involves the following steps, which will be discussed in detail below:

  • Making a copy of the virtual machine's catalog file.
  • Determining the new settings for datastores, folderpath and resource pool and modifying the copy of the catalog file.
  • Restoring the virtual machine using the alternate catalog file capabilities of vcbRestore.

Copying the virtual machine's catalog

Every virtual machine backup that has been created using vcbMounter will contain a file named catalog. This file contains summary information about the backed up virtual machine, such as its display name or its power state at the time it was backed up. Furthermore, this file also allows for some basic virtual machine configuration options to be changed.

Restoring a virtual machine to an alternate location is done by making a copy of this catalog file, modifying it and using the modified copy during restore.

Example

Making a copy of the catalog file of a virtual machine backed up under /home/VMs/vm37:

     cp /home/VMs/vm37/catalog /tmp/catalog-vm37

Determining New Settings

Datastores
In order to re-locate all the files a virtual machine is comprised of, you have to edit the datastore paths in your copy of the catalog file. This involves changing the following settings:

  • Any disk.scsi*.diskname settings: The name and location of all the disks associated with this virtual machine.
  • config.vmx The location for the virtual machine's main configuration file.
  • config.suspenddir The location that will contain the memory snapshots when the virtual machine gets suspended.
  • config.logdir The location that will contain the virtual machine's log files.
In general, you will find that all these settings point to the same directory on the same datastore. This is the standard layout for a virtual machine. VMware highly recommends that you keep this standard layout.

The datastore paths used in these settings have the following syntax:

     []
You can obtain a list of valid datastore names from the datastore browser in your VirtualCenter client, or by looking at the file system labels of your VMFS volumes in the service console under /vmfs/volumes.

Folder Path

In order to change the folder path setting for a virtual machine when it is being restored to an alternate location, you first need to determine which folder path the virtual machine is supposed to be restored to. This can be done by using the vcbUtil command line utility.

If you have set all the command line options in /etc/vmware/backuptools.conf as described here, this can be done with the following command:

     vcbUtil -c vmfolders
The folderpath setting in your copy of the virtual machine's catalog file has to be set to one of the folder paths printed out by the command above.

Resource Pools

In order to change the resource pool setting for a virtual machine when it is being restored to an alternate location, you first need to determine which resource pool the virtual machine is supposed to be restored to. This can be done by using the vcbUtil command line utility.

If you have set all the command line options in /etc/vmware/backuptools.conf as described here, this can be done with the following command:

     vcbUtil -c resourcepools
The resourcepool setting in your copy of the virtual machine's catalog file has to be set to one of the folder paths printed out by the command above.

Restoring Using an Alternate Catalog

Now that all the settings in the virtual machine's alternate catalog have been modified, this alternate setting can be used to restore the virtual machine. In general, a virtual machine can be restored using an alternate catalog file by using the -a switch to specify the alternate catalog.

Example
To restore a virtual machine backed up under /home/VMs/vm37 by using the alternate catalog file /tmp/catalog-vm37, use:

     vcbRestore -s /home/VMs/vm37 -a /tmp/catalog-vm37
Non-interactive Use of vcbRestore

By default, vcbRestore will prompt the user what to do in the case of a file already existing or the virtual machine already being known to VirtualCenter.

However, prompting is not the desired behavior if vcbRestore is to be used by a script in a non-interactive way. In this case you can use the -b command line switch to specify a default behavior. Possible default behaviors are:

prompt
Prompt the user what do before overwriting files or virtual machine configurations already known to VirtualCenter.
overwrite
Overwrite any existing files and virtual machine configurations known to VirtualCenter during restore.
keep
Do not replace existing files and virtual machine configurations known to VirtualCenter.
abort
Fail the restore operation when an existing file or a virtual machine configuration already known to VirtualCenter would have to be replaced.