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

COMMIT_DEFAULT_BANDWIDTH = 0

REBASE_DEFAULT_BANDWIDTH = 0

abort_job(async=False, pivot=False)

Request to cancel any job currently running on the block.

Parameters:

• 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

get_job_info()

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

Parameters:

• 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

resize(size_kb)

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.

Parameters:

• 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)

Returns:

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.

Parameters:

• 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

Parameters:

• 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

delete_configuration()

Undefines a domain from hypervisor.

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

Detaches device to the guest.

Parameters:

• 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).

Parameters:

• 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.

enable_hairpin()

Enables hairpin mode for this guest.

freeze_filesystems()

Freeze filesystems within guest.

get_all_devices(devtype=None)

Returns all devices for a guest

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

get_all_disks()

Returns all the disks for a guest

Returns:a list of LibvirtConfigGuestDisk instances

get_block_device(disk)

Returns a block device wrapper for disk.

get_disk(device)

Returns the disk mounted at device

Returns LivirtConfigGuestDisk:  mounted at device or None

get_info(host)

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:  

get_interface_by_mac(mac)

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

get_interfaces()

Returns a list of all network interfaces for this domain.

get_power_state(host)

get_vcpus_info()

Returns virtual cpus information of guest.

Returns:guest.VCPUInfo

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

Returns xml description of guest.

Parameters:

• 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

has_persistent_configuration()

Whether domain config is persistently stored on the host.

id

inject_nmi()

Injects an NMI to a guest.

is_active()

Determines whether guest is currently running.

launch(pause=False)

Starts a created guest.

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

name

pause()

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.

poweroff()

Stops a running guest.

resume()

Resumes a suspended guest.

save_memory_state()

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()

Shutdown guest

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

Creates a guest snapshot.

Parameters:

• 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()

Thaw filesystems within guest.

uuid

class VCPUInfo(id, cpu, state, time)

Bases: object