Exporting a bitmap that shows the changed blocks between two VDIs
set_on_boot
Setting the on_boot field of the VDI
blocked
Operations on this VDI are temporarily blocked
vdi_type
Values:
system
a disk that may be replaced on upgrade
user
a disk that is always preserved on upgrade
ephemeral
a disk that may be reformatted on upgrade
suspend
a disk that stores a suspend image
crashdump
a disk that stores VM crashdump information
ha_statefile
a disk used for HA storage heartbeating
metadata
a disk used for HA Pool metadata
redo_log
a disk used for a general metadata redo-log
rrd
a disk that stores SR-level RRDs
pvs_cache
a disk that stores PVS cache data
cbt_metadata
Metadata about a snapshot VDI that has been deleted: the set of blocks that changed between some previous version of the disk and the version tracked by the snapshot.
on_boot
Values:
reset
When a VM containing this VDI is started, the contents of the VDI are reset to the state they were in when this flag was last set.
persist
Standard behaviour.
Fields
boolallow_caching[RO/runtime]
true if this VDI is to be cached in the local cache SR
Default value:
false
Published in:
XenServer 5.6 FP1 (cowley)
true if this VDI is to be cached in the local cache SR
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.
Default value:
{}
Published in:
XenServer 4.0 (rio)
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.
links each of the running tasks using this object (by reference) to a current_operation enum which describes the nature of the task.
Default value:
{}
Published in:
XenServer 4.0 (rio)
links each of the running tasks using this object (by reference) to a current_operation enum which describes the nature of the task.
boolis_a_snapshot[RO/runtime]
true if this is a snapshot.
Default value:
false
Published in:
XenServer 5.0 (orlando)
true if this is a snapshot.
boolis_tools_iso[RO/runtime]
Whether this VDI is a Tools ISO
Default value:
false
Published in:
XenServer 7.0 (dundee)
stringlocation[RO/runtime]
location information
Default value:
""
Published in:
XenServer 4.1 (miami)
location information
boolmanaged[RO/runtime]
Published in:
XenServer 4.0 (rio)
boolmetadata_latest[RO/runtime]
Whether this VDI contains the latest known accessible metadata for the pool
Default value:
false
Published in:
XenServer 6.0 (boston)
Whether this VDI contains the latest known accessible metadata for the pool
pool refmetadata_of_pool[RO/runtime]
The pool whose metadata is contained in this VDI
Default value:
OpaqueRef:NULL
Published in:
XenServer 6.0 (boston)
The pool whose metadata is contained in this VDI
boolmissing[RO/runtime]
true if SR scan operation reported this VDI as not present on disk
Published in:
XenServer 4.0 (rio)
true if SR scan operation reported this VDI as not present on disk
stringname_description[RO/constructor]
a notes field containing human-readable description
Default value:
""
Published in:
XenServer 4.0 (rio)
a notes field containing human-readable description
stringname_label[RO/constructor]
a human-readable name
Default value:
""
Published in:
XenServer 4.0 (rio)
a human-readable name
enum on_booton_boot[RO/runtime]
The behaviour of this VDI on a VM boot
Default value:
persist
Published in:
XenServer 5.6 FP1 (cowley)
The behaviour of this VDI on a VM boot
(string → string) mapother_config[RW]
additional configuration
Published in:
XenServer 4.0 (rio)
additional configuration
Deprecated
VDI refparent[RO/runtime]
This field is always null. Deprecated
Published in:
XenServer 4.0 (rio)
Deprecated in:
XenServer 7.1 (ely)
The field was never used.
intphysical_utilisation[RO/runtime]
amount of physical space that the disk image is currently taking up on the storage repository (in bytes)
Published in:
XenServer 4.0 (rio)
amount of physical space that the disk image is currently taking up on the storage repository (in bytes)
boolread_only[RO/constructor]
true if this disk may ONLY be mounted read-only
Published in:
XenServer 4.0 (rio)
true if this disk may ONLY be mounted read-only
boolsharable[RO/constructor]
true if this disk may be shared
Published in:
XenServer 4.0 (rio)
true if this disk may be shared
(string → string) mapsm_config[RW]
SM dependent data
Default value:
{}
Published in:
XenServer 4.1 (miami)
SM dependent data
VDI refsnapshot_of[RO/runtime]
Ref pointing to the VDI this snapshot is of.
Default value:
Null
Published in:
XenServer 5.0 (orlando)
Ref pointing to the VDI this snapshot is of.
datetimesnapshot_time[RO/runtime]
Date/time when this snapshot was created.
Default value:
19700101T00:00:00Z
Published in:
XenServer 5.0 (orlando)
Date/time when this snapshot was created.
VDI ref setsnapshots[RO/runtime]
List pointing to all the VDIs snapshots.
Published in:
XenServer 5.0 (orlando)
List pointing to all the VDIs snapshots.
SR refSR[RO/constructor]
storage repository in which the VDI resides
Published in:
XenServer 4.0 (rio)
storage repository in which the VDI resides
boolstorage_lock[RO/runtime]
true if this disk is locked at the storage level
Published in:
XenServer 4.0 (rio)
true if this disk is locked at the storage level
string settags[RW]
user-specified tags for categorization purposes
Default value:
{}
Published in:
XenServer 5.0 (orlando)
user-specified tags for categorization purposes
enum vdi_typetype[RO/constructor]
type of the VDI
Published in:
XenServer 4.0 (rio)
type of the VDI
stringuuid[RO/runtime]
Unique identifier/object reference
Published in:
XenServer 4.0 (rio)
Unique identifier/object reference
VBD ref setVBDs[RO/runtime]
list of vbds that refer to this disk
Published in:
XenServer 4.0 (rio)
list of vbds that refer to this disk
intvirtual_size[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
Published in:
XenServer 4.0 (rio)
size of disk as presented to the guest (in bytes). Note that, depending on storage backend type, requested size may not be respected exactly
(string → string) mapxenstore_data[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.
Default value:
{}
Published in:
XenServer 4.1 (miami)
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.
Messages
voidadd_tags(session ref, VDI ref, string)
Add the given value to the tags field of the given VDI. If the value is already in that Set, then do nothing.
Add the given key-value pair to the xenstore_data field of the given VDI.
Parameters:
session ref session_id
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
Published in:
XenServer 4.1 (miami)
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.
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.
Parameters:
session ref session_id
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
Result:
The ID of the newly created VDI.
Published in:
XenServer 4.0 (rio)
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.
Copy either a full VDI or the block differences between two VDIs into either a fresh VDI or an existing VDI.
Parameters:
session ref session_id
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
Result:
The reference of the VDI where the blocks were written.
Errors:
VDI_READONLY
The operation required write access but this VDI is read-only
VDI_TOO_SMALL
The VDI is too small. Please resize it to at least the minimum size.
VDI_NOT_SPARSE
The VDI is not stored using a sparse format. It is not possible to query and manipulate only the changed blocks (or 'block differences' or 'disk deltas') between two VDIs. Please select a VDI which uses a sparse-aware technology such as VHD.
Published in:
XenServer 4.0 (rio)
Copies a VDI to an SR. There must be a host that can see both the source and destination SRs simultaneously
Extended in:
XenServer 5.6 FP1 (cowley)
The copy can now be performed between any two SRs.
Extended in:
XenServer 6.2 SP1 Hotfix 4 (clearwater-felton)
The copy can now be performed into a pre-created VDI. It is now possible to request copying only changed blocks from a base VDI
VDI refcreate(session ref, VDI record)
Create a new VDI instance, and return its handle.
The constructor args are: name_label, name_description, SR*, virtual_size*, type*, sharable*, read_only*, other_config*, xenstore_data, sm_config, tags (* = non-optional).
Parameters:
session ref session_id
Reference to a valid session
VDI record args
All constructor arguments
Minimum role:
vm-admin
Result:
reference to the newly created object
Published in:
XenServer 4.0 (rio)
A virtual disk image
voiddata_destroy(session ref, VDI ref)
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.
Parameters:
session ref session_id
Reference to a valid session
VDI ref self
The VDI whose data should be deleted.
Minimum role:
vm-admin
Errors:
SR_OPERATION_NOT_SUPPORTED
The SR backend does not support the operation (check the SR's allowed operations)
VDI_MISSING
This operation cannot be performed because the specified VDI could not be found on the storage substrate
SR_NOT_ATTACHED
The SR is not attached.
SR_HAS_NO_PBDS
The SR has no attached PBDs
OPERATION_NOT_ALLOWED
You attempted an operation that was not allowed.
VDI_INCOMPATIBLE_TYPE
This operation cannot be performed because the specified VDI is of an incompatible type (eg: an HA statefile cannot be attached to a guest)
VDI_NO_CBT_METADATA
The requested operation is not allowed because the specified VDI does not have changed block tracking metadata.
VDI_IN_USE
This operation cannot be performed because this VDI is in use by some other operation
VDI_IS_A_PHYSICAL_DEVICE
The operation cannot be performed on physical device
Published in:
XenServer 7.3 (inverness)
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.
voiddestroy(session ref, VDI ref)
Destroy the specified VDI instance.
Parameters:
session ref session_id
Reference to a valid session
VDI ref self
reference to the object
Minimum role:
vm-admin
Published in:
XenServer 4.0 (rio)
A virtual disk image
voiddisable_cbt(session ref, VDI ref)
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.
Parameters:
session ref session_id
Reference to a valid session
VDI ref self
The VDI for which CBT should be disabled
Minimum role:
vm-admin
Errors:
SR_OPERATION_NOT_SUPPORTED
The SR backend does not support the operation (check the SR's allowed operations)
VDI_MISSING
This operation cannot be performed because the specified VDI could not be found on the storage substrate
SR_NOT_ATTACHED
The SR is not attached.
SR_HAS_NO_PBDS
The SR has no attached PBDs
OPERATION_NOT_ALLOWED
You attempted an operation that was not allowed.
VDI_INCOMPATIBLE_TYPE
This operation cannot be performed because the specified VDI is of an incompatible type (eg: an HA statefile cannot be attached to a guest)
VDI_ON_BOOT_MODE_INCOMPATIBLE_WITH_OPERATION
This operation is not permitted on VDIs in the 'on-boot=reset' mode, or on VMs having such VDIs.
Published in:
XenServer 7.3 (inverness)
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.
voidenable_cbt(session ref, VDI ref)
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.
Parameters:
session ref session_id
Reference to a valid session
VDI ref self
The VDI for which CBT should be enabled
Minimum role:
vm-admin
Errors:
SR_OPERATION_NOT_SUPPORTED
The SR backend does not support the operation (check the SR's allowed operations)
VDI_MISSING
This operation cannot be performed because the specified VDI could not be found on the storage substrate
SR_NOT_ATTACHED
The SR is not attached.
SR_HAS_NO_PBDS
The SR has no attached PBDs
OPERATION_NOT_ALLOWED
You attempted an operation that was not allowed.
VDI_INCOMPATIBLE_TYPE
This operation cannot be performed because the specified VDI is of an incompatible type (eg: an HA statefile cannot be attached to a guest)
VDI_ON_BOOT_MODE_INCOMPATIBLE_WITH_OPERATION
This operation is not permitted on VDIs in the 'on-boot=reset' mode, or on VMs having such VDIs.
Published in:
XenServer 7.3 (inverness)
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.
voidforget(session ref, VDI ref)
Removes a VDI record from the database
Parameters:
session ref session_id
Reference to a valid session
VDI ref vdi
The VDI to forget about
Minimum role:
vm-admin
Published in:
XenServer 4.0 (rio)
Removes a VDI record from the database
VDI ref setget_all(session ref)
Return a list of all the VDIs known to the system.
Get the allowed_operations field of the given VDI.
Parameters:
session ref session_id
Reference to a valid session
VDI ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
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.
VDI ref setget_by_name_label(session ref, string)
Get all the VDI instances with the given label.
Parameters:
session ref session_id
Reference to a valid session
string label
label of object to return
Minimum role:
read-only
Result:
references to objects with matching names
Published in:
XenServer 4.0 (rio)
A virtual disk image
VDI refget_by_uuid(session ref, string)
Get a reference to the VDI instance with the specified UUID.
Get the current_operations field of the given VDI.
Parameters:
session ref session_id
Reference to a valid session
VDI ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
links each of the running tasks using this object (by reference) to a current_operation enum which describes the nature of the task.
boolget_is_a_snapshot(session ref, VDI ref)
Get the is_a_snapshot field of the given VDI.
Parameters:
session ref session_id
Reference to a valid session
VDI ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 5.0 (orlando)
true if this is a snapshot.
boolget_is_tools_iso(session ref, VDI ref)
Get the is_tools_iso field of the given VDI.
Parameters:
session ref session_id
Reference to a valid session
VDI ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 7.0 (dundee)
stringget_location(session ref, VDI ref)
Get the location field of the given VDI.
Parameters:
session ref session_id
Reference to a valid session
VDI ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.1 (miami)
location information
boolget_managed(session ref, VDI ref)
Get the managed field of the given VDI.
Parameters:
session ref session_id
Reference to a valid session
VDI ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
boolget_metadata_latest(session ref, VDI ref)
Get the metadata_latest field of the given VDI.
Parameters:
session ref session_id
Reference to a valid session
VDI ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 6.0 (boston)
Whether this VDI contains the latest known accessible metadata for the pool
pool refget_metadata_of_pool(session ref, VDI ref)
Get the metadata_of_pool field of the given VDI.
Parameters:
session ref session_id
Reference to a valid session
VDI ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 6.0 (boston)
The pool whose metadata is contained in this VDI
boolget_missing(session ref, VDI ref)
Get the missing field of the given VDI.
Parameters:
session ref session_id
Reference to a valid session
VDI ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
true if SR scan operation reported this VDI as not present on disk
stringget_name_description(session ref, VDI ref)
Get the name/description field of the given VDI.
Parameters:
session ref session_id
Reference to a valid session
VDI ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
a notes field containing human-readable description
stringget_name_label(session ref, VDI ref)
Get the name/label field of the given VDI.
Parameters:
session ref session_id
Reference to a valid session
VDI ref self
reference to the object
Minimum role:
read-only
Result:
value of the field
Published in:
XenServer 4.0 (rio)
a human-readable name
vdi_nbd_server_info record setget_nbd_info(session ref, VDI ref)
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.
Parameters:
session ref session_id
Reference to a valid session
VDI ref self
The VDI to access via Network Block Device protocol
Minimum role:
vm-admin
Result:
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.
Errors:
VDI_INCOMPATIBLE_TYPE
This operation cannot be performed because the specified VDI is of an incompatible type (eg: an HA statefile cannot be attached to a guest)
Published in:
XenServer 7.3 (inverness)
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.
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.
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.
Parameters:
session ref session_id
Reference to a valid session
VDI ref self
reference to the object
string key
Key to remove
Minimum role:
vm-admin
Published in:
XenServer 4.1 (miami)
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.
voidremove_tags(session ref, VDI ref, string)
Remove the given value from the tags field of the given VDI. If the value is not in that Set, then do nothing.
Parameters:
session ref session_id
Reference to a valid session
VDI ref self
reference to the object
string value
Value to remove
Minimum role:
vm-operator
Published in:
XenServer 5.0 (orlando)
user-specified tags for categorization purposes
voidresize(session ref, VDI ref, int)
Resize the VDI.
Parameters:
session ref session_id
Reference to a valid session
VDI ref vdi
The VDI to resize
int size
The new size of the VDI
Minimum role:
vm-admin
Published in:
XenServer 4.0 (rio)
Resize the VDI.
Removed
voidresize_online(session ref, VDI ref, int)
Resize the VDI which may or may not be attached to running guests.
Parameters:
session ref session_id
Reference to a valid session
VDI ref vdi
The VDI to resize
int size
The new size of the VDI
Minimum role:
vm-admin
Published in:
XenServer 4.0 (rio)
Deprecated in:
XenServer 7.3 (inverness)
Dummy transition
Removed in:
XenServer 7.3 (inverness)
Online VDI resize is not supported by any of the storage backends.
voidset_allow_caching(session ref, VDI ref, bool)
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.
Parameters:
session ref session_id
Reference to a valid session
VDI ref self
The VDI to modify
bool value
The value to set
Minimum role:
vm-admin
Published in:
XenServer 5.6 FP1 (cowley)
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.
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.
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.
Parameters:
session ref session_id
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
Result:
The ID of the newly created VDI.
Published in:
XenServer 4.0 (rio)
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.
voidupdate(session ref, VDI ref)
Ask the storage backend to refresh the fields in the VDI object
Parameters:
session ref session_id
Reference to a valid session
VDI ref vdi
The VDI whose stats (eg size) should be updated
Minimum role:
vm-admin
Errors:
SR_OPERATION_NOT_SUPPORTED
The SR backend does not support the operation (check the SR's allowed operations)
Published in:
XenServer 4.1.1 (symc)
Ask the storage backend to refresh the fields in the VDI object