Class: VDI
A virtual disk image
| Published in: | XenServer 4.0 (rio) | A virtual disk image |
Enums
vdi_operations
| Values: | clone | Cloning the VDI |
| copy | Copying the VDI | |
| resize | Resizing the VDI | |
| resize_online | Resizing the VDI which may or may not be online | |
| snapshot | Snapshotting the VDI | |
| mirror | Mirroring the VDI | |
| destroy | Destroying the VDI | |
| forget | Forget about the VDI | |
| update | Refreshing the fields of the VDI | |
| force_unlock | Forcibly unlocking the VDI | |
| generate_config | Generating static configuration | |
| enable_cbt | Enabling changed block tracking for a VDI | |
| disable_cbt | Disabling changed block tracking for a VDI | |
| data_destroy | Deleting the data of the VDI | |
| list_changed_blocks | 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
SR ref
SR
[RO/constructor]
storage repository in which the VDI resides
| Published in: | XenServer 4.0 (rio) | storage repository in which the VDI resides |
VBD ref set
VBDs
[RO/runtime]
list of vbds that refer to this disk
| Published in: | XenServer 4.0 (rio) | list of vbds that refer to this disk |
bool
allow_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 |
enum vdi_operations set
allowed_operations
[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.
| 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. |
bool
cbt_enabled
[RO/runtime]
True if changed blocks are tracked for this VDI
| Default value: | false | |
| Published in: | XenServer 7.3 (inverness) | |
crashdump ref set
crash_dumps
[RO/runtime]
list of crash dumps that refer to this disk
| Published in: | XenServer 4.0 (rio) | list of crash dumps that refer to this disk |
(string → enum vdi_operations) map
current_operations
[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.
| 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. |
bool
is_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. |
bool
is_tools_iso
[RO/runtime]
Whether this VDI is a Tools ISO
| Default value: | false | |
| Published in: | XenServer 7.0 (dundee) | |
string
location
[RO/runtime]
location information
| Default value: | "" | |
| Published in: | XenServer 4.1 (miami) | location information |
bool
managed
[RO/runtime]
| Published in: | XenServer 4.0 (rio) |
bool
metadata_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 ref
metadata_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 |
bool
missing
[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 |
string
name_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 |
string
name_label
[RO/constructor]
a human-readable name
| Default value: | "" | |
| Published in: | XenServer 4.0 (rio) | a human-readable name |
enum on_boot
on_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) map
other_config
[RW]
additional configuration
| Published in: | XenServer 4.0 (rio) | additional configuration |
Deprecated
VDI ref
parent
[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. |
int
physical_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) |
bool
read_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 |
bool
sharable
[RO/constructor]
true if this disk may be shared
| Published in: | XenServer 4.0 (rio) | true if this disk may be shared |
(string → string) map
sm_config
[RW]
SM dependent data
| Default value: | {} | |
| Published in: | XenServer 4.1 (miami) | SM dependent data |
VDI ref
snapshot_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. |
datetime
snapshot_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 set
snapshots
[RO/runtime]
List pointing to all the VDIs snapshots.
| Published in: | XenServer 5.0 (orlando) | List pointing to all the VDIs snapshots. |
bool
storage_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 set
tags
[RW]
user-specified tags for categorization purposes
| Default value: | {} | |
| Published in: | XenServer 5.0 (orlando) | user-specified tags for categorization purposes |
enum vdi_type
type
[RO/constructor]
type of the VDI
| Published in: | XenServer 4.0 (rio) | type of the VDI |
string
uuid
[RO/runtime]
Unique identifier/object reference
| Published in: | XenServer 4.0 (rio) | Unique identifier/object reference |
int
virtual_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) map
xenstore_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
void
add_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.
| Parameters: | session ref session_id | Reference to a valid session |
| VDI ref self | reference to the object | |
| string value | New value to add | |
| Minimum role: | vm-operator | |
| Published in: | XenServer 5.0 (orlando) | user-specified tags for categorization purposes |
void
add_to_other_config
(session ref, VDI ref, string, string)
Add the given key-value pair to the other_config 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.0 (rio) | additional configuration |
void
add_to_sm_config
(session ref, VDI ref, string, string)
Add the given key-value pair to the sm_config 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) | SM dependent data |
void
add_to_xenstore_data
(session ref, VDI ref, string, string)
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. |
VDI ref
clone
(session ref, VDI ref, (string → string) map)
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. |
VDI ref
copy
(session ref, VDI ref, SR ref, VDI ref, VDI ref)
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 ref
create
(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 |
void
data_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. |
void
destroy
(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 |
void
disable_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. |
void
enable_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. |
void
forget
(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 |
SR ref
get_SR
(session ref, VDI ref)
Get the SR 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) | storage repository in which the VDI resides |
VBD ref set
get_VBDs
(session ref, VDI ref)
Get the VBDs 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 vbds that refer to this disk |
VDI ref set
get_all
(session ref)
Return a list of all the VDIs known to the system.
| Parameters: | session ref session_id | Reference to a valid session |
| Minimum role: | read-only | |
| Result: | references to all objects | |
| Published in: | XenServer 4.0 (rio) | A virtual disk image |
(VDI ref → VDI record) map
get_all_records
(session ref)
Return a map of VDI references to VDI records for all VDIs known to the system.
| Parameters: | session ref session_id | Reference to a valid session |
| Minimum role: | read-only | |
| Result: | records of all objects | |
| Published in: | XenServer 4.0 (rio) | A virtual disk image |
bool
get_allow_caching
(session ref, VDI ref)
Get the allow_caching 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.6 FP1 (cowley) | true if this VDI is to be cached in the local cache SR |
enum vdi_operations set
get_allowed_operations
(session ref, VDI ref)
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 set
get_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 ref
get_by_uuid
(session ref, string)
Get a reference to the VDI instance with the specified UUID.
| Parameters: | session ref session_id | Reference to a valid session |
| string uuid | UUID of object to return | |
| Minimum role: | read-only | |
| Result: | reference to the object | |
| Published in: | XenServer 4.0 (rio) | A virtual disk image |
bool
get_cbt_enabled
(session ref, VDI ref)
Get the cbt_enabled 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.3 (inverness) | |
crashdump ref set
get_crash_dumps
(session ref, VDI ref)
Get the crash_dumps 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 crash dumps that refer to this disk |
(string → enum vdi_operations) map
get_current_operations
(session ref, VDI ref)
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. |
bool
get_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. |
bool
get_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) | |
string
get_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 |
bool
get_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) | |
bool
get_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 ref
get_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 |
bool
get_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 |
string
get_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 |
string
get_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 set
get_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. |
enum on_boot
get_on_boot
(session ref, VDI ref)
Get the on_boot 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.6 FP1 (cowley) | The behaviour of this VDI on a VM boot |
(string → string) map
get_other_config
(session ref, VDI ref)
Get the other_config 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) | additional configuration |
Deprecated
VDI ref
get_parent
(session ref, VDI ref)
Get the parent 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) | |
| Deprecated in: | XenServer 7.1 (ely) | The field was never used. |
int
get_physical_utilisation
(session ref, VDI ref)
Get the physical_utilisation 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) | amount of physical space that the disk image is currently taking up on the storage repository (in bytes) |
bool
get_read_only
(session ref, VDI ref)
Get the read_only 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 this disk may ONLY be mounted read-only |
VDI record
get_record
(session ref, VDI ref)
Get a record containing the current state 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: | all fields from the object | |
| Published in: | XenServer 4.0 (rio) | A virtual disk image |
bool
get_sharable
(session ref, VDI ref)
Get the sharable 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 this disk may be shared |
(string → string) map
get_sm_config
(session ref, VDI ref)
Get the sm_config 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) | SM dependent data |
VDI ref
get_snapshot_of
(session ref, VDI ref)
Get the snapshot_of 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) | Ref pointing to the VDI this snapshot is of. |
datetime
get_snapshot_time
(session ref, VDI ref)
Get the snapshot_time 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) | Date/time when this snapshot was created. |
VDI ref set
get_snapshots
(session ref, VDI ref)
Get the snapshots 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) | List pointing to all the VDIs snapshots. |
bool
get_storage_lock
(session ref, VDI ref)
Get the storage_lock 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 this disk is locked at the storage level |
string set
get_tags
(session ref, VDI ref)
Get the tags 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) | user-specified tags for categorization purposes |
enum vdi_type
get_type
(session ref, VDI ref)
Get the type 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) | type of the VDI |
string
get_uuid
(session ref, VDI ref)
Get the uuid 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) | Unique identifier/object reference |
int
get_virtual_size
(session ref, VDI ref)
Get the virtual_size 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) | 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) map
get_xenstore_data
(session ref, VDI ref)
Get 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 | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| 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. |
VDI ref
introduce
(session ref, string, string, string, SR ref, enum vdi_type, bool, bool, (string → string) map, string, (string → string) map, (string → string) map, bool, int, int, pool ref, bool, datetime, VDI ref)
Create a new VDI record in the database only
| Parameters: | session ref session_id | 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 | |
| enum 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 | |
| VDI ref snapshot_of | Storage-specific config | |
| Minimum role: | vm-admin | |
| Result: | The ref of the newly created VDI record. | |
| Errors: | SR_OPERATION_NOT_SUPPORTED | The SR backend does not support the operation (check the SR's allowed operations) |
| Published in: | XenServer 4.1 (miami) | Create a new VDI record in the database only |
string
list_changed_blocks
(session ref, VDI ref, VDI ref)
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.
| Parameters: | session ref session_id | Reference to a valid session |
| VDI ref vdi_from | The first VDI. | |
| VDI ref vdi_to | The second VDI. | |
| Minimum role: | vm-operator | |
| Result: | A base64 string-encoding of the bitmap showing which blocks differ in the two VDIs. | |
| 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 | |
| VDI_IN_USE | This operation cannot be performed because this VDI is in use by some other operation | |
| Published in: | XenServer 7.3 (inverness) | 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. |
session ref
open_database
(session ref, VDI ref)
Load the metadata found on the supplied VDI and return a session reference which can be used in API calls to query its contents.
| Parameters: | session ref session_id | Reference to a valid session |
| VDI ref self | The VDI which contains the database to open | |
| Minimum role: | pool-operator | |
| Result: | A session which can be used to query the database | |
| Published in: | XenServer 6.0 (boston) | Load the metadata found on the supplied VDI and return a session reference which can be used in API calls to query its contents. |
VDI ref
pool_migrate
(session ref, VDI ref, SR ref, (string → string) map)
Migrate a VDI, which may be attached to a running guest, to a different SR. The destination SR must be visible to the guest.
| Parameters: | session ref session_id | 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 | |
| Result: | The new reference of the migrated VDI. | |
| Published in: | XenServer 6.1 (tampa) | Migrate a VDI, which may be attached to a running guest, to a different SR. The destination SR must be visible to the guest. |
string
read_database_pool_uuid
(session ref, VDI ref)
Check the VDI cache for the pool UUID of the database on this VDI.
| Parameters: | session ref session_id | Reference to a valid session |
| VDI ref self | The metadata VDI to look up in the cache. | |
| Minimum role: | read-only | |
| Result: | The cached pool UUID of the database on the VDI. | |
| Published in: | XenServer 6.0 (boston) | Check the VDI cache for the pool UUID of the database on this VDI. |
void
remove_from_other_config
(session ref, VDI ref, string)
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.
| 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.0 (rio) | additional configuration |
void
remove_from_sm_config
(session ref, VDI ref, string)
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.
| 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) | SM dependent data |
void
remove_from_xenstore_data
(session ref, VDI ref, string)
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. |
void
remove_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 |
void
resize
(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
void
resize_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. |
void
set_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. |
void
set_name_description
(session ref, VDI ref, string)
Set the name description of the VDI. This can only happen when its SR is currently attached.
| Parameters: | session ref session_id | Reference to a valid session |
| VDI ref self | The VDI to modify | |
| string value | The name description for the VDI | |
| Minimum role: | vm-admin | |
| Published in: | XenServer 4.0 (rio) | Set the name description of the VDI. This can only happen when its SR is currently attached. |
void
set_name_label
(session ref, VDI ref, string)
Set the name label of the VDI. This can only happen when then its SR is currently attached.
| Parameters: | session ref session_id | Reference to a valid session |
| VDI ref self | The VDI to modify | |
| string value | The name lable for the VDI | |
| Minimum role: | vm-admin | |
| Published in: | XenServer 4.0 (rio) | Set the name label of the VDI. This can only happen when then its SR is currently attached. |
void
set_on_boot
(session ref, VDI ref, enum on_boot)
Set the value of the on_boot parameter. This value can only be changed when the VDI is not attached to a running VM.
| Parameters: | session ref session_id | Reference to a valid session |
| VDI ref self | The VDI to modify | |
| enum on_boot value | The value to set | |
| Minimum role: | vm-admin | |
| Published in: | XenServer 5.6 FP1 (cowley) | Set the value of the on_boot parameter. This value can only be changed when the VDI is not attached to a running VM. |
void
set_other_config
(session ref, VDI ref, (string → string) map)
Set the other_config field of the given VDI.
| Parameters: | session ref session_id | Reference to a valid session |
| VDI ref self | reference to the object | |
| (string → string) map value | New value to set | |
| Minimum role: | vm-admin | |
| Published in: | XenServer 4.0 (rio) | additional configuration |
void
set_read_only
(session ref, VDI ref, bool)
Sets the VDI's read_only field
| Parameters: | session ref session_id | 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 | |
| Published in: | XenServer 4.0 (rio) | Sets the VDI's read_only field |
void
set_sharable
(session ref, VDI ref, bool)
Sets the VDI's sharable field
| Parameters: | session ref session_id | 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 | |
| Published in: | XenServer 5.5 (george) | Sets the VDI's sharable field |
void
set_sm_config
(session ref, VDI ref, (string → string) map)
Set the sm_config field of the given VDI.
| Parameters: | session ref session_id | Reference to a valid session |
| VDI ref self | reference to the object | |
| (string → string) map value | New value to set | |
| Minimum role: | vm-admin | |
| Published in: | XenServer 4.1 (miami) | SM dependent data |
void
set_tags
(session ref, VDI ref, string set)
Set the tags field of the given VDI.
| Parameters: | session ref session_id | Reference to a valid session |
| VDI ref self | reference to the object | |
| string set value | New value to set | |
| Minimum role: | vm-operator | |
| Published in: | XenServer 5.0 (orlando) | user-specified tags for categorization purposes |
void
set_xenstore_data
(session ref, VDI ref, (string → string) map)
Set 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 → string) map value | New value to set | |
| 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. |
VDI ref
snapshot
(session ref, VDI ref, (string → string) map)
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. |
void
update
(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 |