USB Passthru XenServer VMs

How to make a USB device seen on a XenServer VM guest

Summary

I have provided a script for the purposes of automating the procedure of attaching and detaching USB mass storage devices from a given VM on XenServer.

This method is particularly useful in environments where USB storage such as removable hard disks is used for storing backups and are rotated on a regular basis.

Requirements

The following is required:
1. XenServer Host.
2. XenCenter installed on the host running the backup software.
3. USB Mass-storage device recognized by XenServer.
4. The usbmount.bat batch script.

Background

In some environments, USB mass storage devices are used for the purposes of backups. In order for this to be effective, the USB storage device is rotated and removed from the server after a backup.

Ordinarily, this process requires you to first confirm that the disk is not in use and then manually perform the detach operation. Similarly, when the disk is re-attached to the server, the storage must be again manually attached to the virtual machine.

Many different backup programs provide the ability to execute programs before and after a backup and using XenServer’s XE utility, it is entirely possible to automate this procedure.

Solution

1. Install XenCenter

The batch program for handling the operation depends on the XE.EXE utility, a command-line interface client for executing commands on XenServer hosts. This utility is included as part of the XenCenter installation, hence XenCenter must be installed on the host on which you intend on running the utility.

If you choose to install XenCenter to a location other than C:\program files\citrix\XenCenter\ please take note of the exact installation path as you will need to modify the batch script accordingly.


2. Modify the usbmount.bat script

Using a text editor such as Notepad, edit the usbmount.txt script according to your requirements. The following attributes must be set:

Set the username, password and address (IP or hostname) of your XenServer host:

SET XE_USERNAME=root
SET XE_PASSWORD=CHANGEME
SET XE_SERVER=xxx.xxx.xxx.xxx

Determine the UUID of the Storage Repository that corresponds with Removable Storage. You can determine this by running the following from within your XenServer host console:
xe sr-list name-label=Removable\ Storage

Once you have the UUID of the Removable Storage, make the change to the script:
REM Removable Storage Repository UUID
SET REMOVABLE_SR_UUID=CHANGEME

Next, determine the UUID of the virtual machine you wish to attach the storage to. To do this, run:
xe vm-list

With the UUID of the VM, make the change to the script:

REM UUID of the VM you wish to attach the USB storage to
SET VM_UUID=CHANGEME

Finally, you need to set the device order. It is important to ensure that there is no overlap and this is done by looking at the number of devices attached to the VM. For example, if only one storage device is currently being used (e.g. virtual hard disk), the next device name to use will be hdb.

REM Device name/order on the VM (e.g. hdb, hdc, hdd...)
SET DEVICE_NAME=hdb

3. Run or Schedule the Batch Program

Once you have made the changes to the batch program, test it by running it from a Command Prompt window. Note that the utility requires a parameter, otherwise it will exit.

To attach the USB storage device to the VM, run:
usbmount.bat attach

To detach the USB storage device from the VM, run:
usbmount.bat detach
Listing of USBMOUNT.BAT

@ECHO OFF
setlocal
REM Attach a USB flash device to a specified VM on XenServer 4.x

REM ------------- EDIT THE OPTIONS BELOW TO SUIT YOUR ENVIRONMENT -------------

REM XenServer Credentials
SET XE_USERNAME=root
SET XE_PASSWORD=CHANGEME
SET XE_SERVER=xxx.xxx.xxx.xxx

REM Removable Storage Repository UUID
SET REMOVABLE_SR_UUID=CHANGEME

REM UUID of the VM you wish to attach the USB storage to
SET VM_UUID=CHANGEME

REM Device name/order on the VM (e.g. hdb, hdc, hdd...)
set DEVICE_NAME=hdb


REM ---------------------------------------------------------------------------

REM XenCenter Path
SET XE_CENTER_PATH=C:\program files\citrix\XenCenter\

REM XE Binary and Baseline Parameters
SET XE_EXEC="%XE_CENTER_PATH%\xe.exe" -s %XE_SERVER% -u %XE_USERNAME% -pw %XE_PASSWORD%

REM Temporary working file
SET TEMP_FILE=%TEMP%/xs-usbmount.tmp


REM ------------ DO NOT EDIT BEYOND THIS LINE ----------------

IF "%1"=="ATTACH" GOTO ATTACH_STORAGE
IF "%1"=="DETACH" GOTO DETACH_STORAGE

REM No parameters
echo Usage USBMOUNT.BAT ^<ATTACH ^| DETACH^>
GOTO END


ETACH_STORAGE
%XE_EXEC% vdi-list sr-uuid=%REMOVABLE_SR_UUID% params=vbd-uuids --minimal > %TEMP_FILE%
SET /P VBD_UUIDS= < %TEMP_FILE%

IF "%VBD_UUIDS%"=="" GOTO NOT_BOUND
%XE_EXEC% vbd-unplug uuid=%VBD_UUIDS%
%XE_EXEC% vbd-destroy uuid=%VBD_UUIDS%
echo.Storage Detached

GOTO END


:ATTACH_STORAGE

REM See if the storage is already bound to a VBD
%XE_EXEC% vdi-list sr-uuid=%REMOVABLE_SR_UUID% params=vbd-uuids --minimal > %TEMP_FILE%
SET /P VBD_UUIDS= < %TEMP_FILE%

IF NOT "%VBD_UUIDS%"=="" GOTO ALREADY_BOUND

%XE_EXEC% vdi-list sr-uuid=%REMOVABLE_SR_UUID% params=uuid --minimal > %TEMP_FILE%
SET /P VDI_UUID= < %TEMP_FILE%

%XE_EXEC% vbd-create vm-uuid=%VM_UUID% device=%DEVICE_NAME% vdi-uuid=%VDI_UUID% --minimal > %TEMP_FILE%
SET /P VBD_UUID= < %TEMP_FILE%

%XE_EXEC% vbd-plug uuid=%VBD_UUID%

echo.VBD UUID attached as: %VBD_UUID%
GOTO END


:ALREADY_BOUND
echo.Removable storage already attached to a VM - aborting.
GOTO END

:NOT_BOUND
echo.Storage device not bound to any VMs - aborting.
GOTO END

:END
endlocal

Why did you copy a post from Citrix's Knowledge Center? http://support.citrix.com/article/CTX118198

The original document was originally posted in October 2008 and revised in July 2009. It hasn't been touched since.

corge said:

Why did you copy a post from Citrix's Knowledge Center? http://support.citrix.com/article/CTX118198

The original document was originally posted in October 2008 and revised in July 2009. It hasn't been touched since.

Click to expand...

Indeed. I can't tell if this guy is a troll or what.