The nova.virt.libvirt.guest Module

Manages information about the guest.

This class encapsulates libvirt domain provides certain higher level APIs around the raw libvirt API. These APIs are then used by all the other libvirt related classes

class BlockDevice(guest, disk)

Bases: object

Wrapper around block device API

abort_job(async=False, pivot=False)

Request to cancel any job currently running on the block.

  • async – Request only, do not wait for completion
  • pivot – Pivot to new file when ending a copy or active commit job
commit(base, top, relative=False)

Commit on block device

For performance during live snapshot it will reduces the disk chain to a single disk.

Parameters:relative – Keep backing chain referenced using relative names

Returns information about job currently running

Returns:BlockDeviceJobInfo or None
rebase(base, shallow=False, reuse_ext=False, copy=False, relative=False)

Rebases block to new base

  • shallow – Limit copy to top of source backing chain
  • reuse_ext – Reuse existing external file of a copy
  • copy – Start a copy job
  • relative – Keep backing chain referenced using relative names

Resizes block device to Kib size.

wait_for_job(abort_on_error=False, wait_for_job_clean=False)

Wait for libvirt block job to complete.

Libvirt may return either cur==end or an empty dict when the job is complete, depending on whether the job has been cleaned up by libvirt yet, or not.

  • abort_on_error – Whether to stop process and raise NovaException on error (default: False)
  • wait_for_job_clean – Whether to force wait to ensure job is finished (see bug: LP#1119173)

True if still in progress False if completed

class BlockDeviceJobInfo(job, bandwidth, cur, end)

Bases: object

class Guest(domain)

Bases: object

attach_device(conf, persistent=False, live=False)

Attaches device to the guest.

  • conf – A LibvirtConfigObject of the device to attach
  • persistent – A bool to indicate whether the change is persistent or not
  • live – A bool to indicate whether it affect the guest in running state
classmethod create(xml, host)

Create a new Guest

  • xml – XML definition of the domain to create
  • host – host.Host connection to define the guest on
Returns guest.Guest:

Guest ready to be launched


Undefines a domain from hypervisor.

detach_device(conf, persistent=False, live=False)

Detaches device to the guest.

  • conf – A LibvirtConfigObject of the device to detach
  • persistent – A bool to indicate whether the change is persistent or not
  • live – A bool to indicate whether it affect the guest in running state
detach_device_with_retry(get_device_conf_func, device, persistent, live, max_retry_count=7, inc_sleep_time=2, max_sleep_time=30)

Detaches a device from the guest. After the initial detach request, a function is returned which can be used to ensure the device is successfully removed from the guest domain (retrying the removal as necessary).

  • get_device_conf_func – function which takes device as a parameter and returns the configuration for device
  • device – device to detach
  • persistent – bool to indicate whether the change is persistent or not
  • live – bool to indicate whether it affects the guest in running state
  • max_retry_count – number of times the returned function will retry a detach before failing
  • inc_sleep_time – incremental time to sleep in seconds between detach retries
  • max_sleep_time – max sleep time in seconds beyond which the sleep time will not be incremented using param inc_sleep_time. On reaching this threshold, max_sleep_time will be used as the sleep time.

Enables hairpin mode for this guest.


Freeze filesystems within guest.


Returns all devices for a guest

Parameters:devtype – a LibvirtConfigGuestDevice subclass class
Returns:a list of LibvirtConfigGuestDevice instances

Returns all the disks for a guest

Returns:a list of LibvirtConfigGuestDisk instances

Returns a block device wrapper for disk.


Returns the disk mounted at device

Returns LivirtConfigGuestDisk:
 mounted at device or None

Retrieve information from libvirt for a specific instance name.

If a libvirt error is encountered during lookup, we might raise a NotFound exception or Error exception depending on how severe the libvirt error is.

Returns hardware.InstanceInfo:

Lookup a LibvirtConfigGuestInterface by the MAC address.

Parameters:mac (str) – MAC address of the guest interface.
Returns:nova.virt.libvirt.config.LibvirtConfigGuestInterface instance if found, else None

Returns a list of all network interfaces for this domain.


Returns virtual cpus information of guest.

get_xml_desc(dump_inactive=False, dump_sensitive=False, dump_migratable=False)

Returns xml description of guest.

  • dump_inactive – Dump inactive domain information
  • dump_sensitive – Dump security sensitive information
  • dump_migratable – Dump XML suitable for migration
Returns string:

XML description of the guest


Whether domain config is persistently stored on the host.


Injects an NMI to a guest.


Determines whether guest is currently running.


Starts a created guest.

Parameters:pause – Indicates whether to start and pause the guest

Suspends an active guest

Process is frozen without further access to CPU resources and I/O but the memory used by the domain at the hypervisor level will stay allocated.

See method “resume()” to reactive guest.


Stops a running guest.


Resumes a suspended guest.


Saves the domain’s memory state. Requires running domain.

raises: raises libvirtError on error

set_user_password(user, new_pass)

Configures a new user password.


Shutdown guest

snapshot(conf, no_metadata=False, disk_only=False, reuse_ext=False, quiesce=False)

Creates a guest snapshot.

  • conf – libvirt.LibvirtConfigGuestSnapshotDisk
  • no_metadata – Make snapshot without remembering it
  • disk_only – Disk snapshot, no system checkpoint
  • reuse_ext – Reuse any existing external files
  • quiesce – Use QGA to quiece all mounted file systems

Thaw filesystems within guest.

class VCPUInfo(id, cpu, state, time)

Bases: object

Previous topic

The nova.virt.libvirt.firewall Module

Next topic

The Module

Project Source

This Page