Product SiteDocumentation Site

Chapter 4. Guest Domains

4.1. Domain Overview
4.2. Listing Domains
4.3. Obtaining State Information About a Domain
4.3.1. Fetching the ID of a domain
4.3.2. Fetching the UUID of a domain
4.3.3. Fetching the OS type of a domain
4.3.4. Determining if the domain has a current snapshot
4.3.5. Determining if the domain has managed save images
4.3.6. Fetch the hostname of the domain
4.3.7. Get the Domain hardware info
4.3.8. Determine if the Domain is running
4.3.9. Determine if the Domain is persistent
4.3.10. Determine if the Domain is updated
4.3.11. Determine the max memory of the Domain
4.3.12. Determine the max Vcpus of the Domain
4.3.13. Fetch the name of the Domain
4.3.14. Fetch the state of the Domain
4.3.15. Extract the time information from Domain
4.4. Lifecycle Control
4.4.1. Provisioning and Starting
4.4.2. Stopping
4.4.3. Suspend / Resume and Save / Restore
4.4.4. Migration
4.4.5. Autostart
4.5. Domain Configuration
4.5.1. Emulator
4.5.2. Boot Modes
4.5.3. Memory / CPU Resources
4.6. Monitoring Performance
4.6.1. Domain Block Device Performance
4.6.2. vCPU Performance
4.6.3. Memory Statistics
4.6.4. I/O Statistics
4.7. Device configuration
4.7.1. Disks
4.7.2. Networking
4.7.3. Mice, Keyboard & Tablets
4.7.4. USB Device Passthrough
4.7.5. PCI device passthrough
4.8. Live Configuration Change
4.8.1. Block Device Jobs

4.1. Domain Overview

A domain is an instance of an operating system running on a virtualized machine. A guest domain can refer to either a running virtual machine or a configuration which can be used to launch a virtual machine. The connection object provides methods to enumerate the guest domains, create new guest domains and manage existing domains. A guest domain is represented with the virDomainPtr object and has a number of unique identifiers:

Unique identifiers

  • ID: positive integer, unique amongst running guest domains on a single host. An inactive domain does not have an ID. If the host OS is a virtual domain, it is given an ID of zero by default. For example, with the Xen hypervisor, Dom0 indicates a guest domain. Other domain IDs will be allocated starting at 1, and incrementing each time a new domain starts. Typically domain IDs will not be re-used until the entire ID space wraps around. The domain ID space is at least 16 bits in size, but often extends to 32 bits.
  • name: short string, unique amongst all guest domains on a single host, both running and inactive. For maximum portability between hypervisors applications should only rely on being able to use the characters a-Z,0-9,-,_ in names. Many hypervisors will store inactive domain configurations as files on disk, based on the domain name.
  • UUID: 16 unsigned bytes, guaranteed to be unique amongst all guest domains on any host. RFC 4122 defines the format for UUIDs and provides a recommended algorithm for generating UUIDs with guaranteed uniqueness. If the host OS is itself a virtual domain, then by convention it will be given a UUID of all zeros. This is the case with the Xen hypervisor, where Dom0 is a guest domain itself.
A guest domain may be transient, or persistent. A transient guest domain can only be managed while it is running on the host and, when powered off, all traces of it will disappear. A persistent guest domain has its configuration maintained in a data store on the host by the hypervisor, in an implementation defined format. Thus when a persistent guest is powered off, it is still possible to manage its inactive config. A transient guest can be turned into a persistent guest on the fly by defining a configuration for it.
Once an application has a unique identifier for a domain, it will often want to obtain the corresponding virDomain object. There are three, imaginatively named, methods to do lookup existing domains, lookupByID, lookupByName and lookupByUUID. Each of these takes the domain identifier as a parameter. They will return None if no matching domain exists. The error object can be queried to find specific details of the error if required.

Example 4.1. Fetching a domain object from an ID

# Example-1.py
#!/usr/bin/env python3
import sys
import libvirt

conn = None
try:
    conn = libvirt.open("qemu:///system")
except libvirt.libvirtError as e:
    print(repr(e), file=sys.stderr)
    exit(1)

domainID = 6
dom = conn.lookupByID(domainID)
if dom == None:
    print('Failed to get the domain object', file=sys.stderr)

conn.close()
exit(0)
It should be noted that the lookupByID method will not work if the domain is not active. Inactive domains all have an ID of -1.

Example 4.2. Fetching a domain object from a name

# Example-2.py
#!/usr/bin/env python3
import sys
import libvirt

conn = None
try:
    conn = libvirt.open("qemu:///system")
except libvirt.libvirtError as e:
    print(repr(e), file=sys.stderr)
    exit(1)

domainName = 'someguest'
dom = conn.lookupByName(domainName)
if dom == None:
    print('Failed to get the domain object', file=sys.stderr)

conn.close()

Example 4.3. Fetching a domain object from a UUID

# Example-3.py
#!/usr/bin/env python3
import sys
import libvirt

conn = None
try:
    conn = libvirt.open("qemu:///system")
except libvirt.libvirtError as e:
    print(repr(e), file=sys.stderr)
    exit(1)

domainUUID = '00311636-7767-71d2-e94a-26e7b8bad250'
dom = conn.lookupByUUID(domainUUID)
if dom == None:
    print('Failed to get the domain object', file=sys.stderr)

conn.close()
exit(0)
The UUID example used the example above uses the printable format of UUID. Using the equivalent raw bytes is not supported by Python.