Vdsm datatypes

VDSM uses various complex types throughout its API. Currently these are expressed as free-form dictionaries and/or strings with magic values. This wiki page attempts to capture a comprehensive list of these types for reference and to serve as a base for discussion on creating a more formalized specification of the types for the next generation API.


Type Specification
DriveSpec_t Uniquely identifies a storage volume for use as a drive for a virtual machine
{ spUUID, sdUUID, imgUUID, volUUID }  # Standard UUID quartet
{ GUID }  # Device mapper GUID
{ UUID }  # blkid-based UUID
HibernationVolumeHandle_t Bundles together the storage resources that are needed for hibernation operations
  sdUUID         # Storage domain that contains the state and param volumes
  spUUID         # Storage pool
  stateImageID   # Image UUID for VM state
  stateVolumeID  # Volume UUID for VM state
  paramImageID   # Image UUID for hibernation parameters
  paramVolumeID  # Volume UUID for hibernation parameters
VM_Create_t Contains all parameters needed to create a new virtual machine
  'vmName'         # Set the name of the virtual machine. String.
  'vmId'           # The virtual machine UUID.
  'hiberVolHandle' # An optional HibernationVolumeHandle_t for resuming a hibernated VM
                   # A comma-separated list: sdUUID,spUUID,stateImageID,stateVolumeID,paramImageID,paramVolumeID
  'restoreState'   # A volume containing migration restore data. DriveSpec_t
  'memSize'        # The desired amount of memory (in megabytes)
  'display'        # The type of display.  String: 'qxl', 'vnc', 'qxlnc', 'local'
  'displayNetwork' # Limit display to specific host network.  Bridge name. Default: 0 (listen on all interfaces)
  'spiceMonitors'  # The number of monitors to add to a VM (spice only).  Default: 1
  'keyboardLayout' # Specify the keymap to use.
  'boot'           # The desired boot device. String: 'a', 'c', 'd', 'n'
  'vmType'         # The type of VM to create.  String: 'kvm'
  'floppy'         # Set the floppy disk volume. DriveSpec_t
  'volatileFloppy' # The floppy is temporary and should be ejected and deleted on shutdown or reboot.
  'cdrom'          # Set the cdrom volume. DriveSpec_t
  'sysprepInf'     # Create a sysprep floppy from an inf file for automatic Windows installation. Binary data.
  'nicModel'       # A comma-separated list of nic models to use, one per desired network device.
                   # String: 'ne2k_pci', 'i82551', 'i82557b', 'i82559er', 'rtl8139', 'e1000', 'pcnet', 'virtio'
  'macAddr'        # A comma-separated list of mac addresses to use, one per desired network device.
  'bridge'         # A comma-separated list of host bridge names, one per desired network device.
                   # Each device will be connected to the corresponding host network.
  'smp'            # The number of desired vcpus.
  'cpuType'        # Set cpu type and features.  Comma-separated list with the following specification:
                   # <cpuType>,<feature-1>,<feature-2>,...<feature-N>
                   # Default cpuType: 'qemu64'.  See libvirt documentation for full details on cpu types and features.
  'smpCoresPerSocket' # CPU topology.  The number of cores on each vcpu
  'smpThreadsPerCore' # CPU topology.  The number of threads on each vcpu core
  'drives'         # An array of dicts with the following specification:
                   # {
                   #   'if'       - Drive interface type. String: 'ide', 'virtio'
                   #   'serial'   - Optional drive serial number. String.
                   #   'poolID'   - Storage pool UUID
                   #   'domainID' - Storage domain UUID
                   #   'imageID'  - Image UUID
                   #   'volumeID' - Volume UUID
                   # }
  'tabletEnable'   # Should the USB tablet be used for input? Boolean.
  'soundDevice'    # Add a sound card with the given model.  String: 'pcspk', 'sb16', 'ac97', 'es1370', 'hda'
  'vmchannel'      # Create a channel device for guest agent communication? Boolean.
  'nice'           # Set nice value of the qemu process. Integer: -20..19
  'timeOffset'     # Clock offset from UTC (in seconds)
  'tdf'            # Use an RTC timer with a 'catchup' tick policy? Boolean.
  'emulatedMachine'# The machine type to emulate.  String.  Default: 'pc'.
  'initrd'         # Enable direct-boot from host using this file for the initrd.  Local path.
  'kernel'         # Enable direct-boot from host using this file for the kernel.  Local path.
  'kernelArgs'     # When direct-boot is enabled, pass these arguments to the kernel. String.
  'acpiEnable'     # Enable ACPI in the guest? Boolean.
  # The following 'custom' fields are also recognized: vhost, sndbuf, viodiskcache
This list does not include internal state variables or fields that may be inserted to activate special modes such as restore, migration or hibernation. ''These should be added later in a special section.''
VM_Migrate_t Contains the parameters needed to migrate an existing domain to another host
  'vmId'           # The UUID of the VM to migrate
  'mode'           # String: 'remote' or 'file'
  'method'         # String: 'online'
  'dst'            # String: <host>:<port>
  'hiberVolHandle' # (Only for hibernate) HibernationVolumeHandle_t for saving state to file 
  'downtime'       # The maximum amount of allowed downtime during migration
