Product documentation
Develop for XenServer
8 Citrix Hypervisor 8.2 CU1
View PDF

Class: VDI

October 11, 2024
Contributed by: 
X X

A virtual disk image

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///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: add_tags

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)
<!--NeedCopy-->

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: add_to_other_config

Overview:

Add the given key-value pair to the other_config field of the given VDI.

Signature:

void add_to_other_config (session ref session_ref, VDI ref self, string key, string value)
<!--NeedCopy-->

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: add_to_sm_config

Overview:

Add the given key-value pair to the sm_config field of the given VDI.

Signature:

void add_to_sm_config (session ref session_ref, VDI ref self, string key, string value)
<!--NeedCopy-->

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: add_to_xenstore_data

Overview:

Add the given key-value pair to the xenstore_data field of the given VDI.

Signature:

void add_to_xenstore_data (session ref session_ref, VDI ref self, string key, string value)
<!--NeedCopy-->

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 driver_params are specified then these are passed through to the storage-specific 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)
<!--NeedCopy-->

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)
<!--NeedCopy-->

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)
<!--NeedCopy-->

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: data_destroy

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 cbt_metadata. This operation is idempotent: calling it on a VDI of type cbt_metadata results in a no-op, and no error will be thrown.

Signature:

void data_destroy (session ref session_ref, VDI ref self)
<!--NeedCopy-->

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)
<!--NeedCopy-->

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: disable_cbt

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 no-op, and no error will be thrown.

Signature:

void disable_cbt (session ref session_ref, VDI ref self)
<!--NeedCopy-->

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: enable_cbt

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 no-op, and no error will be thrown.

Signature:

void enable_cbt (session ref session_ref, VDI ref self)
<!--NeedCopy-->

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)
<!--NeedCopy-->

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: get_all

Overview:

Return a list of all the VDIs known to the system.

Signature:

VDI ref set get_all (session ref session_ref)
<!--NeedCopy-->

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: get_all_records

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)
<!--NeedCopy-->

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: get_allow_caching

Overview:

Get the allow_caching field of the given VDI.

Signature:

bool get_allow_caching (session ref session_ref, VDI ref self)
<!--NeedCopy-->

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: get_allowed_operations

Overview:

Get the allowed_operations field of the given VDI.

Signature:

vdi_operations set get_allowed_operations (session ref session_ref, VDI ref self)
<!--NeedCopy-->

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: get_by_name_label

Overview:

Get all the VDI instances with the given label.

Signature:

VDI ref set get_by_name_label (session ref session_ref, string label)
<!--NeedCopy-->

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: get_by_uuid

Overview:

Get a reference to the VDI instance with the specified UUID.

Signature:

VDI ref get_by_uuid (session ref session_ref, string uuid)
<!--NeedCopy-->

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: get_cbt_enabled

Overview:

Get the cbt_enabled field of the given VDI.

Signature:

bool get_cbt_enabled (session ref session_ref, VDI ref self)
<!--NeedCopy-->

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: get_crash_dumps

Overview:

Get the crash_dumps field of the given VDI.

Signature:

crashdump ref set get_crash_dumps (session ref session_ref, VDI ref self)
<!--NeedCopy-->

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: get_current_operations

Overview:

Get the current_operations field of the given VDI.

Signature:

(string -> vdi_operations) map get_current_operations (session ref session_ref, VDI ref self)
<!--NeedCopy-->

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: get_is_a_snapshot

Overview:

Get the is_a_snapshot field of the given VDI.

Signature:

bool get_is_a_snapshot (session ref session_ref, VDI ref self)
<!--NeedCopy-->

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: get_is_tools_iso

Overview:

Get the is_tools_iso field of the given VDI.

Signature:

bool get_is_tools_iso (session ref session_ref, VDI ref self)
<!--NeedCopy-->

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: get_location

Overview:

Get the location field of the given VDI.

Signature:

string get_location (session ref session_ref, VDI ref self)
<!--NeedCopy-->

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: get_managed

