TSM for Virtual Environments

1. Introduction

TSM for Virtual Environments ("TSM for VE") is an HFS service for backing up Virtual Machines that are running in a VMware vSphere infrastructure.  Currently, vSphere 5.0, 5.1, 5.5, 6.0 and 6.5 are supported.

Features of TSM for VE include:

  • "Forever incremental" image-level backups of virtual machines using VMware changed block tracking (CBT).
  • Client-side de-duplication (reduces network traffic).
  • Image-level restores of entire virtual machines.
  • Restores of individual files from image-level backups (using an agent installed in the VM).
  • Restores of individual files from image-level backups (using iSCSI).

There are some limitations. The TSM for VE client cannot backup virtual machines with the following properties:

  • Virtual machines with virtual disks, including RDM disks, greater than 2 TB.
  • Virtual machines with physical RDM disks (virtual RDM disks can be backed up).

There are TSM for VE settings that allow these VMs to be backed up but unsupported disks will be skipped. Contact the HFS team for details.

The Service Level Description is available here.  There is also a talk from the 2015 ICTF conference available.

Access to the service is by application; send an email to hfs@ox.ac.uk to request an account.

2. Prerequisites

2.1 Changed block tracking (CBT) enabled

CBT must be enabled on the virtual machines that you wish to backu up.  WIthout this, TSM will always perform a full backup of a virtual machine which will consume a lot of resources at both the TSM client and TSM server.

2.2. A suitable "proxy" machine

This can be installed on the vSphere infrastructure that you are planning to back up. The machine needs to be running Windows 7 or 2008R2 (or later) and will need at least 2 GB of RAM. If you are planning to back up vSphere 6.5, you will need the version 8.1 client which requires Windows 2012 or later.

2.3. Firewall configuration

When setting up TSM for VE on a proxy machine, several ports are used for communication between the proxy machine and the vCenter server or vice-versa. These ports need to be open in any host-based or dedicated firewall between the two machines and are listed in this table:

Firewall configuration for TSM for VE
Source host Destination port Destination host Use Required?
Proxy machine 443 vCenter server Communication between the proxy machine and the vCenter server. Yes
Proxy machine 902 vCenter server Used for NBD (Network Block Disk) transport. If proxy machine is not a VM.
vCenter server 1527 Proxy Machine Used for the vCenter plugin. Required if installing vCenter plugin. If installing vCenter plugin.
VMs 3260 Proxy Machine Default iSCSI port. If using iSCSI file-level restore.
Proxy machine 3400 dsmdd1.hfs.ox.ac.uk
TSM backup traffic. Destination host will be advised by HFS team on account set up. Yes
vCenter server 9080 Proxy Machine Used for the vCenter plugin. If installing vCenter plugin.

2.4. vCenter server and backup user

TSM for VE communicates with a vCenter server to perform VM backups. The user required for this needs some elevated privileges but does not need to be a full administrator. It is recommended that you set up a new vCenter user specifically for TSM backup and restore. To add a new role suitable for backup and restore operations, perform the following steps:

  1. Log into the vCenter server with the vSphere client.

  2. Navigate to [Home] > [Roles] and click Add Role.

  3. The Add New Role dialogue box is displayed:

    vCenter Add New Role dialogue box

  4. Choose a name for the new role, e.g. "HFS Backup".

  5. Add the following permissions to the role:

    Required privileges for HFS backup vSphere role
    vCenter Server objects Associated privileges that are required
    Allocate space, Browse datastore, Low-level file operations
    Register extension, Unregister extension, Update extension
    Global Licenses, Log Event, Cancel Task
    Host > Configuration Storage partition configuration
    Network Assign network
    Assign virtual machine to resource pool, Migrate powered off virtual machine, Migrate powered on virtual machine
    Tasks Create Task, Update Task
    vApp Add virtual machine, Assign resource pool, Create
    Virtual machine > Configuration
    Add existing disk, Add new disk, Add or remove device, Advanced, Change CPU count, Change resource, Disk change tracking, Disk Lease, Host USB device, Memory, Modify device setting, Raw device, Reload from path, Remove disk, Rename, Reset guest information, Settings, Swapfile placement, Upgrade virtual hardware
    Virtual machine > Guest operations
    Guest Operation Modifications, Guest Operation Program Execution, Guest Operation Queries
    Virtual machine > Interaction Power On, Power Off
    Virtual machine > Inventory Create new, Register, Remove, Unregister
    Virtual machine > Provisioning
    Allow disk access, Allow read-only disk access, Allow virtual machine download
    Virtual machine > Snapshot
    management > State
    Create snapshot, Remove snapshot, Rename snapshot, Revert to snapshot
  6. Create a new user in your vSphere infrastructure. How you do this depends on your local authentication setup.

  7. Navigate to [Home] > [Inventory] > [VMs and Templates].

  8. Right-click on the vCenter server in the list on the left and choose Add Permission.... The Assign Permission dialogue box is displayed:

    vCenter Assign Permissions dialogue box

  9. Click Add.... The Select Users and Groups dialogue is displayed:

    vCenter Select Users and Groups dialogue box

  10. Choose the newly created user from the list and click Add. Click OK.

  11. Choose the HFS backup role created earlier from the Assigned Role drop down in the Assign Permissions dialogue box.

  12. Ensure Propagate to Child Objects is checked and click OK.

  13. You can check that the permission has been assigned correctly by choosing the vCenter server from the navigation pane and then choosing the Permissions tab. You should see the new permission listed.

