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
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:
# ,,,... # 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: : '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  
The file data format COW_FORMAT # The qemu COW format is specified
RAW_FORMAT # The raw format is specified  

Indicates the legality of the volume | ILLEGAL_VOL
FAKE_VOL | | Image_MoveOperation_t

Specify the type of image move operation that is desired COPY_OP
A list of device names to include when creating a new LVM volume group [ “sda1”, “sdb3” … ]

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 | UNKNOWN_DOMAIN = 0
CIFS_DOMAIN = 5 | | 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 | DATA_DOMAIN = 1
BACKUP_DOMAIN = 3 | | StorageDomain_UploadVolume_Method_t

Designates the upload method to be used for StorageDomain.UploadVolume ‘rsync’ # Use the rsync program
‘wget’ # Use the wget program  
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 is a boolean to set whether source # images should be zeroed after data has been moved ] | | **StorageDomainStatus_t**

The current status of a StorageDomain | DOM_UNKNOWN_STATUS = ‘Unknown’
DOM_ACTIVE_STATUS = ‘Active’ | | StoragePool_ReconstructDomainDict_t

A dictionary of sdUUIDs and status used to reconstruct the master StorageDomain { : } # Where status is a StorageDomainStatus_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 | ‘status’
‘reboot’ | | 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:
vlan= bonding="" | nic="" (bonding and nics are mutually exclusive) ipaddr="" netmask="" gateway="" bootproto="..." delay="..." onboot="yes"|"no" (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 | |——|—————|