Overview:

Get the managed field of the given VDI.

Signature:

bool get_managed (session ref session_ref, VDI ref self)
<!--NeedCopy-->

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: get_metadata_latest

Overview:

Get the metadata_latest field of the given VDI.

Signature:

bool get_metadata_latest (session ref session_ref, VDI ref self)
<!--NeedCopy-->

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: get_metadata_of_pool

Overview:

Get the metadata_of_pool field of the given VDI.

Signature:

pool ref get_metadata_of_pool (session ref session_ref, VDI ref self)
<!--NeedCopy-->

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: get_missing

Overview:

Get the missing field of the given VDI.

Signature:

bool get_missing (session ref session_ref, VDI ref self)
<!--NeedCopy-->

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: get_name_description

Overview:

Get the name/description field of the given VDI.

Signature:

string get_name_description (session ref session_ref, VDI ref self)
<!--NeedCopy-->

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: get_name_label

Overview:

Get the name/label field of the given VDI.

Signature:

string get_name_label (session ref session_ref, VDI ref self)
<!--NeedCopy-->

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: get_nbd_info

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 vdi_nbd_server_info 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 NBD-related purpose in its purpose field. To access the given VDI, any of the vdi_nbd_server_info 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)
<!--NeedCopy-->

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: get_on_boot

Overview:

Get the on_boot field of the given VDI.

Signature:

on_boot get_on_boot (session ref session_ref, VDI ref self)
<!--NeedCopy-->

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: get_other_config

Overview:

Get the other_config field of the given VDI.

Signature:

(string -> string) map get_other_config (session ref session_ref, VDI ref self)
<!--NeedCopy-->

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: get_parent

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)
<!--NeedCopy-->

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: get_physical_utilisation

Overview:

Get the physical_utilisation field of the given VDI.

Signature:

int get_physical_utilisation (session ref session_ref, VDI ref self)
<!--NeedCopy-->

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: get_read_only

Overview:

Get the read_only field of the given VDI.

Signature:

bool get_read_only (session ref session_ref, VDI ref self)
<!--NeedCopy-->

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: get_record

Overview:

Get a record containing the current state of the given VDI.

Signature:

VDI record get_record (session ref session_ref, VDI ref self)
<!--NeedCopy-->

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: get_sharable

Overview:

Get the sharable field of the given VDI.

Signature:

bool get_sharable (session ref session_ref, VDI ref self)
<!--NeedCopy-->

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: get_sm_config

Overview:

Get the sm_config field of the given VDI.

Signature:

(string -> string) map get_sm_config (session ref session_ref, VDI ref self)
<!--NeedCopy-->

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: get_snapshot_of

Overview:

Get the snapshot_of field of the given VDI.

Signature:

VDI ref get_snapshot_of (session ref session_ref, VDI ref self)
<!--NeedCopy-->

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: get_snapshot_time

Overview:

Get the snapshot_time field of the given VDI.

Signature:

datetime get_snapshot_time (session ref session_ref, VDI ref self)
<!--NeedCopy-->

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: get_snapshots

Overview:

Get the snapshots field of the given VDI.

Signature:

VDI ref set get_snapshots (session ref session_ref, VDI ref self)
<!--NeedCopy-->

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: get_SR

Overview:

Get the SR field of the given VDI.

Signature:

SR ref get_SR (session ref session_ref, VDI ref self)
<!--NeedCopy-->

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: get_storage_lock

Overview:

Get the storage_lock field of the given VDI.

Signature:

bool get_storage_lock (session ref session_ref, VDI ref self)
<!--NeedCopy-->

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: get_tags

Overview:

Get the tags field of the given VDI.

Signature:

string set get_tags (session ref session_ref, VDI ref self)
<!--NeedCopy-->

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: get_type

Overview:

Get the type field of the given VDI.

Signature:

vdi_type get_type (session ref session_ref, VDI ref self)
<!--NeedCopy-->

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: get_uuid