VM_SetTicket_ExistingConnAction_t Describes how to handle an existing vm display connection when establishing a new connection. String:
'keep'        # Allow the current user to remain connected
'disconnect'  # Disconnect the current user
'fail'        # Abort the operation
Volume_Type_t Specifies whether a volume is preallocated or sparse
  PREALLOCATED  # All needed storage for the volume is allocated at volume creation time
  SPARSE        # Storage is allocated dynamically as more space is required
Volume_Format_t The file data format
  COW_FORMAT  # The qemu COW format is specified
  RAW_FORMAT  # The raw format is specified
Volume_Legality_t Indicates the legality of the volume
Image_MoveOperation_t Specify the type of image move operation that is desired
LVM_Create_DeviceList_t A list of device names to include when creating a new LVM volume group
[ "sda1", "sdb3" ... ]
ISCSI_ConnectParams_t A dictionary of iSCSI connection information
  'connection' # iSCSI host IP address
  'port'       # iSCSI host port
  'user'       # Login user
  'password'   # Login password
StorageDomain_Type_t Identifies the type of backing storage that is used by the domain
StorageDomain_Create_TypeParameters_t Storage Domain type-specific creation parameters ''For FCP and iSCSI domains:''
  vgUUID      # The UUID of the volume group to be used
''For NFS domains:''
  remotePath  # The path to the remote NFS exported filesystem (<host>:/<path>)
''For LOCALFS domains:''
  localPath  # The local path to use (eg. /var/localstorage)
StorageDomain_Class_t Identifies the nature/class of data that will be stored in the domain
StorageDomain_UploadVolume_Method_t Designates the upload method to be used for StorageDomain.UploadVolume
  'rsync'  # Use the rsync program
  'wget'   # Use the wget program
StorageConnectionParameters_t Parameters needed for connecting to different kinds of storage ''For NFS, LocalFS, and CIFS storage:''
  'id'          # Used to identify this connection in the return value
  'connection'  # For NFS:     <host>:/<path>
                # For LocalFS: <local path>
                # For CIFS:    Not supported
''For FCP and iSCSI storage:''
  'id'             # Used to identify this connection in the return value
  'connection'     # The IP address of the iSCSI server
  'iqn'            # The iSCSI target
  'portal'         # Unused
  'user'           # iSCSI server username
  'password'       # iSCSI server password
  'port'           # iSCSI server host port
  'initiatorName'  # iSCSI initiator
StoragePool_ImageMoveList_t Defines a list of images to move along with per-image parameters
  { imgUUID: <postZero> } # postZero is a boolean to set whether source
                          # images should be zeroed after data has been moved
StorageDomainStatus_t The current status of a StorageDomain
StoragePool_ReconstructDomainDict_t A dictionary of sdUUIDs and status used to reconstruct the master StorageDomain
{ <sdUUID>: <status> } # Where status is a StorageDomainStatus_t
StoragePool_UpdateVMsList_t A list of VM metadata to store/update
    'vm'       # The VM UUID
    'ovf':     # The VM definition in OVF format
    'imglist'  # A comma-separated list of imgUUIDs
FenceNode_Agent_t Select the agent to use from the fence-agents project ''See the fence-agents documentation for details. Possible values are:''
ack_manual     alom           apc            apc_snmp       baytech        bladecenter
brocade        bullpap        cisco_mds      cisco_ucs      cpint          drac
drac5          eaton_snmp     egenera        eps            ibmblade       ifmib
ilo            ilo_mp         intelmodular   ipmilan        kdump          kdump_send
ldom           lpar           mcdata         na             nss_wrapper    rackswitch
rhevm          rsa            rsb            sanbox2        scsi           virsh
vixel          vmware         vmware_helper  vmware_soap    wti            xcat
xenapi         zvm
FenceNode_Action_t Selects the fencing action to perform
SetupNetworks_Params_t Structure to provide complete network setup information
networks - dict of key=network, value=attributes
           where 'attributes' is a dict with the following optional items:
                bonding="<name>" | nic="<name>"
                (bonding and nics are mutually exclusive)
                (other options will be passed to the config file AS-IS)
           -- OR --
                remove=True (other attributes can't be specified)

bondings - dict of key=bonding, value=attributes
           where 'attributes' is a dict with the following optional items:
                nics=["<nic1>" , "<nic2>", ...]
            -- OR --
                remove=True (other attributes can't be specified)

options - dict of options, such as:

    Bondings are removed when they change state from 'used' to 'unused'.

    By default, if you edit a network that is attached to a bonding, it's not
    necessary to re-specify the bonding (you need only to note the attachement
    in the network's attributes). Similarly, if you edit a bonding, it's not
    necessary to specify its networks.
    However, if you specify the 'explicitBonding' option as true, the function
    will expect you to specify all networks that are attached to a specified
    bonding, and vice-versa, the bonding attached to a specified network.

Return Data

All API calls return a dictionary with this basic format:

      'status': { 'code': <integer>, 'message': <string> },
      ... Function-specific fields ...

This table describes the function-specific fields that appear in certain API calls.

Type Specification