Class: VDI

Last published : Oct 01, 2026
A virtual disk image
Related information
XenServer 8.4 Management API

Fields for class: VDI

Field Type Qualifier Description
allow_caching bool RO/runtime true if this VDI is to be cached in the local cache SR
allowed_operations vdi_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.
cbt_enabled bool RO/runtime True if changed blocks are tracked for this VDI
crash_dumps crashdump ref set RO/runtime list of crash dumps that refer to this disk
current_operations (string -> vdi_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.
is_a_snapshot bool RO/runtime true if this is a snapshot.
is_tools_iso bool RO/runtime Whether this VDI is a Tools ISO
location string RO/runtime location information
managed bool RO/runtime
metadata_latest bool RO/runtime Whether this VDI contains the latest known accessible metadata for the pool
metadata_of_pool pool ref RO/runtime The pool whose metadata is contained in this VDI
missing bool RO/runtime true if SR scan operation reported this VDI as not present on disk
name_description string RO/constructor a notes field containing human-readable description
name_label string RO/constructor a human-readable name
on_boot on_boot RO/runtime The behaviour of this VDI on a VM boot
other_config (string -> string) map RW additional configuration
parent VDI ref RO/runtime Deprecated. This field is always null. Deprecated
physical_utilisation int RO/runtime amount of physical space that the disk image is currently taking up on the storage repository (in bytes)
read_only bool RO/constructor true if this disk may ONLY be mounted read-only
sharable bool RO/constructor true if this disk may be shared
sm_config (string -> string) map RW SM dependent data
snapshot_of VDI ref RO/runtime Ref pointing to the VDI this snapshot is of.
snapshot_time datetime RO/runtime Date/time when this snapshot was created.
snapshots VDI ref set RO/runtime List pointing to all the VDIs snapshots.
SR SR ref RO/constructor storage repository in which the VDI resides
storage_lock bool RO/runtime true if this disk is locked at the storage level
tags string set RW user-specified tags for categorization purposes
type vdi_type RO/constructor type of the VDI
uuid string RO/runtime Unique identifier/object reference
VBDs VBD ref set RO/runtime list of vbds that refer to this disk
virtual_size int RO/constructor size of disk as presented to the guest (in bytes). Note that, depending on storage backend type, requested size may not be respected exactly
xenstore_data (string -> string) map RW data to be inserted into the xenstore tree (/local/domain/0/backend/vbd/<domid>/<device-id>/sm-data) after the VDI is attached. This is generally set by the SM backends on vdi_attach.

RPCs associated with class: VDI

RPC name: addtags

Overview:
Add the given value to the tags field of the given VDI. If the value is already in that Set, then do nothing.
Signature:
void add_tags (session ref session_ref, VDI ref self, string value)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VDI ref self reference to the object
string value New value to add
Minimum Role: vm-operator
Return Type: void

RPC name: addtootherconfig

Overview:
Add the given keyvalue pair to the otherconfig field of the given VDI.
Signature:
void add_to_other_config (session ref session_ref, VDI ref self, string key, string value)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VDI 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: addtosmconfig

Overview:
Add the given keyvalue pair to the smconfig field of the given VDI.
Signature:
void add_to_sm_config (session ref session_ref, VDI ref self, string key, string value)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VDI 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: addtoxenstoredata

Overview:
Add the given keyvalue pair to the xenstoredata field of the given VDI.
Signature:
void add_to_xenstore_data (session ref session_ref, VDI ref self, string key, string value)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VDI 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: clone

Overview:
Take an exact copy of the VDI and return a reference to the new disk. If any driverparams are specified then these are passed through to the storagespecific substrate driver that implements the clone operation. NB the clone lives in the same Storage Repository as its parent.
Signature:
VDI ref clone (session ref session_ref, VDI ref vdi, (string -> string) map driver_params)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VDI ref vdi The VDI to clone
(string -> string) map driver_params Optional parameters that are passed through to the backend driver in order to specify storage-type-specific clone options
Minimum Role: vm-admin
Return Type: VDI ref
The ID of the newly created VDI.

RPC name: copy

Overview:
Copy either a full VDI or the block differences between two VDIs into either a fresh VDI or an existing VDI.
Signature:
VDI ref copy (session ref session_ref, VDI ref vdi, SR ref sr, VDI ref base_vdi, VDI ref into_vdi)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VDI ref vdi The VDI to copy
SR ref sr The destination SR (only required if the destination VDI is not specified
VDI ref base_vdi The base VDI (only required if copying only changed blocks, by default all blocks will be copied)
VDI ref into_vdi The destination VDI to copy blocks into (if omitted then a destination SR must be provided and a fresh VDI will be created)
Minimum Role: vm-admin
Return Type: VDI ref
The reference of the VDI where the blocks were written.
Possible Error Codes: VDI_READONLY, VDI_TOO_SMALL, VDI_NOT_SPARSE

RPC name: create

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

RPC name: datadestroy

Overview:
Delete the data of the snapshot VDI, but keep its changed block tracking metadata. When successful, this call changes the type of the VDI to cbtmetadata. This operation is idempotent: calling it on a VDI of type cbtmetadata results in a noop, and no error will be thrown.
Signature:
void data_destroy (session ref session_ref, VDI ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VDI ref self The VDI whose data should be deleted.
Minimum Role: vm-admin
Return Type: void
Possible Error Codes: SR_OPERATION_NOT_SUPPORTED, VDI_MISSING, SR_NOT_ATTACHED, SR_HAS_NO_PBDS, OPERATION_NOT_ALLOWED, VDI_INCOMPATIBLE_TYPE, VDI_NO_CBT_METADATA, VDI_IN_USE, VDI_IS_A_PHYSICAL_DEVICE

RPC name: destroy

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

RPC name: disablecbt

Overview:
Disable changed block tracking for the VDI. This call is only allowed on VDIs that support enabling CBT. It is an idempotent operation disabling CBT for a VDI for which CBT is not enabled results in a noop, and no error will be thrown.
Signature:
void disable_cbt (session ref session_ref, VDI ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VDI ref self The VDI for which CBT should be disabled
Minimum Role: vm-admin
Return Type: void
Possible Error Codes: SR_OPERATION_NOT_SUPPORTED, VDI_MISSING, SR_NOT_ATTACHED, SR_HAS_NO_PBDS, OPERATION_NOT_ALLOWED, VDI_INCOMPATIBLE_TYPE, VDI_ON_BOOT_MODE_INCOMPATIBLE_WITH_OPERATION

RPC name: enablecbt

Overview:
Enable changed block tracking for the VDI. This call is idempotent enabling CBT for a VDI for which CBT is already enabled results in a noop, and no error will be thrown.
Signature:
void enable_cbt (session ref session_ref, VDI ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VDI ref self The VDI for which CBT should be enabled
Minimum Role: vm-admin
Return Type: void
Possible Error Codes: SR_OPERATION_NOT_SUPPORTED, VDI_MISSING, SR_NOT_ATTACHED, SR_HAS_NO_PBDS, OPERATION_NOT_ALLOWED, VDI_INCOMPATIBLE_TYPE, VDI_ON_BOOT_MODE_INCOMPATIBLE_WITH_OPERATION

RPC name: forget

Overview:
Removes a VDI record from the database
Signature:
void forget (session ref session_ref, VDI ref vdi)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VDI ref vdi The VDI to forget about
Minimum Role: vm-admin
Return Type: void

RPC name: getall

Overview:
Return a list of all the VDIs known to the system.
Signature:
VDI 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: VDI ref set
references to all objects

RPC name: getallrecords

Overview:
Return a map of VDI references to VDI records for all VDIs known to the system.
Signature:
(VDI ref -> VDI 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: (VDI ref -> VDI record) map
records of all objects

RPC name: getallowcaching

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

RPC name: getallowedoperations

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

RPC name: getbynamelabel

Overview:
Get all the VDI instances with the given label.
Signature:
VDI ref set get_by_name_label (session ref session_ref, string label)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
string label label of object to return
Minimum Role: read-only
Return Type: VDI ref set
references to objects with matching names

RPC name: getbyuuid

Overview:
Get a reference to the VDI instance with the specified UUID.
Signature:
VDI 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: VDI ref
reference to the object

RPC name: getcbtenabled

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

RPC name: getcrashdumps

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

RPC name: getcurrentoperations

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

RPC name: getisasnapshot

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

RPC name: getistoolsiso

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

RPC name: getlocation

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

RPC name: getmanaged

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

RPC name: getmetadatalatest

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

RPC name: getmetadataofpool

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

RPC name: getmissing

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

RPC name: getnamedescription

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

RPC name: getnamelabel

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

RPC name: getnbdinfo

Overview:
Get details specifying how to access this VDI via a Network Block Device server. For each of a set of NBD server addresses on which the VDI is available, the return value set contains a vdinbdserverinfo object that contains an exportname to request once the NBD connection is established, and connection details for the address. An empty list is returned if there is no network that has a PIF on a host with access to the relevant SR, or if no such network has been assigned an NBDrelated purpose in its purpose field. To access the given VDI, any of the vdinbdserverinfo objects can be used to make a connection to a server, and then the VDI will be available by requesting the exportname.
Signature:
vdi_nbd_server_info record set get_nbd_info (session ref session_ref, VDI ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VDI ref self The VDI to access via Network Block Device protocol
Minimum Role: vm-admin
Return Type: vdi_nbd_server_info record set
The details necessary for connecting to the VDI over NBD. This includes an authentication token, so must be treated as sensitive material and must not be sent over insecure networks.
Possible Error Codes: VDI_INCOMPATIBLE_TYPE

RPC name: getonboot

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

RPC name: getotherconfig

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

RPC name: getparent

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

RPC name: getphysicalutilisation

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

RPC name: getreadonly

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

RPC name: getrecord

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

RPC name: getsharable

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

RPC name: getsmconfig

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

RPC name: getsnapshotof

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

RPC name: getsnapshottime

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

RPC name: getsnapshots

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

RPC name: getSR

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

RPC name: getstoragelock

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

RPC name: gettags

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

RPC name: gettype

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

RPC name: getuuid

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

RPC name: getVBDs

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

RPC name: getvirtualsize

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

RPC name: getxenstoredata

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

RPC name: introduce

Overview:
Create a new VDI record in the database only
Signature:
VDI ref introduce (session ref session_ref, string uuid, string name_label, string name_description, SR ref SR, vdi_type type, bool sharable, bool read_only, (string -> string) map other_config, string location, (string -> string) map xenstore_data, (string -> string) map sm_config, bool managed, int virtual_size, int physical_utilisation, pool ref metadata_of_pool, bool is_a_snapshot, datetime snapshot_time, VDI ref snapshot_of)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
string uuid The uuid of the disk to introduce
string name_label The name of the disk record
string name_description The description of the disk record
SR ref SR The SR that the VDI is in
vdi_type type The type of the VDI
bool sharable true if this disk may be shared
bool read_only true if this disk may ONLY be mounted read-only
(string -> string) map other_config additional configuration
string location location information
(string -> string) map xenstore_data Data to insert into xenstore
(string -> string) map sm_config Storage-specific config
bool managed Storage-specific config
int virtual_size Storage-specific config
int physical_utilisation Storage-specific config
pool ref metadata_of_pool Storage-specific config
bool is_a_snapshot Storage-specific config
datetime snapshot_time Storage-specific config. When the timezone is missing, UTC is assumed
VDI ref snapshot_of Storage-specific config
Minimum Role: vm-admin
Return Type: VDI ref
The ref of the newly created VDI record.
Possible Error Codes: SR_OPERATION_NOT_SUPPORTED

RPC name: listchangedblocks

Overview:
Compare two VDIs in 64k block increments and report which blocks differ. This operation is not allowed when vdito is attached to a VM.
Signature:
string list_changed_blocks (session ref session_ref, VDI ref vdi_from, VDI ref vdi_to)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VDI ref vdi_from The first VDI.
VDI ref vdi_to The second VDI.
Minimum Role: vm-operator
Return Type: string
A base64 stringencoding of the bitmap showing which blocks differ in the two VDIs.
Possible Error Codes: SR_OPERATION_NOT_SUPPORTED, VDI_MISSING, SR_NOT_ATTACHED, SR_HAS_NO_PBDS, VDI_IN_USE

RPC name: opendatabase

Overview:
Load the metadata found on the supplied VDI and return a session reference which can be used in API calls to query its contents.
Signature:
session ref open_database (session ref session_ref, VDI ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VDI ref self The VDI which contains the database to open
Minimum Role: pool-operator
Return Type: session ref
A session which can be used to query the database

RPC name: poolmigrate

Overview:
Migrate a VDI, which may be attached to a running guest, to a different SR. The destination SR must be visible to the guest.
Signature:
VDI ref pool_migrate (session ref session_ref, VDI ref vdi, SR ref sr, (string -> string) map options)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VDI ref vdi The VDI to migrate
SR ref sr The destination SR
(string -> string) map options Extra parameters. Supports: "dest-img-format" (raw vhd qcow2) to specify the image format to use on the destination SR.
Minimum Role: vm-power-admin
Return Type: VDI ref
The new reference of the migrated VDI.

RPC name: readdatabasepooluuid

Overview:
Check the VDI cache for the pool UUID of the database on this VDI.
Signature:
string read_database_pool_uuid (session ref session_ref, VDI ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VDI ref self The metadata VDI to look up in the cache.
Minimum Role: read-only
Return Type: string
The cached pool UUID of the database on the VDI.

RPC name: removefromotherconfig

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

RPC name: removefromsmconfig

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

RPC name: removefromxenstoredata

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

RPC name: removetags

Overview:
Remove the given value from the tags field of the given VDI. If the value is not in that Set, then do nothing.
Signature:
void remove_tags (session ref session_ref, VDI ref self, string value)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VDI ref self reference to the object
string value Value to remove
Minimum Role: vm-operator
Return Type: void

RPC name: resize

Overview:
Resize the VDI.
Signature:
void resize (session ref session_ref, VDI ref vdi, int size)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VDI ref vdi The VDI to resize
int size The new size of the VDI
Minimum Role: vm-admin
Return Type: void

RPC name: resizeonline

This message is removed.
Overview:
Resize the VDI which may or may not be attached to running guests.
Signature:
void resize_online (session ref session_ref, VDI ref vdi, int size)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VDI ref vdi The VDI to resize
int size The new size of the VDI
Minimum Role: vm-admin
Return Type: void

RPC name: revert

Overview:
Copy the contents of a snapshot to the VDI it's related to. The original contents of the VDI are lost.
Signature:
void revert (session ref session_ref, VDI ref snapshot)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VDI ref snapshot The snapshot to which we want to revert
Minimum Role: vm-power-admin
Return Type: void
Possible Error Codes: UNIMPLEMENTED_IN_SM_BACKEND

RPC name: setallowcaching

Overview:
Set the value of the allowcaching parameter. This value can only be changed when the VDI is not attached to a running VM. The caching behaviour is only affected by this flag for VHDbased VDIs that have one parent and no child VHDs. Moreover, caching only takes place when the host running the VM containing this VDI has a nominated SR for local caching.
Signature:
void set_allow_caching (session ref session_ref, VDI ref self, bool value)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VDI ref self The VDI to modify
bool value The value to set
Minimum Role: vm-admin
Return Type: void

RPC name: setnamedescription

Overview:
Set the name description of the VDI. This can only happen when its SR is currently attached.
Signature:
void set_name_description (session ref session_ref, VDI ref self, string value)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VDI ref self The VDI to modify
string value The name description for the VDI
Minimum Role: vm-admin
Return Type: void

RPC name: setnamelabel

Overview:
Set the name label of the VDI. This can only happen when then its SR is currently attached.
Signature:
void set_name_label (session ref session_ref, VDI ref self, string value)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VDI ref self The VDI to modify
string value The name lable for the VDI
Minimum Role: vm-admin
Return Type: void

RPC name: setonboot

Overview:
Set the value of the onboot parameter. This value can only be changed when the VDI is not attached to a running VM.
Signature:
void set_on_boot (session ref session_ref, VDI ref self, on_boot value)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VDI ref self The VDI to modify
on_boot value The value to set
Minimum Role: vm-admin
Return Type: void

RPC name: setotherconfig

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

RPC name: setreadonly

Overview:
Sets the VDI's readonly field
Signature:
void set_read_only (session ref session_ref, VDI ref self, bool value)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VDI ref self The VDI to modify
bool value The new value of the VDI's read_only field
Minimum Role: vm-admin
Return Type: void

RPC name: setsharable

Overview:
Sets the VDI's sharable field
Signature:
void set_sharable (session ref session_ref, VDI ref self, bool value)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VDI ref self The VDI to modify
bool value The new value of the VDI's sharable field
Minimum Role: vm-admin
Return Type: void

RPC name: setsmconfig

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

RPC name: settags

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

RPC name: setxenstoredata

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

RPC name: snapshot

Overview:
Take a readonly snapshot of the VDI, returning a reference to the snapshot. If any driverparams are specified then these are passed through to the storagespecific substrate driver that takes the snapshot. NB the snapshot lives in the same Storage Repository as its parent.
Signature:
VDI ref snapshot (session ref session_ref, VDI ref vdi, (string -> string) map driver_params)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VDI ref vdi The VDI to snapshot
(string -> string) map driver_params Optional parameters that can be passed through to backend driver in order to specify storage-type-specific snapshot options
Minimum Role: vm-admin
Return Type: VDI ref
The ID of the newly created VDI.

RPC name: update

Overview:
Ask the storage backend to refresh the fields in the VDI object
Signature:
void update (session ref session_ref, VDI ref vdi)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
VDI ref vdi The VDI whose stats (eg size) should be updated
Minimum Role: vm-admin
Return Type: void
Possible Error Codes: SR_OPERATION_NOT_SUPPORTED