Class: VBD

Last published : Oct 01, 2026
A virtual block device
Related information
XenServer 9 Management API

Fields for class: VBD

Field Type Qualifier Description
allowed_operations vbd_operations set RO/runtime list of the operations allowed in this state. This list is advisory only and the server state may have changed by the time this field is read by a client.
bootable bool RW true if this VBD is bootable
current_operations (string -> vbd_operations) map RO/runtime links each of the running tasks using this object (by reference) to a current_operation enum which describes the nature of the task.
currently_attached bool RO/constructor is the device currently attached (erased on reboot)
device string RO/constructor device seen by the guest, for example, hda1
empty bool RO/constructor if true this represents an empty drive
metrics VBD_metrics ref RO/runtime Removed. metrics associated with this VBD
mode vbd_mode RO/constructor the mode the VBD should be mounted with
other_config (string -> string) map RW additional configuration
qos_algorithm_params (string -> string) map RW parameters for chosen QoS algorithm
qos_algorithm_type string RW QoS algorithm to use
qos_supported_algorithms string set RO/runtime supported QoS algorithms for this VBD
runtime_properties (string -> string) map RO/runtime Device runtime properties
status_code int RO/runtime error/success code associated with last attach-operation (erased on reboot)
status_detail string RO/runtime error/success information associated with last attach-operation status (erased on reboot)
storage_lock bool RO/runtime true if a storage level lock was acquired
type vbd_type RW how the VBD will appear to the guest (for example, disk or CD)
unpluggable bool RW true if this VBD will support hot-unplug
userdevice string RW user-friendly device name, for example, 0, 1, 2, etc.
uuid string RO/runtime Unique identifier/object reference
VDI VDI ref RO/constructor the virtual disk
VM VM ref RO/constructor the virtual machine

RPCs associated with class: VBD

RPC name: addtootherconfig

Overview:
Add the given keyvalue pair to the otherconfig field of the given VBD.
Signature:
void add_to_other_config (session ref session_ref, VBD ref self, string key, string value)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VBD ref self reference to the object
string key Key to add
string value Value to add
Minimum Role: vm-admin
Return Type: void

RPC name: addtoqosalgorithmparams

Overview:
Add the given keyvalue pair to the qos/algorithmparams field of the given VBD.
Signature:
void add_to_qos_algorithm_params (session ref session_ref, VBD ref self, string key, string value)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VBD ref self reference to the object
string key Key to add
string value Value to add
Minimum Role: vm-admin
Return Type: void

RPC name: assertattachable