Overview:

Get the uuid field of the given VDI.

Signature:

string get_uuid (session ref session_ref, VDI ref self)
<!--NeedCopy-->

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: get_VBDs

Overview:

Get the VBDs field of the given VDI.

Signature:

VBD ref set get_VBDs (session ref session_ref, VDI ref self)
<!--NeedCopy-->

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: get_virtual_size

Overview:

Get the virtual_size field of the given VDI.

Signature:

int get_virtual_size (session ref session_ref, VDI ref self)
<!--NeedCopy-->

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: get_xenstore_data

Overview:

Get the xenstore_data field of the given VDI.

Signature:

(string -> string) map get_xenstore_data (session ref session_ref, VDI ref self)
<!--NeedCopy-->

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)
<!--NeedCopy-->

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: list_changed_blocks

Overview:

Compare two VDIs in 64k block increments and report which blocks differ. This operation is not allowed when vdi_to is attached to a VM.

Signature:

string list_changed_blocks (session ref session_ref, VDI ref vdi_from, VDI ref vdi_to)
<!--NeedCopy-->

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 string-encoding 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: open_database

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)
<!--NeedCopy-->

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: pool_migrate

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)
<!--NeedCopy-->

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 Other parameters

Minimum Role: vm-power-admin

Return Type: VDI ref

The new reference of the migrated VDI.

RPC name: read_database_pool_uuid

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)
<!--NeedCopy-->

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: remove_from_other_config

Overview:

Remove the given key and its corresponding value from the other_config 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)
<!--NeedCopy-->

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: remove_from_sm_config

Overview:

Remove the given key and its corresponding value from the sm_config 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)
<!--NeedCopy-->

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: remove_from_xenstore_data

Overview:

Remove the given key and its corresponding value from the xenstore_data 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)
<!--NeedCopy-->

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: remove_tags

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)
<!--NeedCopy-->

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)
<!--NeedCopy-->

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: resize_online

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)
<!--NeedCopy-->

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: set_allow_caching

Overview:

Set the value of the allow_caching 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 VHD-based 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)
<!--NeedCopy-->

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: set_name_description

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)
<!--NeedCopy-->

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: set_name_label

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)
<!--NeedCopy-->

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: set_on_boot

Overview:

Set the value of the on_boot 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)
<!--NeedCopy-->

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: set_other_config

Overview:

Set the other_config field of the given VDI.

Signature:

void set_other_config (session ref session_ref, VDI ref self, (string -> string) map value)
<!--NeedCopy-->

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: set_read_only

Overview:

Sets the VDI’s read_only field

Signature:

void set_read_only (session ref session_ref, VDI ref self, bool value)
<!--NeedCopy-->

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: set_sharable

Overview:

Sets the VDI’s sharable field

Signature:

void set_sharable (session ref session_ref, VDI ref self, bool value)
<!--NeedCopy-->

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: set_sm_config

Overview:

Set the sm_config field of the given VDI.

Signature:

void set_sm_config (session ref session_ref, VDI ref self, (string -> string) map value)
<!--NeedCopy-->

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: set_tags

Overview:

Set the tags field of the given VDI.

Signature:

void set_tags (session ref session_ref, VDI ref self, string set value)
<!--NeedCopy-->

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: set_xenstore_data

Overview:

Set the xenstore_data field of the given VDI.

Signature:

void set_xenstore_data (session ref session_ref, VDI ref self, (string -> string) map value)
<!--NeedCopy-->

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 read-only snapshot of the VDI, returning a reference to the snapshot. If any driver_params are specified then these are passed through to the storage-specific 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)
<!--NeedCopy-->

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)
<!--NeedCopy-->

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

Class: VDI
October 11, 2024
Contributed by: 
X X
October 11, 2024
Contributed by: 
X X

In this article

Site feedback | Your privacy choices footer linkYour Privacy Choices | Privacy and legal terms | Consent settings | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.