Capability Information Methods¶
The getCapabilities method call can be used to obtain information about the capabilities of the virtualization host. If successful, it returns a string containing the capabilities XML (described below). If an error occurred, None will be returned instead.
The following code demonstrates the use of the getCapabilities method:
import libvirt
conn = libvirt.open("qemu:///system")
if not conn:
raise SystemExit("Failed to open connection to qemu:///system")
caps = conn.getCapabilities() # caps will be a string of XML
print("Capabilities:\n" + caps)
conn.close()
The capabilities XML format provides information about the host virtualization technology. In particular, it describes the capabilities of the virtualization host, the virtualization driver, and the kinds of guests that the virtualization technology can launch.
Note:
The capabilities XML can (and does) vary based on the libvirt driver in use.
An example capabilities XML looks like:
<capabilities>
<host>
<cpu>
<arch>x86_64</arch>
</cpu>
<migration_features>
<live/>
<uri_transports>
<uri_transport>tcp</uri_transport>
</uri_transports>
</migration_features>
<topology>
<cells num="1">
<cell id="0">
<cpus num="2">
<cpu id="0"/>
<cpu id="1"/>
</cpus>
</cell>
</cells>
</topology>
</host>
<guest>
<os_type>hvm</os_type>
<arch name="i686">
<wordsize>32</wordsize>
<emulator>/usr/bin/qemu</emulator>
<machine>pc</machine>
<machine>isapc</machine>
<domain type="qemu">
</domain>
<domain type="kvm">
<emulator>/usr/bin/qemu-kvm</emulator>
</domain>
</arch>
<features>
<pae/>
<nonpae/>
<acpi default="on" toggle="yes"/>
<apic default="on" toggle="no"/>
</features>
</guest>
<guest>
<os_type>hvm</os_type>
<arch name="x86_64">
<wordsize>64</wordsize>
<emulator>/usr/bin/qemu-system-x86_64</emulator>
<machine>pc</machine>
<machine>isapc</machine>
<domain type="qemu">
</domain>
<domain type="kvm">
<emulator>/usr/bin/qemu-kvm</emulator>
</domain>
</arch>
<features>
<acpi default="on" toggle="yes"/>
<apic default="on" toggle="no"/>
</features>
</guest>
</capabilities>
(the rest of the discussion will refer back to this XML using XPath notation). In the capabilities XML, there is always the /host sub-document, and zero or more /guest sub-documents (while zero guest sub-documents are allowed, this means that no guests of this particular driver can be started on this particular host).
- /host
Describes the capabilities of the host.
- /host/uuid
Shows the UUID of the host. This is derived from the SMBIOS UUID if it is available and valid, or can be overridden in libvirtd.conf
with a custom value. If neither of the above are properly set, a temporary UUID will be generated each time that libvirtd is restarted.
- /host/cpu
Describes the capabilities of the host's CPUs. It is used by libvirt when deciding whether a guest can be properly started on this particular machine, and is also consulted during live migration to determine if the destination machine supplies the necessary flags to continue to run the guest.
- /host/cpu/arch
A required XML node that describes the underlying host CPU architecture. As of this writing, all libvirt drivers initialize this from the output of uname
.
- /host/cpu/model
An optional element that describes the CPU model that the host CPUs most closely resemble. The list of CPU models that libvirt currently know about are in the cpu_map.xml
file.
- /host/cpu/feature
Zero or more elements that describe additional CPU features that the host CPUs have that are not covered in /host/cpu/model.
- /host/cpu/features
An optional sub-document that describes additional cpu features present on the host. As of this writing, it is only used by the xen driver to report on the presence or lack of the svm or vmx flag, and to report on the presence or lack of the pae flag.
- /host/migration_features
An optional sub-document that describes the migration features that this driver supports on this host (if any). If this sub-document does not exist, then migration is not supported. As of this writing, the xen, qemu, and esx drivers support migration.
- /host/migration_features/live
XML node exists if the driver supports live migration.
- /host/migration_features/uri_transports
An optional sub-document that describes alternate migration connection mechanisms. These alternate connection mechanisms can be useful on multi-homed virtualization systems. For instance, the virsh migrate
command might connect to the source of the migration via 10.0.0.1, and the destination of the migration via 10.0.0.2. However, due to security policy, the source of the migration might only be allowed to talk directly to the destination of the migration via 192.168.0.0/24. In this case, using the alternate migration connection mechanism would allow this migration to succeed. As of this writing, the xen driver supports the alternate migration mechanism "xenmigr", while the qemu driver supports the alternate migration mechanism "tcp". Please see the documentation on migration for more information.
- /host/topology
A sub-document that describes the NUMA topology of the host machine; each NUMA node is represented by a /host/topology/cells/cell, and describes which CPUs are in that NUMA node. If the host machine is a UMA (non-NUMA) machine, then there will be only one cell and all CPUs will be in this cell. This is very hardware-specific, so will necessarily vary between different machines.
- /host/secmodel
An optional sub-document that describes the security model in use on the host. /host/secmodel/model shows the name of the security model while /host/secmodel/doi shows the Domain Of Interpretation. For more information about security, please see the Security section.
- /guest
Each /guest sub-document describes a kind of guest that this host driver can start. This description includes the architecture of the guest (i.e. i686) along with the ABI provided to the guest (i.e. hvm, xen, or uml).
- /guest/os_type
A required element that describes the type of guest.
Driver | Guest Type |
---|---|
qemu | Always "hvm" |
xen | Either "xen" for a paravirtualized guest or "hvm" for a fully virtualized guest |
uml | Always "uml" |
lxc | Always "exe" |
vbox | Always "hvm" |
openvz | Always "exe" |
one | Always "hvm" |
ex | Not supported at this time |
- /guest/arch
The root of an XML sub-document describing various virtual hardware aspects of this guest type. It has a single attribute called "name", which can be used to refer back to this sub-document.
- /guest/arch/wordsize
A required element that describes how many bits per word this guest type uses. This is typically 32 or 64.
- /guest/arch/emulator
An optional element that describes the default path to the emulator for this guest type. Note that the emulator can be overridden by the /guest/arch/domain/emulator element (described below) for guest types that need alternate binaries.
- /guest/arch/loader
An optional element that describes the default path to the firmware loader for this guest type. Note that the default loader path can be overridden by the /guest/arch/domain/loader element (described below) for guest types that use alternate loaders. At present, this is only used by the xen driver for HVM guests.
- /guest/arch/machine
There can be zero or more /guest/arch/machine elements that describe the default types of machines that this guest emulator can emulate. These "machines" typically represent the ABI or hardware interface that a guest can be started with. Note that these machine types can be overridden by the /guest/arch/domain/machine elements (described below) for virtualization technologies that provide alternate machine types. Typical values for this are "pc", and "isapc", meaning a regular PCI based PC, and an older, ISA based PC, respectively.
- /guest/arch/domain
There can be zero or more /guest/arch/domain XML sub-trees (although with zero /guest/arch/domain XML sub-trees, no guests of this driver can be started). Each /guest/arch/domain XML sub-tree has optional <emulator>
, <loader>
, and <machine>
elements that override the respective defaults specified above. For any of the elements that are missing, the default values are used.
- /guest/features
An optional sub-document describes various additional guest features that can be enabled or disabled, along with their default state and whether they can be toggled on or off.