Overview:
Throws an error if this VBD could not be attached to this VM if the VM were running. Intended for debugging.
Signature:
void assert_attachable (session ref session_ref, VBD ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VBD ref self The VBD to query
Minimum Role: vm-admin
Return Type: void

RPC name: create

Overview:
Create a new VBD instance, and return its handle.
Signature:
VBD ref create (session ref session_ref, VBD record args)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VBD record args All constructor arguments
Minimum Role: vm-admin
Return Type: VBD ref
reference to the newly created object

RPC name: destroy

Overview:
Destroy the specified VBD instance.
Signature:
void destroy (session ref session_ref, VBD ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VBD ref self reference to the object
Minimum Role: vm-admin
Return Type: void

RPC name: eject

Overview:
Remove the media from the device and leave it empty
Signature:
void eject (session ref session_ref, VBD ref vbd)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VBD ref vbd The vbd representing the CDROM-like device
Minimum Role: vm-operator
Return Type: void
Possible Error Codes: VBD_NOT_REMOVABLE_MEDIA, VBD_IS_EMPTY

RPC name: getall

Overview:
Return a list of all the VBDs known to the system.
Signature:
VBD ref set get_all (session ref session_ref)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Minimum Role: read-only
Return Type: VBD ref set
references to all objects

RPC name: getallrecords

Overview:
Return a map of VBD references to VBD records for all VBDs known to the system.
Signature:
(VBD ref -> VBD record) map get_all_records (session ref session_ref)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Minimum Role: read-only
Return Type: (VBD ref -> VBD record) map
records of all objects

RPC name: getallowedoperations

Overview:
Get the allowedoperations field of the given VBD.
Signature:
vbd_operations set get_allowed_operations (session ref session_ref, VBD ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VBD ref self reference to the object
Minimum Role: read-only
Return Type: vbd_operations set
value of the field

RPC name: getbootable

Overview:
Get the bootable field of the given VBD.
Signature:
bool get_bootable (session ref session_ref, VBD ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VBD ref self reference to the object
Minimum Role: read-only
Return Type: bool
value of the field

RPC name: getbyuuid

Overview:
Get a reference to the VBD instance with the specified UUID.
Signature:
VBD ref get_by_uuid (session ref session_ref, string uuid)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
string uuid UUID of object to return
Minimum Role: read-only
Return Type: VBD ref
reference to the object

RPC name: getcurrentoperations

Overview:
Get the currentoperations field of the given VBD.
Signature:
(string -> vbd_operations) map get_current_operations (session ref session_ref, VBD ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VBD ref self reference to the object
Minimum Role: read-only
Return Type: (string -> vbd_operations) map
value of the field

RPC name: getcurrentlyattached

Overview:
Get the currentlyattached field of the given VBD.
Signature:
bool get_currently_attached (session ref session_ref, VBD ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VBD ref self reference to the object
Minimum Role: read-only
Return Type: bool
value of the field

RPC name: getdevice

Overview:
Get the device field of the given VBD.
Signature:
string get_device (session ref session_ref, VBD ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VBD ref self reference to the object
Minimum Role: read-only
Return Type: string
value of the field

RPC name: getempty

Overview:
Get the empty field of the given VBD.
Signature:
bool get_empty (session ref session_ref, VBD ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VBD ref self reference to the object
Minimum Role: read-only
Return Type: bool
value of the field

RPC name: getmetrics

This message is removed.
Overview:
Get the metrics field of the given VBD.
Signature:
VBD_metrics ref get_metrics (session ref session_ref, VBD ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VBD ref self reference to the object
Minimum Role: read-only
Return Type: VBD_metrics ref
value of the field

RPC name: getmode

Overview:
Get the mode field of the given VBD.
Signature:
vbd_mode get_mode (session ref session_ref, VBD ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VBD ref self reference to the object
Minimum Role: read-only
Return Type: vbd_mode
value of the field

RPC name: getotherconfig

Overview:
Get the otherconfig field of the given VBD.
Signature:
(string -> string) map get_other_config (session ref session_ref, VBD ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VBD ref self reference to the object
Minimum Role: read-only
Return Type: (string -> string) map
value of the field

RPC name: getqosalgorithmparams

Overview:
Get the qos/algorithmparams field of the given VBD.
Signature:
(string -> string) map get_qos_algorithm_params (session ref session_ref, VBD ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VBD ref self reference to the object
Minimum Role: read-only
Return Type: (string -> string) map
value of the field

RPC name: getqosalgorithmtype

Overview:
Get the qos/algorithmtype field of the given VBD.
Signature:
string get_qos_algorithm_type (session ref session_ref, VBD ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VBD ref self reference to the object
Minimum Role: read-only
Return Type: string
value of the field

RPC name: getqossupportedalgorithms

Overview:
Get the qos/supportedalgorithms field of the given VBD.
Signature:
string set get_qos_supported_algorithms (session ref session_ref, VBD ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VBD ref self reference to the object
Minimum Role: read-only
Return Type: string set
value of the field

RPC name: getrecord

Overview:
Get a record containing the current state of the given VBD.
Signature:
VBD record get_record (session ref session_ref, VBD ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VBD ref self reference to the object
Minimum Role: read-only
Return Type: VBD record
all fields from the object

RPC name: getruntimeproperties

Overview:
Get the runtimeproperties field of the given VBD.
Signature:
(string -> string) map get_runtime_properties (session ref session_ref, VBD ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VBD ref self reference to the object
Minimum Role: read-only
Return Type: (string -> string) map
value of the field

RPC name: getstatuscode

Overview:
Get the statuscode field of the given VBD.
Signature:
int get_status_code (session ref session_ref, VBD ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VBD ref self reference to the object
Minimum Role: read-only
Return Type: int
value of the field

RPC name: getstatusdetail

Overview:
Get the statusdetail field of the given VBD.
Signature:
string get_status_detail (session ref session_ref, VBD ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VBD ref self reference to the object
Minimum Role: read-only
Return Type: string
value of the field

RPC name: getstoragelock

Overview:
Get the storagelock field of the given VBD.
Signature:
bool get_storage_lock (session ref session_ref, VBD ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VBD ref self reference to the object
Minimum Role: read-only
Return Type: bool
value of the field

RPC name: gettype

Overview:
Get the type field of the given VBD.
Signature:
vbd_type get_type (session ref session_ref, VBD ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VBD ref self reference to the object
Minimum Role: read-only
Return Type: vbd_type
value of the field

RPC name: getunpluggable

Overview:
Get the unpluggable field of the given VBD.
Signature:
bool get_unpluggable (session ref session_ref, VBD ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VBD ref self reference to the object
Minimum Role: read-only
Return Type: bool
value of the field

RPC name: getuserdevice

Overview:
Get the userdevice field of the given VBD.
Signature:
string get_userdevice (session ref session_ref, VBD ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VBD ref self reference to the object
Minimum Role: read-only
Return Type: string
value of the field

RPC name: getuuid

Overview:
Get the uuid field of the given VBD.
Signature:
string get_uuid (session ref session_ref, VBD ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VBD ref self reference to the object
Minimum Role: read-only
Return Type: string
value of the field

RPC name: getVDI

Overview:
Get the VDI field of the given VBD.
Signature:
VDI ref get_VDI (session ref session_ref, VBD ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VBD ref self reference to the object
Minimum Role: read-only
Return Type: VDI ref
value of the field

RPC name: getVM

Overview:
Get the VM field of the given VBD.
Signature:
VM ref get_VM (session ref session_ref, VBD ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VBD ref self reference to the object
Minimum Role: read-only
Return Type: VM ref
value of the field

RPC name: insert

Overview:
Insert new media into the device
Signature:
void insert (session ref session_ref, VBD ref vbd, VDI ref vdi)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VBD ref vbd The vbd representing the CDROM-like device
VDI ref vdi The new VDI to 'insert'
Minimum Role: vm-operator
Return Type: void
Possible Error Codes: VBD_NOT_REMOVABLE_MEDIA, VBD_NOT_EMPTY

RPC name: plug

Overview:
Hotplug the specified VBD, dynamically attaching it to the running VM
Signature:
void plug (session ref session_ref, VBD ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VBD ref self The VBD to hotplug
Minimum Role: vm-admin
Return Type: void

RPC name: removefromotherconfig

Overview:
Remove the given key and its corresponding value from the otherconfig field of the given VBD. If the key is not in that Map, then do nothing.
Signature:
void remove_from_other_config (session ref session_ref, VBD ref self, string key)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VBD ref self reference to the object
string key Key to remove
Minimum Role: vm-admin
Return Type: void

RPC name: removefromqosalgorithmparams

Overview:
Remove the given key and its corresponding value from the qos/algorithmparams field of the given VBD. If the key is not in that Map, then do nothing.
Signature:
void remove_from_qos_algorithm_params (session ref session_ref, VBD ref self, string key)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VBD ref self reference to the object
string key Key to remove
Minimum Role: vm-admin
Return Type: void

RPC name: setbootable

Overview:
Set the bootable field of the given VBD.
Signature:
void set_bootable (session ref session_ref, VBD ref self, bool value)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VBD ref self reference to the object
bool value New value to set
Minimum Role: vm-admin
Return Type: void

RPC name: setmode

Overview:
Sets the mode of the VBD. The powerstate of the VM must be halted.
Signature:
void set_mode (session ref session_ref, VBD ref self, vbd_mode value)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VBD ref self Reference to the object
vbd_mode value New value to set
Minimum Role: vm-admin
Return Type: void

RPC name: setotherconfig

Overview:
Set the otherconfig field of the given VBD.
Signature:
void set_other_config (session ref session_ref, VBD ref self, (string -> string) map value)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VBD ref self reference to the object
(string -> string) map value New value to set
Minimum Role: vm-admin
Return Type: void

RPC name: setqosalgorithmparams

Overview:
Set the qos/algorithmparams field of the given VBD.
Signature:
void set_qos_algorithm_params (session ref session_ref, VBD ref self, (string -> string) map value)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VBD ref self reference to the object
(string -> string) map value New value to set
Minimum Role: vm-admin
Return Type: void

RPC name: setqosalgorithmtype

Overview:
Set the qos/algorithmtype field of the given VBD.
Signature:
void set_qos_algorithm_type (session ref session_ref, VBD ref self, string value)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VBD ref self reference to the object
string value New value to set
Minimum Role: vm-admin
Return Type: void

RPC name: settype

Overview:
Set the type field of the given VBD.
Signature:
void set_type (session ref session_ref, VBD ref self, vbd_type value)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VBD ref self reference to the object
vbd_type value New value to set
Minimum Role: vm-admin
Return Type: void

RPC name: setunpluggable

Overview:
Set the unpluggable field of the given VBD.
Signature:
void set_unpluggable (session ref session_ref, VBD ref self, bool value)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VBD ref self reference to the object
bool value New value to set
Minimum Role: vm-admin
Return Type: void

RPC name: setuserdevice

Overview:
Set the userdevice field of the given VBD.
Signature:
void set_userdevice (session ref session_ref, VBD ref self, string value)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VBD ref self reference to the object
string value New value to set
Minimum Role: vm-admin
Return Type: void

RPC name: unplug

Overview:
Hotunplug the specified VBD, dynamically unattaching it from the running VM
Signature:
void unplug (session ref session_ref, VBD ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VBD ref self The VBD to hot-unplug
Minimum Role: vm-admin
Return Type: void
Possible Error Codes: DEVICE_DETACH_REJECTED, DEVICE_ALREADY_DETACHED

RPC name: unplugforce

Overview:
Forcibly unplug the specified VBD
Signature:
void unplug_force (session ref session_ref, VBD ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VBD ref self The VBD to forcibly unplug
Minimum Role: vm-admin
Return Type: void