3. Installation

Note: If you have not yet contacted the HFS team for a TSM for VE account, please do this first by emailing hfs@it.ox.ac.uk.

Note: Depending which packages are installed, this procedure may require a reboot so take care if installing on a VM or machine that performs other tasks.

3.1.  Installing the IBM TSM for VE package

  1. Download the correct installer

  2. Run the downloaded exectuable file.  It is a self-extracting executable file and will extract the contents to a TSMVMWARE_WIN directory inside the current directory.  You need about 1.6 GB of free space for the files.

  3. Change to the TSMVMWARE_WIN directory and run spinstall.exe.  Note that IBM do not sign their installer package.

  4. Follow the prompts and accept the license terms:

  5. From the Installation Type prompt, choose Advanced installation:

  6. From the Advanced Installation Type prompt, choose Install a complete data mover for in-guest application protection.

  7. The installer will install several IBM packages and possibly some prerequisites too (e.g. C++ redistributable packages).

  8. The TSM for VE package istelf will prompt for some input.  Accept the defaults, ensuring that vSPhere Protection is selected at the Environment Protection prompt:

3.2. Configuring TSM for VE

  1. Download the appropriate configuration tool.

  2. For TSM for VE version 7.1, download the latest TSM for VE version 7.1 configuration tool.

  3. For IBM Spectrum Protect for VE version 8.1, download the latest IBM Spectrum Protect for VE version 8.1 configuration tool.

  4. Run TSM for VE config tool.exe.

  5. Fill in the requested information in the form that is displayed.  You will be given the required information by the HFS Team when they have set up your TSM for VE account. Hovering over each item on the form will give more information on that item. Help takes you to this page.

    TSM for VE configuration tool

  6. Click Configure.

  7. Once the configuration is complete, click Exit.

4. Configuration

We have tried to choose reasonable defaults in the configuration file (C:\Program Files\Tivoli\TSM\baclient\tsm4ve.opt). However, there are some configuration options that you may want to adjust to suit your setup. In particular, these are:


This sets the list of VMs that you want to back up. If the proxy machine is a VM on the vCenter server, you should not back it up via itself so add its name to the -VM part of DOMAIN.VMFULL. To exclude virtual machines vm1, vm2 and vm3 from the backups, give them as the value for -VM, separated by commas:

DOMAIN.VMFULL  all-vm;-VM=vm1,vm2,vm3

Note that if the VM name contains spaces, it should not be surrounded by quotes. There should also be no spaces between VM names and the commas. This applies to all DOMAIN.VMFULL options.

To specify explicitly the VMs to backup, use the VM option. For example to backup vm1, vm2 and vm3, use:

DOMAIN.VMFULL vm=vm1,vm2,vm3

VMs can also be specified by vCenter folder, host, host cluster and datastore. To backup specific folders, use:

DOMAIN.VMFULL  vmfolder=folder1,folder2,folder3

To backup specific ESX/ESXi hosts, use:

DOMAIN.VMFULL  vmhost=host1,host2,host3

To backup specific host clusters, use:

DOMAIN.VMFULL  vmhostcluster=cluster1,cluster2,cluster3

To backup specific datastores, use:

DOMAIN.VMFULL  vmdatastore=datastore1,datastore2,datastore3


EXCLUDE.VMDISK excludes the specified virtual disk from backup.  For example, to exclude virtual disk "Hard Disk 2" of virtual machine "vmname":

EXCLUDE.VMDISK vmname "Hard Disk 2"

The second argument is the virtual disk's label, rather than the VMDK file.  The disk label can be obtained from the vSphere client or from the TSM command line with:

backup vm -preview vmname


INCLUDE.VMDISK includes specific virtual disks in the backup of a virtual machine and creates an implicit exclude for all other virtual disks on that virtual machine.  For example, if you have a virtual machine named "vmname" with four virtual disks ("Hard Disk 1" to "Hard Disk 4"), the following would backup "Hard disk 1" and "Hard Disk 2" of "vmname" but not "Hard Disk 3" or "Hard Disk 4":

INCLUDE.VMDISK vmname "Hard Disk 1"
INCLUDE.VMDISK vmname "Hard Disk 2"

The second argument is the virtual disk's label, rather than the VMDK file.  The disk label can be obtained from the vSphere client or from the TSM command line with:

backup vm vmname -mode=ifincr -preview


Maximum number of VM backups to perform in parallel per instance of the TSM client.


Maximum number of VM backups to perform in parallel per ESX or ESXi host.


Maximum number of VM backups to perform in parallel per datastore.

The limit options can be used to ensure that parallel VM backups do not put too much load on any one part of your infrastructure. If you have one ESX/ESXi host and one datastore then all the limits on parallel backups should be equal.

5. Backup virtual machines

