Month: January 2008

Introduction

This document explains how to use the VCB scripts installed on the proxy as part of the VCB installation to integrate with a backup application.

How VCB Works

VMware Consolidated Backup is a technology that allows users to backup a full image or certain files of a virtual machine while it is running, affording you business continuity and zero downtime. (Currently, file level backups are only available on Windows filesystems.) In order to do this, we leverage VMware’s snapshot technology. In essence, on the backend, the snapshot technology redirects disk I/O from the original vmdk to a delta file so that it frees the lock on the original vmdk and all new writes to disk go onto a new delta file. With the original vmdk free, you can use it read-only and backup your data. (You can only access it read only because since the VM is running, there will be reads from time to time from the original vmdk if necessary from the running VM itself. Your backup will not be the sole user of the vmdk file.)

The instructions for creating the integration are very simple in most cases and only get complex if the default settings won’t work for a given application. Generally, the default settings will work if backup software supports to following features:
1) Relocatable root for backups
2) Ability to associate data with arbitrary hostnames
3) Support for DNS hostnames

If these conditions are not met, there may be a need to customize the VCB scripts.

A VCB backup sequence consists of 7 parts:
1) Optionally quiesce the VM
2) Snapshot the VM
3) Unquiesce the VM (if quiesced)
4) Mount the VMDK
5) Run the backup
6) Unmount the VMDK
7) Remove the snapshot

Backup Vendor Integration Options

The backup vendor has a couple possible integration points: quiesce scripts and/or backup integration. A specific vendor could do either or both. However, without the backup integration, the customer will need some other backup solution.

For quiesce scripts, the backup vendor could provide the scripts needed in steps 1 and 3 to quiesce and unquiesce the applications. This is accomplished by providing scripts to the users and then installing them inside the VM in the as the pre-freeze and post-thaw scripts described on pages 40-41 of the Virtual Machine Backup Guide or here:
http://pubs.vmware.com/vi301/backup/wwh … .4.22.html
Quiescing is important for the integrity of your data. If you don’t quiesce your applications, when you restore from backup, you will end up with the application in your VM as if it had powered down hard. VMware does a quiescing of the filesystem, so that a restore backup doesn’t require a chkdsk or fsck, but it doesn’t do quiescing for applications. Quiescing the applications allow you the opportunity to safely shutdown the applications or commit any logs to databases or do whatever your applications need to do. This way, you can avoid having to replay logs or recover from database logs when you restore. If you do shutdown the application, please note that you can unquiesce the VM immediately after the snapshot is created, so if you do need a window for this, the time should be fairly small. Most applications can be quiesced without being shutdown.

Backup integration is accomplished through the VCB proxy. The backup vendor’s client software is generally recommended to reside on the VCB proxy. This is typically the same or very similar to the client software that would reside on a non-VCB host being backed-up. There are a few hooks into the VCB framework to allow the backup software to mount and unmount the vmdk.

How to Integrate

In order to work with VCB, all a backup client has to do is run a VCB command to snapshot and mount the VM (literally a single command) run its own backup command on the VM disk image or file mount, and then unmount the VM (again a single command). There are some cases where changes to the standard backup client software might be needed, for instance if the backup system can not handle a relocated disk image or file mount by default.

While there are a number of ways to implement the VCB backup process, essentially you just want to create a wrapper around the backup executable to run the extra two commands. You can see examples of the wrappers in the Sample Integrations provided on the VMware website (http://www.vmware.com/download/vi/drivers_tools.html, go down to Consolidated Backup Integration Modules). For instance in the Legato Sample Integration, the wrapper script is called vcb-backup.wsf (which actually runs the main function in vcb-backup.js, where most of the code is). The vcb-backup.js script runs basically the same setup described below, then calls the Networker-specific save command as part of the RunSaveCmd() function, then performs the same cleanup as described below.

You can take a look at the other Sample Integrations to see some different ways of implementing this, though it may be easier to understand and implement something closer to the generic templates.

The generic template script accomplishes all the same steps of the backup integration, but provides a simple and easy to integrate way of creating the wrapper script. Using the generic templates, here’s what you actually need to do to write a VCB integration:

1) Create a directory named after your product under ‘C:\Program Files\VMware Consolidated Backup Framework
2) Copy the content of the generic directory into that directory
3) Make any modifications you need and create your VCB wrapper command in the directory.

Essentially, all you need in the wrapper script is a call to pre-command.wsf, a call to your vendor-specific save command, and a call to post-command.wsf.

In most cases that should be everything you need. If for some reason you need to do something more complex than what the templates let you do, here’s an explanation of how the templates work:

The template files are installed in ‘C:\Program Files\VMware Consolidated Backup Framework’ as part of the standard VCB install. The templates and APIs come from the ‘generic’ directory.
• The generic/glue.js contains API functions for calling the VCB framework (described in more detail below).
• The generic/utils.js scriptfile serves as a library of useful routines.
• The generic/pre-command.wsf file is a template for snapshotting and mounting a VM on the proxy.
• The generic/post-command.wsf scriptfile is a template for cleaning up after a backup.
• The config/config.js file is a user configuration file. The backup vendor should leave the file alone, though they may need to modify it for testing. The file sets some local variables like usernames and passwords that are needed for VCB to run.

The pre-command.wsf script expects 2 arguments, the ID number of the VM to backup (required) and the type of backup (optional and described below). A brief explanation of what the pre-command.wsf command does follows:

1) Loads up an environment from the standard configuration file ($VCBDIR/config/config.js)
1) Loads the API functions from utils.js and glue.js. It uses local copies in the specific integration directory, but you can also load the copies from the generic directory.
2) Makes a call to Util_InitializeConfigVars (part of util.js) to load up the default configuration variables and throw errors if any are not set correctly. Essentially this is verifying that the config.js file (which you already loaded) is correctly formatted and populated. In addition, it sets the Util_vcbPath to the path to the VCB install directory and sets the default mode (which is SAN).
3) Creates a VMInfo object defining the VM to be backed-up. This uses the VMid and the backup type from the command arguments. There is a third argument representing the path within the VM mount directory to be backed-up. This is not used by the template because we are assuming whole VM backups. The legal backup types are vcbBackupTypeUnknown (same as “unknown” on the command line), vcbBackupTypeFile (same as “file” on the command line), and vcbBackupTypeFullVM (same as “fullvm” on the command line).
4) Makes a snapshot of the VM specified and then mounts it using prepare for backup function from glue.js. It’s documented in the script and takes 3 arguments: the VMinfo object representing the VM being backedup, a Boolean representing whether you want VCB to take the snapshot for you, and a Boolean representing whether VCB should discard the snapshot when it is done. The Booleans are generally just some standard global variables documented in the code. It is best to use those. The actual implementation of this uses the vcbmounter command line. In rare cases, you may need to create a new js function to call it if you are trying to do something really unusual. The command syntax is: vcbmounter.exe -h -u -p -a {ipaddr: or name:} -r -t {fullvm,file} -m {mode}

Following the pre-command.wsf file, you would generally call your backup products save command from within the same wrapper file that called pre-command.wsf.

Following that, the post-command.wsf would be called. In the unlikely event you need to change its behavior; but it does the following:

1) Loads up an environment from the standard configuration file
($VCBDIR/config/config.js)
2) Loads the API functions from utils.js and glue.js. It uses local copies in the specific integration directory, but you can also load the copies from the generic directory.
3) Makes a call to Util_InitializeConfigVars (part of util.js) to load up the default configuration variables and throw errors if any are not set correctly. Essentially this is verifying that the config.js file (which you already loaded) is correctly formatted and populated. In addition, it sets the Util_vcbPath to the path to the VCB install directory and sets the default mode (which is SAN).
4) Makes a call to CleanUpAfterBackup (part of glue.js) with the location of the mount point of the VM as the only argument. CleanUpAfterBackup is an API to the command line ‘vcbmounter.exe -U’. If you need to do something crazy, you can access the command line directly using the syntax: vcbmounter.exe -h -u -p -U

Troubleshooting notes:

Hardware requirements: The VCB proxy will need network access to both, the VirtualCenter and ESX servers. It will also need to be presented the same LUNs (LUN numbers need to match) on the storage side that are presented to the ESX hosts (that you’re expecting to backup).

If the vcbMounter command doesn’t work, here are some steps you can go about troubleshooting. You can get additional debug information from the vcbMounter command by appending “-L 6” to end of the command.

If you’re having authentication issues, you can run:
vcbUtil -h -u -p -c ping

If it’s not finding the VM via the name or ip address, you can run:
vcbVmName -h -u -p -s any
This will list all VMs found on that VirtualCenter host. If you don’t have VMware Tools installed inside the guest OS, you will not be able to use ipaddr or name. With this output, you have the opportunity to use moref or uuid.

Looking at the log files will be helpful as well.

Some Log file locations on the VCB proxy server:
vmount service logs – C:\WINDOWS\Temp\vmware-vmount[*]–>vstor log files – C:\WINDOWS\Temp\vmware-vlun[*].log

You can find pre/post script log files under
C:\WINDOWS\Temp\ pre_.log
C:\WINDOWS\Temp\ post_.log
C:\WINDOWS\Temp\ browsestart_.log
C:\WINDOWS\Temp\ browseend_.log

3rd party backup Logs – C:\Documents and Settings\Administrator\Local Settings\Temp

Log files for VirtualCenter:
C:\WINDOWS\Temp\vpx\vpxd-*.log]]>