5.1. Using the TSM client GUI

  1. Launch the TSM for VE client GUI on the proxy machine using the shortcut on the desktop or in the TSM for VE Start Menu folder.

  2. Choose [Actions] > [Backup VM]. The Backup Virtual Machine window is displayed.

  3. Expand the Virtual Machines item. This displays the ESX/ESXi hosts in the navigation pane. Expand or click on the ESX/ESXi hosts:

    TSM client GUI Backup Virtual Machine window.

  4. Select virtual machines to backup. Choose Incremental Forever - Incremental from the drop down box at the top of the window and click Backup.

  5. The task list window displays the progress:

    Backup Virtual Machine task list window.

  6. For detailed information, click Report:

    Backup Virtual Machine detailed report.

5.2. Using the TSM command line

To back up all virtual machines specified in the DOMAIN.VMFULL option, start the TSM for VE command line client using the shortcut on the desktop or in the TSM for VE Start Menu folder and run:

tsm> backup vm -mode=IFincr

To back up a specific VM, run:

tsm> backup vm 'vmname' -mode=IFincr

6. Restore virtual machines

6.1. Using the TSM client GUI

  1. Launch the TSM GUI client on the proxy machine.

  2. Choose [Actions] > [Restore VM]. The Restore Virtual Machine window is displayed:

    Restore Virtual Machine window.

  3. Choose a VM in the navigation pane. All the available backups of the VM are displayed. Choose a backup and click Restore.

  4. The Restore Destination window is displayed. If you wish to restore to the original location, you need to make sure that there is not a VM with the same name in that location. If you are restoring to a new location, specify as much of the information as necessary. If you specify only a new name the VM will be restored to the original location with the new name

    Restore Destination window.

  5. Click Restore to start the restore.

6.2. Using the TSM command line

  • To restore a virtual machine to the same name and location as it was backed up from:

    tsm> restore vm 'vm name'

    You must ensure that the target VM name no longer exists.

  • To restore a virtual machine to its original location but with a new name:

    tsm> restore vm 'vm name' -vmname='new vm name'
  • To restore a VM to a new name and new location, specify both the name and location:

    tsm> restore vm 'vm name' -vmname='new vm name' -datacenter='data center name' -host='ESXi host name' -datastore='datastore name'

7. Restore individual files

Restoring individual files is achieved by using the Data Protection for VMware Recovery Agent. Launch the Recovery Agent from [Start] > [All Programs] > [Tivoli Storage Manager] > [Data Protection for VMware] > [Data Protection for VMware Recovery Agent]:

Recovery Agent main window.

7.1. Using iSCSI

The most flexible way to restore individual files is by using the Recovery Agent to export a backup as an iSCSI target that the iSCSI initiator on a virtual machine can then mount.

  1. Select [New Tivoli Storage Manager server...] from the Tivoli Storage Manager server drop-down.

  2. Set the following:

    Server address dsmdd1.hfs.ox.ac.uk
    Server port 3400
    Node access method Asnodename
    Authentication node The proxy node name. This is the NodeName setting in tsm4ve.opt
    Password The password for the authentication node
    Target Node The TSM for VE target node. This is the AsNodeName setting in tsm4ve.opt

    Recovery Agent new server dialogue.

    Click OK.

  3. Choose the relevant backup by selecting a Virtual machine, Snapshot and Disk under Select snapshot:

    Recovery Agent select backup.

    Click Mount.

  4. The Select mount destination dialogue is displayed:

    Recovery Agent select mount destination dialogue (iSCSI).

    Choose Mount as an iSCSI target and set a unique (on the proxy machine) iSCSI target name and set the appropriate iSCSI initiator name that corresponds to the virtual machine that will connect to this iSCSI target. Note that port 3260 must be open between the

    Click OK.

  5. The iSCSI target will now be listed in the Mounted Volumes list in the Recovery Agent. Configure the iSCSI initiator on the appropriate VM to mount the target read-only and copy the required files to the VM using standard operating system tools. How to do this is beyond the scope of these instructions as it varies for each operating system.

  6. When the iSCSI target is not needed any longer, unmount it and disconnect the iSCSI initiator from the target. Select the target in the Recovery Agent and click Dismount.

  7. Exit the Recovery Agent by clicking Close.

7.2. Using a Windows mount

You can mount an NTFS backup as a drive letter or in an empty NTFS folder.

  1. Follow the steps for setting up iSCSI until you reach the Select mount destination dialogue.

  2. Select Create virtual volume from selected partition.

  3. Select a partition to mount. You should also select Show only mountable partitions and Mount virtual volume as read only.

  4. Choose either a drive letter or NTFS folder for the partition.

    Recovery Agent select mount destination dialogue (local mount).

    Click OK.

  5. The volume appears in the Mounted Volumes list of the Recovery Agent. Use normal Windows tools to copy files from the mounted volume. When finished, select the volume in the Recovery Agent and click Dismount.
  6. Close the Recovery Agent.

Although the above procedure was run on the TSM for VE proxy machine it is possible to install the recovery agent on a VM to perform local mounts. Contact the HFS team if you wish to do this.

Written by IT Services. Latest revision 18 July 2017