commit f359b8aa6034cfb4b60816fd215fd72c9a7abfb0
Author: W. David Ashley <w.david.ashley(a)gmail.com>
Date: Thu Jun 25 08:29:55 2015 -0500
Update the Introduction and Architecture chapters for Python.
en-US/Architecture.xml | 1396 ++++++++++++++++++++++++------------------------
en-US/Introduction.xml | 223 ++++----
2 files changed, 818 insertions(+), 801 deletions(-)
---
diff --git a/en-US/Architecture.xml b/en-US/Architecture.xml
index 4f892ed..6307295 100644
--- a/en-US/Architecture.xml
+++ b/en-US/Architecture.xml
@@ -4,767 +4,785 @@
%BOOK_ENTITIES;
]>
<chapter id="libvirt_application_development_guide_using_python-Architecture">
- <title>Architecture</title>
- <para>
- This chapter describes the main principles and architecture choices behind the definition of the libvirt API.
- </para>
+ <title>Architecture</title>
+ <para>
+ This chapter describes the main principles and architecture choices behind the definition of the
+ libvirt API and the Python libvirt module.
+ </para>
- <section id="libvirt_application_development_guide_using_python-Architecture-Object_Model">
- <title>Object model</title>
+ <section id="libvirt_application_development_guide_using_python-Architecture-Object_Model">
+ <title>Object model</title>
- <para>
+ <para>
+ The scope of the libvirt API and the Python libvirt module is intended to extend to all functions necessary for
+ deployment and management of virtual machines. This entails management of both the core
+ hypervisor functions and host resources that are required by virtual machines, such as
+ networking, storage and PCI/USB devices. Most of the classes and methods exposed by libvirt have
+ a pluggable internal backend, allowing support for different underlying virtualization
+ technologies and operating systems. Thus, the extent of the functionality available from
+ a particular API or method is determined by the specific hypervisor driver in use and the
+ capabilities of the underlying virtualization technology.
+ </para>
- The scope of the libvirt API is intended to extend to all functions necessary for
- deployment and management of virtual machines. This entails management of both the core
- hypervisor functions and host resources that are required by virtual machines, such as
- networking, storage and PCI/USB devices. Most of the APIs exposed by libvirt have
- a pluggable internal backend, allowing support for different underlying virtualization
- technologies and operating systems. Thus, the extent of the functionality available from
- an particular API is determined by the specific hypervisor driver in use and the
- capabilities of the underlying virtualization technology.
- </para>
+ <section id="libvirt_application_development_guide_using_python-Architecture-Object_Model-Connection">
+ <title>Hypervisor connections</title>
- <section id="libvirt_application_development_guide_using_python-Architecture-Object_Model-Connection">
- <title>Hypervisor connections</title>
-
- <para>
- A connection is the primary or top level object in the libvirt API. An instance
- of this object is required before attempting to use almost any of the APIs. A
- connection is associated with a particular hypervisor, which may be running locally
- on the same machine as the libvirt client application, or on a remote machine
- over the network. In all cases, the connection is represented with the <literal>virConnectPtr</literal> object and identified by a URI. The URI scheme
- and path defines the hypervisor to connect to, while the host part of the URI
- determines where it is located. Refer to <xref linkend="libvirt_application_development_guide_using_python-Connections-URI_Formats"/>
- for a full description of valid URIs.
- </para>
-
- <para>
- An application is permitted to open multiple connections at the same time, even when using
- more than one type of hypervisor on a single machine. For example, a host may provide
- both KVM full machine virtualization and LXC container virtualization. A connection
- object may be used concurrently across multiple threads. Once a connection has been
- established, it is possible to obtain handles to other managed objects or create new
- managed objects, as discussed in <xref linkend="libvirt_application_development_guide_using_python-Architecture-Object_Model-Domain"/>.
- </para>
- </section>
+ <para>
+ A connection is the primary or top level object in the libvirt API and Python libvirt module. An instance
+ of this object is required before attempting to use almost any of the classes or methods. A
+ connection is associated with a particular hypervisor, which may be running locally
+ on the same machine as the libvirt client application, or on a remote machine
+ over the network. In all cases, the connection is represented by an instance of the <literal>virConnect</literal> class and identified by a URI. The URI scheme
+ and path defines the hypervisor to connect to, while the host part of the URI
+ determines where it is located. Refer to <xref linkend="libvirt_application_development_guide_using_python-Connections-URI_Formats"/>
+ for a full description of valid URIs.
+ </para>
- <section id="libvirt_application_development_guide_using_python-Architecture-Object_Model-Domain">
- <title>Guest domains</title>
-
- <para>
- A guest domain can refer to either a running virtual machine or a configuration
- that can be used to launch a virtual machine. The connection object provides APIs
- to enumerate the guest domains, create new guest domains and manage existing domains.
- A guest domain is represented with the
- <literal>virDomainPtr</literal>
- object and has a number of unique identifiers.
- </para>
-
- <itemizedlist>
- <title>Unique identifiers</title>
-
- <listitem>
-
- <para>
- <application>ID</application>: positive integer, unique amongst running guest domains on a single
- host. An inactive domain does not have an ID.
- </para>
- </listitem>
-
- <listitem>
-
- <para>
- <application>name</application>: short string, unique amongst all guest domains on a single host, both running and inactive. To ensure maximum portability between hypervisors, it is recommended that names only include alphanumeric (<literal>a</literal> - <literal>Z</literal>, <literal>0</literal> - <literal>9</literal>), hyphen (<literal> - </literal>) and underscore (<literal> _ </literal>) characters.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <application>UUID</application>: 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.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- A guest domain may be transient or persistent. A transient guest domain
- can only be managed while it is running on the host. Once it is powered off, all trace 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 configuration. A transient guest can be turned into
- a persistent guest while it is running by defining a configuration for it.
- </para>
-
- <para>
- Refer to <xref linkend="libvirt_application_development_guide_using_python-Guest_Domains"/> for further information about using guest domain objects.
- </para>
- </section>
+ <para>
+ An application is permitted to open multiple connections at the same time, even when using
+ more than one type of hypervisor on a single machine. For example, a host may provide
+ both KVM full machine virtualization and LXC container virtualization. A connection
+ object may be used concurrently across multiple threads. Once a connection has been
+ established, it is possible to obtain handles to other managed objects or create new
+ managed objects, as discussed in <xref linkend="libvirt_application_development_guide_using_python-Architecture-Object_Model-Domain"/>.
+ </para>
+ </section>
- <section id="libvirt_application_development_guide_using_python-Architecture-Network">
- <title>Virtual networks</title>
-
- <para>
- A virtual network provides a method for connecting the network devices of one or more guest domains within a single host. The virtual network can either:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- Remain isolated to the host; or
- </para>
- </listitem>
- <listitem>
- <para>
- Allow routing of traffic off-node via the active network interfaces of the host OS. This includes the option to apply NAT to IPv4 traffic.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- A virtual network is represented by the <literal>virNetworkPtr</literal> object and has two unique
- identifiers:
- </para>
-
- <itemizedlist>
- <title>Unique identifiers</title>
- <listitem>
- <para>
- <application>name</application>: short string, unique amongst all virtual network on a single host,
- both running and inactive. For maximum portability between hypervisors, applications should only use the characters <literal>a-Z,0-9,-,_</literal> in names.
- </para>
- </listitem>
- <listitem>
- <para>
- <application>UUID</application>: 16 unsigned bytes, guaranteed to be unique amongst all virtual
- networks on any host. RFC 4122 defines the format for UUIDs and provides
- a recommended algorithm for generating UUIDs with guaranteed uniqueness.
- </para>
- </listitem>
- </itemizedlist>
-
-
- <para>
- A virtual network may be transient or persistent. A transient virtual network can only be managed while it it is running on the host. When taken offline, all traces of it will disappear. A persistent virtual network has its configuration maintained in a data store on the host, in an implementation defined format. Thus when a persistent network is brought offline, it is still possible to manage its inactive config. A transient network can be turned into a persistent network on the fly by defining a configuration for it.
- </para>
-
- <para>
- After installation of libvirt, every host will get a single virtual network instance called 'default', which provides DHCP services to guests and allows NAT'd IP connectivity to the host's interfaces.
- This service is of most use to hosts with intermittent network connectivity. For example, laptops using wireless networking.
- </para>
-
- <para>
- Refer to <xref linkend="libvirt_application_development_guide_using_python-Virtual_Networks"/> for further information about using virtual network objects.
- </para>
+ <section id="libvirt_application_development_guide_using_python-Architecture-Object_Model-Domain">
+ <title>Guest domains</title>
- </section>
+ <para>
+ A guest domain can refer to either a running virtual machine or a configuration
+ that 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 an instance of the
+ <literal>virDomain</literal> class and has a number of unique identifiers.
+ </para>
- <section id="libvirt_application_development_guide_using_python-Architecture-Object_Model-StoragePool">
- <title>Storage pools</title>
-
- <para>
- The storage pool object provides a mechanism for managing all types of storage on a host, such as local disk, logical volume group, iSCSI target, FibreChannel HBA and local/network file system. A pool refers
- to a quantity storage that is able to be allocated to form individual volumes. A storage pool is represented by the <literal>virStoragePoolPtr</literal> object and has a pair of unique identifiers.
- </para>
-
- <itemizedlist>
- <title>Unique identifiers</title>
- <listitem>
- <para>
- <application>name</application>: short string, unique amongst all storage pools on a single host,
- both running and inactive. For maximum portability between hypervisors
- applications should only rely on being able to use the characters
- <literal>a-Z,0-9,-,_</literal> in names.
- </para>
- </listitem>
- <listitem>
- <para>
- <application>UUID</application>: 16 unsigned bytes, guaranteed to be unique amongst all storage
- pools on any host. RFC 4122 defines the format for UUIDs and provides
- a recommended algorithm for generating UUIDs with guaranteed uniqueness.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- A storage pool may be transient, or persistent. A transient storage pool
- can only be managed while it is running on the host and, when powered off,
- all trace of it will disappear (the underlying physical storage still exists
- of course !). A persistent storage pool has its configuration
- maintained in a data store on the host by the hypervisor, in an implementation
- defined format. Thus when a persistent storage pool is deactivated, it is still
- possible to manage its inactive config. A transient pool can be turned into
- a persistent pool on the fly by defining a configuration for it.
- </para>
-
-
- <para>
- Refer to <xref linkend="libvirt_application_development_guide_using_python-Storage_Pools"/> for further information about using storage pool objects.
- </para>
+ <itemizedlist>
+ <title>Unique identifiers</title>
+ <listitem>
+ <para>
+ <application>ID</application>: positive integer, unique amongst running guest domains on a single
+ host. An inactive domain does not have an ID.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <application>name</application>: short string, unique amongst all guest domains on a single host, both running and inactive. To ensure maximum portability between hypervisors, it is recommended that names only include alphanumeric (<literal>a</literal> - <literal>Z</literal>, <literal>0</literal> - <literal>9</literal>), hyphen (<literal> - </literal>) and underscore (<literal> _ </literal>) characters.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <application>UUID</application>: 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.
+ </para>
+ </listitem>
+ </itemizedlist>
- </section>
+ <para>
+ A guest domain may be transient or persistent. A transient guest domain
+ can only be managed while it is running on the host. Once it is powered off, all trace 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 configuration. A transient guest can be turned into
+ a persistent guest while it is running by defining a configuration for it.
+ </para>
- <section id="libvirt_application_development_guide_using_python-Architecture-Object_Model-StorageVol">
- <title>Storage volumes</title>
-
- <para>
- The storage volume object provides management of an allocated block of
- storage within a pool, be it a disk partition, logical volume, SCSI/iSCSI
- LUN, or a file within a local/network file system. Once allocated, a volume
- can be used to provide disks to one (or more) virtual domains. A volume is
- represented by the <literal>virStorageVolPtr</literal> object, and has
- three identifiers
- </para>
-
- <itemizedlist>
- <title>Unique identifiers</title>
- <listitem>
- <para>
- name: short string, unique amongst all storage volumes within a storage
- pool. For maximum portability between implementations applications
- should only rely on being able to use the characters
- <literal>a-Z,0-9,-,_</literal> in names. The name is not guaranteed
- to be stable across reboots, or between hosts, even if the storage
- pool is shared between hosts.
- </para>
- </listitem>
- <listitem>
- <para>
- <application>Key</application>: a opaque string, of arbitrary printable characters, intended to
- uniquely identify the volume within the pool. The key is intended to be
- stable across reboots, and between hosts.
- </para>
- </listitem>
- <listitem>
- <para>
- <application>Path</application>: a file system path referring to the volume. The path is unique
- amongst all storage volumes on a single host. If the storage pool
- is configured with a suitable target path, the volume path may be
- stable across reboots, and between hosts.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- Refer to <xref linkend="libvirt_application_development_guide_using_python-Storage_Pools-Volume"/> for further information about using storage volume objects
- </para>
+ <para>
+ Refer to <xref linkend="libvirt_application_development_guide_using_python-Guest_Domains"/> for further information about using guest domain objects.
+ </para>
+ </section>
- </section>
+ <section id="libvirt_application_development_guide_using_python-Architecture-Network">
+ <title>Virtual networks</title>
- <section id="libvirt_application_development_guide_using_python-Architecture-Object_Model-HostDev">
- <title>Host devices</title>
-
- <para>
- Host devices provide a view to the hardware devices available on the
- host machine. This covers both the physical USB or PCI devices and
- logical devices these provide, such as a NIC, disk, disk controller,
- sound card, etc. Devices can be arranged to form a tree structure
- allowing relationships to be identified. A host device is represented
- by the <literal>virNodeDevPtr</literal> object, and has one
- general identifier, though specific device types may have their own
- unique identifiers.
- </para>
-
- <itemizedlist>
- <title>Unique identifiers</title>
- <listitem>
- <para>
- <application>name</application>: short string, unique amongst all devices on the host. The
- naming scheme is determined by the host operating system. The name
- is not guaranteed to be stable across reboots.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- Physical devices can be detached from the host OS drivers,
- which implicitly removes all associated logical devices, and
- then assigned to a guest domain. Physical device information is
- also useful when working with the storage and networking APIs
- to determine what resources are available to configure.
- </para>
-
- <para>
- Refer to <xref linkend="libvirt_application_development_guide_using_python-Host_Devices"/> for further information about using host device objects.
- </para>
+ <para>
+ A virtual network provides a method for connecting the network devices of one or more guest
+ domains within a single host. The virtual network can either:
+ </para>
- </section>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Remain isolated to the host; or
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Allow routing of traffic off-node via the active network interfaces of the host OS.
+ This includes the option to apply NAT to IPv4 traffic.
+ </para>
+ </listitem>
+ </itemizedlist>
- </section>
+ <para>
+ A virtual network is represented by an instance of the <literal>virNetwork</literal> class and has
+ two unique identifiers:
+ </para>
- <section id="libvirt_application_development_guide_using_python-Architecture-Driver_Model">
- <title>Driver model</title>
+ <itemizedlist>
+ <title>Unique identifiers</title>
+ <listitem>
+ <para>
+ <application>name</application>: short string, unique amongst all virtual network on
+ a single host, both running and inactive. For maximum portability between hypervisors,
+ applications should only use the characters <literal>a-Z,0-9,-,_</literal> in names.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <application>UUID</application>: 16 unsigned bytes, guaranteed to be unique amongst
+ all virtual networks on any host. RFC 4122 defines the format for UUIDs and provides
+ a recommended algorithm for generating UUIDs with guaranteed uniqueness.
+ </para>
+ </listitem>
+ </itemizedlist>
- <para>
- The libvirt library exposes a guaranteed stable API & ABI which is decoupled
- from any particular virtualization technology. In addition many of the APIs have
- associated XML schemata which are considered part of the stable ABI guarantee.
- Internally, there are multiple of implementations of the public ABI, each
- targeting a different virtualization technology. Each implementation is referred
- to as a driver. When obtaining a instance of the <literal>virConnectPtr</literal>
- object, the application developer can provide a URI to determine which hypervisor
- driver is activated.
- </para>
+ <para>
+ A virtual network may be transient or persistent. A transient virtual network can only be
+ managed while it it is running on the host. When taken offline, all traces of it will disappear. A persistent virtual network has its configuration maintained in a data store on the host, in an implementation defined format. Thus when a persistent network is brought offline, it is still possible to manage its inactive config. A transient network can be turned into a persistent network on the fly by defining a configuration for it.
+ </para>
- <para>
- No two virtualization technologies have exactly the same functionality.
- The libvirt goal is not to restrict applications to a lowest common
- denominator, since this would result in an unacceptably limited API.
- Instead libvirt attempts to define a representation of concepts and
- configuration that is hypervisor agnostic, and adaptable to allow
- future extensions. Thus, if two hypervisors implement a comparable
- feature, libvirt provides a uniform control mechanism or configuration
- format for that feature.
- </para>
+ <para>
+ After installation of libvirt, every host will get a single virtual network instance called
+ 'default', which provides DHCP services to guests and allows NAT'd IP connectivity to the
+ host's interfaces. This service is of most use to hosts with intermittent network connectivity.
+ For example, laptops using wireless networking.
+ </para>
- <para>
- If a libvirt driver does not implement a particular API, then it will
- return a VIR_ERR_NO_SUPPORT error code enabling this to be detected.
- There is also an API to allow applications to the query certain
- capabilities of a hypervisor, such as the type of guest ABIs that
- are supported.
- </para>
+ <para>
+ Refer to <xref linkend="libvirt_application_development_guide_using_python-Virtual_Networks"/>
+ for further information about using virtual network objects.
+ </para>
- <para>
- Internally a libvirt driver will attempt to utilize whatever management
- channels are available for the virtualization technology in question.
- For some drivers this may require libvirt to run directly on the host
- being managed, talking to a local hypervisor, while others may be able
- to communicate remotely over an RPC service. For drivers which have
- no native remote communication capability, libvirt provides a generic
- secure RPC service. This is discussed in detail later in this chapter.
- </para>
+ </section>
- <itemizedlist>
- <title>Hypervisor drivers</title>
+ <section id="libvirt_application_development_guide_using_python-Architecture-Object_Model-StoragePool">
+ <title>Storage pools</title>
- <listitem>
- <para>
- <application>Xen</application>: The open source Xen hypervisor
- providing paravirtualized and fully virtualized machines.
- A single system driver runs in the Dom0 host talking directly
- to a combination of the hypervisor, xenstored and xend.
- Example local URI scheme <literal>xen:///</literal>.
- </para>
- </listitem>
+ <para>
+ The storage pool object provides a mechanism for managing all types of storage on a host,
+ such as local disk, logical volume group, iSCSI target, FibreChannel HBA and local/network
+ file system. A pool refers to a quantity storage that is able to be allocated to form
+ individual volumes. A storage pool is represented by an instance of the
+ <literal>virStoragePool</literal> class and has a pair of unique identifiers.
+ </para>
- <listitem>
- <para>
- <application>QEMU</application>: Any open source QEMU based virtualization
- technology, including KVM. A single privileged system driver runs in the host
- managing QEMU processes. Each unprivileged user account also has a private instance
- of the driver. Example privileged URI scheme <literal>qemu:///system</literal>.
- Example unprivileged URI scheme <literal>qemu:///session</literal>
- </para>
- </listitem>
+ <itemizedlist>
+ <title>Unique identifiers</title>
+ <listitem>
+ <para>
+ <application>name</application>: short string, unique amongst all storage pools on a
+ single host, both running and inactive. For maximum portability between hypervisors
+ applications should only rely on being able to use the characters
+ <literal>a-Z,0-9,-,_</literal> in names.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <application>UUID</application>: 16 unsigned bytes, guaranteed to be unique amongst
+ all storage pools on any host. RFC 4122 defines the format for UUIDs and provides
+ a recommended algorithm for generating UUIDs with guaranteed uniqueness.
+ </para>
+ </listitem>
+ </itemizedlist>
- <listitem>
- <para>
- <application>UML</application>: The User Mode Linux kernel, a pure paravirtualization
- technology. A single privileged system driver runs in the host managing
- UML processes. Each unprivileged user account also has a private instance
- of the driver. Example privileged URI scheme <literal>uml:///system</literal>.
- Example unprivileged URI scheme <literal>uml:///session</literal>
- </para>
- </listitem>
+ <para>
+ A storage pool may be transient, or persistent. A transient storage pool
+ can only be managed while it is running on the host and, when powered off,
+ all trace of it will disappear (the underlying physical storage still exists
+ of course !). A persistent storage pool has its configuration
+ maintained in a data store on the host by the hypervisor, in an implementation
+ defined format. Thus when a persistent storage pool is deactivated, it is still
+ possible to manage its inactive config. A transient pool can be turned into
+ a persistent pool on the fly by defining a configuration for it.
+ </para>
+
+
+ <para>
+ Refer to <xref linkend="libvirt_application_development_guide_using_python-Storage_Pools"/> for further information about using storage pool objects.
+ </para>
+
+ </section>
+
+ <section id="libvirt_application_development_guide_using_python-Architecture-Object_Model-StorageVol">
+ <title>Storage volumes</title>
+
+ <para>
+ The storage volume object provides management of an allocated block of
+ storage within a pool, be it a disk partition, logical volume, SCSI/iSCSI
+ LUN, or a file within a local/network file system. Once allocated, a volume
+ can be used to provide disks to one (or more) virtual domains. A volume is
+ represented by an instance of the <literal>virStorageVol</literal> class, and has
+ three identifiers
+ </para>
+
+ <itemizedlist>
+ <title>Unique identifiers</title>
+ <listitem>
+ <para>
+ name: short string, unique amongst all storage volumes within a storage
+ pool. For maximum portability between implementations applications
+ should only rely on being able to use the characters
+ <literal>a-Z,0-9,-,_</literal> in names. The name is not guaranteed
+ to be stable across reboots, or between hosts, even if the storage
+ pool is shared between hosts.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <application>Key</application>: a opaque string, of arbitrary printable characters,
+ intended to uniquely identify the volume within the pool. The key is intended to be
+ stable across reboots, and between hosts.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <application>Path</application>: a file system path referring to the volume. The path
+ is unique amongst all storage volumes on a single host. If the storage pool
+ is configured with a suitable target path, the volume path may be
+ stable across reboots, and between hosts.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ Refer to <xref linkend="libvirt_application_development_guide_using_python-Storage_Pools-Volume"/>
+ for further information about using storage volume objects
+ </para>
+
+ </section>
+
+ <section id="libvirt_application_development_guide_using_python-Architecture-Object_Model-HostDev">
+ <title>Host devices</title>
+
+ <para>
+ Host devices provide a view to the hardware devices available on the
+ host machine. This covers both the physical USB or PCI devices and
+ logical devices these provide, such as a NIC, disk, disk controller,
+ sound card, etc. Devices can be arranged to form a tree structure
+ allowing relationships to be identified. A host device is represented
+ by an instance of the <literal>virNodeDev</literal> class, and has one
+ general identifier, though specific device types may have their own
+ unique identifiers.
+ </para>
+
+ <itemizedlist>
+ <title>Unique identifiers</title>
+ <listitem>
+ <para>
+ <application>name</application>: short string, unique amongst all devices on the host.
+ The naming scheme is determined by the host operating system. The name
+ is not guaranteed to be stable across reboots.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ Physical devices can be detached from the host OS drivers,
+ which implicitly removes all associated logical devices, and
+ then assigned to a guest domain. Physical device information is
+ also useful when working with the storage and networking APIs
+ to determine what resources are available to configure.
+ </para>
+
+ <para>
+ Refer to <xref linkend="libvirt_application_development_guide_using_python-Host_Devices"/>
+ for further information about using host device objects.
+ </para>
+
+ </section>
+
+ </section>
+
+ <section id="libvirt_application_development_guide_using_python-Architecture-Driver_Model">
+ <title>Driver model</title>
- <listitem>
<para>
- <application>OpenVZ</application>: The OpenVZ container based virtualization
- technology, using a modified Linux host kernel. A single privileged system
- driver runs in the host talking to the OpenVZ tools. Example privileged
- URI scheme <literal>openvz:///system</literal>
+ The libvirt library exposes a guaranteed stable API & ABI which is decoupled
+ from any particular virtualization technology. In addition many of the APIs have
+ associated XML schemata which are considered part of the stable ABI guarantee.
+ Internally, there are multiple of implementations of the public ABI, each
+ targeting a different virtualization technology. Each implementation is referred
+ to as a driver. When obtaining a instance of the <literal>virConnect</literal>
+ class, the application developer can provide a URI to determine which hypervisor
+ driver is activated.
</para>
- </listitem>
- <listitem>
<para>
- <application>LXC</application>: The native Linux container based virtualization
- technology, available with Linux kernels since 2.6.25. A single privileged system
- driver runs in the host talking to the kernel. Example privileged
- URI scheme <literal>lxc:///</literal>
+ No two virtualization technologies have exactly the same functionality.
+ The libvirt goal is not to restrict applications to a lowest common
+ denominator, since this would result in an unacceptably limited API.
+ Instead libvirt attempts to define a representation of concepts and
+ configuration that is hypervisor agnostic, and adaptable to allow
+ future extensions. Thus, if two hypervisors implement a comparable
+ feature, libvirt provides a uniform control mechanism or configuration
+ format for that feature.
</para>
- </listitem>
- <listitem>
<para>
- <application>Remote</application>: Generic secure RPC service talking to
- a <literal>libvirtd</literal> daemon. Encryption and authentication using
- a choice of TLS, x509 certificates, SASL (GSSAPI/Kerberos) and SSH tunneling.
- URIs follow the scheme of the desired driver, but with a hostname filled
- in, and a data transport name appended to the URI scheme. Example URI to
- talk to Xen over a TLS channel <literal>xen+tls://somehostname/</literal>.
- Example URI to talk to QEMU over a SASL channel <literal>qemu+tcp:///somehost/system</literal>
+ If a libvirt driver does not implement a particular API, then it will
+ return a VIR_ERR_NO_SUPPORT error code enabling this to be detected.
+ There is also an API to allow applications to the query certain
+ capabilities of a hypervisor, such as the type of guest ABIs that
+ are supported.
</para>
- </listitem>
- <listitem>
<para>
- <application>Test</application>: A mock driver, providing a virtual
- in-memory hypervisor covering all the libvirt APIs. Facilities testing
- of applications using libvirt, by allowing automated tests to run which
- exercise libvirt APIs without needing to deal with a real hypervisor
- Example default URI scheme <literal>test:///default</literal>.
- Example customized URI scheme <literal>test:///path/to/driver/config.xml</literal>
+ Internally a libvirt driver will attempt to utilize whatever management
+ channels are available for the virtualization technology in question.
+ For some drivers this may require libvirt to run directly on the host
+ being managed, talking to a local hypervisor, while others may be able
+ to communicate remotely over an RPC service. For drivers which have
+ no native remote communication capability, libvirt provides a generic
+ secure RPC service. This is discussed in detail later in this chapter.
</para>
- </listitem>
- </itemizedlist>
-
- <figure id="driver_arch">
- <title>libvirt driver architecture</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/159516-libvirt-driver-arch.png" format="PNG"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- </section>
-
- <section id="libvirt_application_development_guide_using_python-Architecture-Remote_Management">
- <title>Remote management</title>
-
- <para>
- While many virtualization technologies provide a remote management
- capability, libvirt does not assume this and provides a dedicated
- driver allowing for remote management of any libvirt hypervisor
- driver. The driver has a variety of data transports providing
- considerable security for the data communication. The driver is
- designed such that there is 100% functional equivalence whether
- talking to the libvirt driver locally, or via the RPC service.
- </para>
- <para>
- In addition to the native RPC service included in libvirt, there
- are a number of alternatives for remote management that will not
- be discussed in this document. The <literal>libvirt-qpid</literal>
- project provides an agent for the QPid messaging service, exposing
- all libvirt managed objects and operations over the message bus.
- This keeps a fairly close, near 1-to-1, mapping to the C API in
- libvirt. The <literal>libvirt-CIM</literal> project provides a
- CIM agent, that maps the libvirt object model onto the DMTF
- virtualization schema.
- </para>
-
- <section id="libvirt_application_development_guide_using_python-Architecture-Remote_Management-Basic_Usage">
- <title>Basic usage</title>
-
- <para>
- The server end of the RPC service is provided by the <literal>libvirtd</literal>
- daemon, which must be run on the host to be managed. In an default
- deployment this daemon will only be listening for connection on a local
- UNIX domain socket. This only allows for a libvirt client to use the
- SSH tunnel data transport. With suitable configuration of x509 certificates,
- or SASL credentials, the <literal>libvirtd</literal> daemon can be told
- to listen on a TCP socket for direct, non-tunneled client connections.
- </para>
-
- <para>
- As can be seen from earlier example libvirt driver URIs, then hostname
- field in the URI is always left empty for local libvirt connections.
- To make use of the libvirt RPC driver, only two changes are required
- to the local URI. At least a hostname must be specified, at which
- point libvirt will attempt to use the direct TLS data transport.
- An alternative data transport can be requested by appending its name
- to the URI scheme. The URIs formats will be described in detail later
- in this document <xref linkend="libvirt_application_development_guide_using_python-Connections-Remote_URIs"/>
- </para>
-
- </section>
+ <itemizedlist>
+ <title>Hypervisor drivers</title>
- <section id="libvirt_application_development_guide_using_python-Architecture-Transports">
- <title>Data Transports</title>
-
- <para>
- To cope with the wide variety of deployment environments, the libvirt
- RPC service supports a number of data transports, all of which can
- be configured with industry standard encryption and authentication
- capabilities.
- </para>
-
- <table id='transports' frame='all'>
- <title>Transports</title>
- <tgroup cols='2' align='left' colsep='1' rowsep='1'>
- <colspec colname='c1' />
- <colspec colname='c2' />
- <thead>
- <row>
- <entry><para>Transport</para></entry>
- <entry><para>Description</para></entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <para>tls</para>
- </entry>
- <entry>
+ <listitem>
<para>
- A TCP socket running the TLS protocol on the wire. This is the
- default data transport if none is explicitly requested, and uses a
- TCP connection on port 16514. At minimum it is necessary to configure
- the server with a x509 certificate authority and issue it a server
- certificate. The <literal>libvirtd</literal> server can, optionally,
- be configured to require clients to present x509 certificates as a
- means of authentication.
+ <application>Xen</application>: The open source Xen hypervisor
+ providing paravirtualized and fully virtualized machines.
+ A single system driver runs in the Dom0 host talking directly
+ to a combination of the hypervisor, xenstored and xend.
+ Example local URI scheme <literal>xen:///</literal>.
</para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>tcp</para>
- </entry>
- <entry>
- <para>
- A TCP socket without the TLS protocol on the wire. This data transport
- should not be used on untrusted networks, unless the SASL authentication
- service has been enabled and configured with a plug-in that provides
- encryption. The TCP connection is made on port 16509.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>unix</para>
- </entry>
- <entry>
+ </listitem>
+
+ <listitem>
<para>
- A local only data transport, allowing users to connect to a
- <literal>libvirtd</literal> daemon running as a different user
- account. As it is only accessible on the local machine, it is
- unencrypted. The standard socket names are
- <literal>/var/run/libvirt/libvirt-sock</literal> for full management
- capabilities and <literal>/var/run/libvirt/libvirt-sock-ro</literal>
- for a socket restricted to read only operations.
+ <application>QEMU</application>: Any open source QEMU based virtualization
+ technology, including KVM. A single privileged system driver runs in the host
+ managing QEMU processes. Each unprivileged user account also has a private instance
+ of the driver. Example privileged URI scheme <literal>qemu:///system</literal>.
+ Example unprivileged URI scheme <literal>qemu:///session</literal>
</para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>ssh</para>
- </entry>
- <entry>
+ </listitem>
+
+ <listitem>
<para>
- The RPC data is tunneled over an SSH connection to the remote
- machine. It requires Netcat (nc) is installed on the remote machine
- and that libvirtd is running with the UNIX domain socket enabled.
- It is recommended that SSH be configured to not require password
- prompts to the client application. For example, if using SSH public
- key authentication it is recommended an ssh-agent by run to cache
- key credentials. GSSAPI is another useful authentication mode for
- the SSH transport allowing use of a pre-initialized Keberos credential
- cache.
+ <application>UML</application>: The User Mode Linux kernel, a pure paravirtualization
+ technology. A single privileged system driver runs in the host managing
+ UML processes. Each unprivileged user account also has a private instance
+ of the driver. Example privileged URI scheme <literal>uml:///system</literal>.
+ Example unprivileged URI scheme <literal>uml:///session</literal>
</para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>ext</para>
- </entry>
- <entry>
+ </listitem>
+
+ <listitem>
<para>
- Any external program that can make a connection to the remote
- machine by means that are outside the scope of libvirt. If
- none of the built-in data transports are satisfactory, this
- allows an application to provide a helper program to proxy
- RPC data over a custom channel.
+ <application>OpenVZ</application>: The OpenVZ container based virtualization
+ technology, using a modified Linux host kernel. A single privileged system
+ driver runs in the host talking to the OpenVZ tools. Example privileged
+ URI scheme <literal>openvz:///system</literal>
</para>
- </entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
-
- </section>
+ </listitem>
- <section id="libvirt_application_development_guide_using_python-Architecture-Authentication">
- <title>Authentication schemes</title>
-
- <para>
- To cope with the wide variety of deployment environments, the libvirt
- RPC service supports a number of authentication schemes on its data
- transports, with industry standard encryption and authentication
- capabilities. The choice of authentication scheme is configured by
- the administrator in the <literal>/etc/libvirt/libvirtd.conf</literal>
- file.
- </para>
-
- <table id='authentications' frame='all'>
- <title>Schemes</title>
- <tgroup cols='2' align='left' colsep='1' rowsep='1'>
- <colspec colname='c1' />
- <colspec colname='c2' />
- <thead>
- <row>
- <entry><para>Scheme</para></entry>
- <entry><para>Description</para></entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <para>sasl</para>
- </entry>
- <entry>
+ <listitem>
<para>
- SASL is a industry standard for pluggable authentication
- mechanisms. Each plug-in has a wide variety of capabilities
- and discussion of their merits is outside the scope of
- this document. For the <literal>tls</literal> data transport
- there is a wide choice of plug-ins, since TLS is providing
- data encryption for the network channel. For the
- <literal>tcp</literal> data transport, libvirt will refuse
- to use any plug-in which does not support data encryption.
- This effectively limits the choice to GSSAPI/Kerberos.
- SASL can optionally be enabled on the UNIX domain socket
- data transport if strong authentication of local users is
- required.
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>polkit</para>
- </entry>
- <entry>
+ <application>LXC</application>: The native Linux container based virtualization
+ technology, available with Linux kernels since 2.6.25. A single privileged system
+ driver runs in the host talking to the kernel. Example privileged
+ URI scheme <literal>lxc:///</literal>
+ </para>
+ </listitem>
+
+ <listitem>
<para>
- PolicyKit is an authentication scheme suitable for local
- desktop virtualization deployments, for use only on the
- UNIX domain socket data transport. It enables the libvirtd
- daemon to validate that the client application is running
- within the local X desktop session. It can be configured
- to allow access to a logged in user automatically, or
- prompt them to enter their own password, or the superuser
- (root) password.
+ <application>Remote</application>: Generic secure RPC service talking to
+ a <literal>libvirtd</literal> daemon. Encryption and authentication using
+ a choice of TLS, x509 certificates, SASL (GSSAPI/Kerberos) and SSH tunneling.
+ URIs follow the scheme of the desired driver, but with a hostname filled
+ in, and a data transport name appended to the URI scheme. Example URI to
+ talk to Xen over a TLS channel <literal>xen+tls://somehostname/</literal>.
+ Example URI to talk to QEMU over a SASL channel
+ <literal>qemu+tcp:///somehost/system</literal>
</para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>x509</para>
- </entry>
- <entry>
+ </listitem>
+
+ <listitem>
<para>
- Although not strictly an authentication scheme, the TLS
- data transport can be configured to mandate the use of
- client x509 certificates. The server can then whitelist
- the client distinguished names to control access.
+ <application>Test</application>: A mock driver, providing a virtual
+ in-memory hypervisor covering all the libvirt APIs. Facilities testing
+ of applications using libvirt, by allowing automated tests to run which
+ exercise libvirt APIs without needing to deal with a real hypervisor
+ Example default URI scheme <literal>test:///default</literal>.
+ Example customized URI scheme <literal>test:///path/to/driver/config.xml</literal>
</para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
+ </listitem>
+ </itemizedlist>
+
+ <figure id="driver_arch">
+ <title>libvirt driver architecture</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/159516-libvirt-driver-arch.png" format="PNG"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
</section>
- </section>
- <section id="libvirt_application_development_guide_using_python-Architecture-TLS_Cert">
- <title>Generating TLS certificates</title>
-
- <para>
- Libvirt supports TLS certificates for verifying the identity of the server and clients. There are two distinct checks involved:
- </para>
+ <section id="libvirt_application_development_guide_using_python-Architecture-Remote_Management">
+ <title>Remote management</title>
- <orderedlist>
- <listitem>
<para>
- The client checks that it is connecting to the correct server by matching the certificate the server sends with the server's hostname. This check can be disabled by adding <literal>?no_verify=1</literal>. Refer to <xref linkend="remote_URI"/> for details.
+ While many virtualization technologies provide a remote management
+ capability, libvirt does not assume this and provides a dedicated
+ driver allowing for remote management of any libvirt hypervisor
+ driver. The driver has a variety of data transports providing
+ considerable security for the data communication. The driver is
+ designed such that there is 100% functional equivalence whether
+ talking to the libvirt driver locally, or via the RPC service.
</para>
- </listitem>
- <listitem>
+
<para>
- The server checks to ensure that only allowed clients are connected. This is performed using either:
+ In addition to the native RPC service included in libvirt, there
+ are a number of alternatives for remote management that will not
+ be discussed in this document. The <literal>libvirt-qpid</literal>
+ project provides an agent for the QPid messaging service, exposing
+ all libvirt managed objects and operations over the message bus.
+ This keeps a fairly close, near 1-to-1, mapping to the C API in
+ libvirt. The <literal>libvirt-CIM</literal> project provides a
+ CIM agent, that maps the libvirt object model onto the DMTF
+ virtualization schema.
</para>
- <orderedlist>
- <listitem>
+ <section id="libvirt_application_development_guide_using_python-Architecture-Remote_Management-Basic_Usage">
+ <title>Basic usage</title>
+
<para>
- The client's IP address; or
+ The server end of the RPC service is provided by the <literal>libvirtd</literal>
+ daemon, which must be run on the host to be managed. In an default
+ deployment this daemon will only be listening for connection on a local
+ UNIX domain socket. This only allows for a libvirt client to use the
+ SSH tunnel data transport. With suitable configuration of x509 certificates,
+ or SASL credentials, the <literal>libvirtd</literal> daemon can be told
+ to listen on a TCP socket for direct, non-tunneled client connections.
</para>
- </listitem>
- <listitem>
+
<para>
- The client's IP address and the client's certificate.
+ As can be seen from earlier example libvirt driver URIs, then hostname
+ field in the URI is always left empty for local libvirt connections.
+ To make use of the libvirt RPC driver, only two changes are required
+ to the local URI. At least a hostname must be specified, at which
+ point libvirt will attempt to use the direct TLS data transport.
+ An alternative data transport can be requested by appending its name
+ to the URI scheme. The URIs formats will be described in detail later
+ in this document
+ <xref linkend="libvirt_application_development_guide_using_python-Connections-Remote_URIs"/>.
</para>
- </listitem>
- </orderedlist>
+
+ </section>
+
+ <section id="libvirt_application_development_guide_using_python-Architecture-Transports">
+ <title>Data Transports</title>
+
+ <para>
+ To cope with the wide variety of deployment environments, the libvirt
+ RPC service supports a number of data transports, all of which can
+ be configured with industry standard encryption and authentication
+ capabilities.
+ </para>
+
+ <table id='transports' frame='all'>
+ <title>Transports</title>
+ <tgroup cols='2' align='left' colsep='1' rowsep='1'>
+ <colspec colname='c1' />
+ <colspec colname='c2' />
+ <thead>
+ <row>
+ <entry><para>Transport</para></entry>
+ <entry><para>Description</para></entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>tls</para>
+ </entry>
+ <entry>
+ <para>
+ A TCP socket running the TLS protocol on the wire. This is the
+ default data transport if none is explicitly requested, and uses a
+ TCP connection on port 16514. At minimum it is necessary to configure
+ the server with a x509 certificate authority and issue it a server
+ certificate. The <literal>libvirtd</literal> server can, optionally,
+ be configured to require clients to present x509 certificates as a
+ means of authentication.
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para>tcp</para>
+ </entry>
+ <entry>
+ <para>
+ A TCP socket without the TLS protocol on the wire. This data transport
+ should not be used on untrusted networks, unless the SASL authentication
+ service has been enabled and configured with a plug-in that provides
+ encryption. The TCP connection is made on port 16509.
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para>unix</para>
+ </entry>
+ <entry>
+ <para>
+ A local only data transport, allowing users to connect to a
+ <literal>libvirtd</literal> daemon running as a different user
+ account. As it is only accessible on the local machine, it is
+ unencrypted. The standard socket names are
+ <literal>/var/run/libvirt/libvirt-sock</literal> for full management
+ capabilities and <literal>/var/run/libvirt/libvirt-sock-ro</literal>
+ for a socket restricted to read only operations.
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para>ssh</para>
+ </entry>
+ <entry>
+ <para>
+ The RPC data is tunneled over an SSH connection to the remote
+ machine. It requires Netcat (nc) is installed on the remote machine
+ and that libvirtd is running with the UNIX domain socket enabled.
+ It is recommended that SSH be configured to not require password
+ prompts to the client application. For example, if using SSH public
+ key authentication it is recommended an ssh-agent by run to cache
+ key credentials. GSSAPI is another useful authentication mode for
+ the SSH transport allowing use of a pre-initialized Keberos credential
+ cache.
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para>ext</para>
+ </entry>
+ <entry>
+ <para>
+ Any external program that can make a connection to the remote
+ machine by means that are outside the scope of libvirt. If
+ none of the built-in data transports are satisfactory, this
+ allows an application to provide a helper program to proxy
+ RPC data over a custom channel.
+ </para>
+ </entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </table>
+
+ </section>
+
+ <section id="libvirt_application_development_guide_using_python-Architecture-Authentication">
+ <title>Authentication schemes</title>
+
+ <para>
+ To cope with the wide variety of deployment environments, the libvirt
+ RPC service supports a number of authentication schemes on its data
+ transports, with industry standard encryption and authentication
+ capabilities. The choice of authentication scheme is configured by
+ the administrator in the <literal>/etc/libvirt/libvirtd.conf</literal>
+ file.
+ </para>
+
+ <table id='authentications' frame='all'>
+ <title>Schemes</title>
+ <tgroup cols='2' align='left' colsep='1' rowsep='1'>
+ <colspec colname='c1' />
+ <colspec colname='c2' />
+ <thead>
+ <row>
+ <entry><para>Scheme</para></entry>
+ <entry><para>Description</para></entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>sasl</para>
+ </entry>
+ <entry>
+ <para>
+ SASL is a industry standard for pluggable authentication
+ mechanisms. Each plug-in has a wide variety of capabilities
+ and discussion of their merits is outside the scope of
+ this document. For the <literal>tls</literal> data transport
+ there is a wide choice of plug-ins, since TLS is providing
+ data encryption for the network channel. For the
+ <literal>tcp</literal> data transport, libvirt will refuse
+ to use any plug-in which does not support data encryption.
+ This effectively limits the choice to GSSAPI/Kerberos.
+ SASL can optionally be enabled on the UNIX domain socket
+ data transport if strong authentication of local users is
+ required.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>polkit</para>
+ </entry>
+ <entry>
+ <para>
+ PolicyKit is an authentication scheme suitable for local
+ desktop virtualization deployments, for use only on the
+ UNIX domain socket data transport. It enables the libvirtd
+ daemon to validate that the client application is running
+ within the local X desktop session. It can be configured
+ to allow access to a logged in user automatically, or
+ prompt them to enter their own password, or the superuser
+ (root) password.
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para>x509</para>
+ </entry>
+ <entry>
+ <para>
+ Although not strictly an authentication scheme, the TLS
+ data transport can be configured to mandate the use of
+ client x509 certificates. The server can then whitelist
+ the client distinguished names to control access.
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ </section>
+ </section>
+
+ <section id="libvirt_application_development_guide_using_python-Architecture-TLS_Cert">
+ <title>Generating TLS certificates</title>
<para>
- Server checking may be enabled or disabled using the libvirtd.conf file.
+ Libvirt supports TLS certificates for verifying the identity of the server and clients.
+ There are two distinct checks involved:
</para>
- </listitem>
- </orderedlist>
+ <orderedlist>
+ <listitem>
+ <para>
+ The client checks that it is connecting to the correct server by matching the
+ certificate the server sends with the server's hostname. This check can be
+ disabled by adding <literal>?no_verify=1</literal>. Refer to
+ <xref linkend="remote_URI"/> for details.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The server checks to ensure that only allowed clients are connected. This is
+ performed using either:
+ </para>
- <para>
- For full certificate checking you will need to have certificates issued by a recognized Certificate Authority (CA) for your server(s) and all clients. To avoid the expense of obtaining certificates from a commercial CA, there is the option to set up your own CA and tell your server(s) and clients to trust certificates issues by your own CA. To do this, follow the instructions contained in the next section.
- </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ The client's IP address; or
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The client's IP address and the client's certificate.
+ </para>
+ </listitem>
+ </orderedlist>
+
+ <para>
+ Server checking may be enabled or disabled using the libvirtd.conf file.
+ </para>
+
+ </listitem>
+ </orderedlist>
- <para>
- Be aware that the default configuration for libvirtd.conf allows any client to connect, provided that they have a valid certificate issued by the CA for their own IP address. This setting may need to be made more or less permissive, dependent upon your requirements.
- </para>
+ <para>
+ For full certificate checking you will need to have certificates issued by a recognized
+ Certificate Authority (CA) for your server(s) and all clients. To avoid the expense of
+ obtaining certificates from a commercial CA, there is the option to set up your own CA
+ and tell your server(s) and clients to trust certificates issues by your own CA. To do
+ this, follow the instructions contained in the next section.
+ </para>
- <section id="libvirt_application_development_guide_using_python-Architecture-TLS_Cert-Public_Key">
- <title>Public Key Infrastructure setup</title>
-
- <table id='public_key' frame='none'><title>Public Key setup</title>
- <tgroup cols='4' align='left' colsep='1' rowsep='1'>
- <colspec colname='c1' colwidth="10%"/>
- <colspec colname='c2' colwidth="10%"/>
- <colspec colname='c3' colwidth="40%"/>
- <colspec colname='c4' colwidth="40%"/>
- <thead>
- <row>
- <entry><para><emphasis role="bold">Location</emphasis></para></entry>
- <entry><para><emphasis role="bold">Machine</emphasis></para></entry>
- <entry><para><emphasis role="bold">Description</emphasis></para></entry>
- <entry><para><emphasis role="bold">Required fields</emphasis></para></entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><para><literal>/etc/pki/CA/cacert.pem</literal></para></entry>
- <entry><para>Installed on all clients and servers</para></entry>
- <entry><para>CA's certificate</para></entry>
- <entry><para>n/a</para></entry>
- </row>
- <row>
- <entry><para><literal>/etc/pki/libvirt/private/serverkey.pem</literal></para></entry>
- <entry><para>Installed on the server</para></entry>
- <entry><para>Server's private key</para></entry>
- <entry><para>n/a</para></entry>
- </row>
- <row>
- <entry><para><literal>/etc/pki/libvirt/ servercert.pem</literal></para></entry>
- <entry><para>Installed on the server</para></entry>
- <entry><para>Server's certificate signed by the CA</para></entry>
- <entry><para>CommonName (CN) must be the hostname of the server as it is seen by clients. </para></entry>
- </row>
- <row>
- <entry><para><literal>/etc/pki/libvirt/private/clientkey.pem</literal></para></entry>
- <entry><para>Installed on the client</para></entry>
- <entry><para>Client's private key.</para></entry>
- <entry><para>n/a</para></entry>
- </row>
- <row>
- <entry><para><literal>/etc/pki/CA/cacert.pem</literal></para></entry>
- <entry><para>Installed on the client</para></entry>
- <entry><para>Client's certificate signed by the CA</para></entry>
- <entry><para>Distinguished Name (DN) can be checked against an access control list (<literal>tls_allowed_dn_list</literal>).</para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
+ <para>
+ Be aware that the default configuration for libvirtd.conf allows any client to connect,
+ provided that they have a valid certificate issued by the CA for their own IP address.
+ This setting may need to be made more or less permissive, dependent upon your requirements.
+ </para>
- </section>
+ <section id="libvirt_application_development_guide_using_python-Architecture-TLS_Cert-Public_Key">
+ <title>Public Key Infrastructure setup</title>
+
+ <table id='public_key' frame='none'><title>Public Key setup</title>
+ <tgroup cols='4' align='left' colsep='1' rowsep='1'>
+ <colspec colname='c1' colwidth="30%"/>
+ <colspec colname='c2' colwidth="15%"/>
+ <colspec colname='c3' colwidth="25%"/>
+ <colspec colname='c4' colwidth="30%"/>
+ <thead>
+ <row>
+ <entry><para><emphasis role="bold">Location</emphasis></para></entry>
+ <entry><para><emphasis role="bold">Machine</emphasis></para></entry>
+ <entry><para><emphasis role="bold">Description</emphasis></para></entry>
+ <entry><para><emphasis role="bold">Required fields</emphasis></para></entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><para><literal>/etc/pki/CA/cacert.pem</literal></para></entry>
+ <entry><para>Installed on all clients and servers</para></entry>
+ <entry><para>CA's certificate</para></entry>
+ <entry><para>n/a</para></entry>
+ </row>
+ <row>
+ <entry><para><literal>/etc/pki/libvirt/private/serverkey.pem</literal></para></entry>
+ <entry><para>Installed on the server</para></entry>
+ <entry><para>Server's private key</para></entry>
+ <entry><para>n/a</para></entry>
+ </row>
+ <row>
+ <entry><para><literal>/etc/pki/libvirt/ servercert.pem</literal></para></entry>
+ <entry><para>Installed on the server</para></entry>
+ <entry><para>Server's certificate signed by the CA</para></entry>
+ <entry><para>CommonName (CN) must be the hostname of the server as it is seen by clients. </para></entry>
+ </row>
+ <row>
+ <entry><para><literal>/etc/pki/libvirt/private/clientkey.pem</literal></para></entry>
+ <entry><para>Installed on the client</para></entry>
+ <entry><para>Client's private key.</para></entry>
+ <entry><para>n/a</para></entry>
+ </row>
+ <row>
+ <entry><para><literal>/etc/pki/CA/cacert.pem</literal></para></entry>
+ <entry><para>Installed on the client</para></entry>
+ <entry><para>Client's certificate signed by the CA</para></entry>
+ <entry><para>Distinguished Name (DN) can be checked against an access control list (<literal>tls_allowed_dn_list</literal>).</para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ </section>
- </section>
+ </section>
</chapter>
diff --git a/en-US/Introduction.xml b/en-US/Introduction.xml
index 440f7bc..a1c06b1 100644
--- a/en-US/Introduction.xml
+++ b/en-US/Introduction.xml
@@ -4,129 +4,128 @@
%BOOK_ENTITIES;
]>
<chapter id="libvirt_application_development_guide_using_python-Introduction">
- <title>Introduction</title>
+ <title>Introduction</title>
- <para>
- Libvirt is a hypervisor-independent virtualization API and toolkit that is
- able to interact with the virtualization capabilities of a range of operating
- systems. It is free software under the GNU Lesser General Public License.
- </para>
-
- <para>
- This chapter provides an introduction to libvirt and defines common terms
- that will be used throughout the guide.
- </para>
-
- <section id="libvirt_application_development_guide_using_python-Introduction-Overview">
- <title>Overview</title>
<para>
- Libvirt provides a common, generic and stable layer to securely manage
- domains on a node. As nodes may be remotely located, libvirt provides
- all APIs required to provision, create, modify, monitor, control, migrate
- and stop the domains, within the limits of hypervisor support for these
- operations. Although multiple nodes may be accessed with libvirt
- simultaneously, the APIs are limited to single node operations.
+ Libvirt is a hypervisor-independent virtualization API and toolkit that is
+ able to interact with the virtualization capabilities of a range of operating
+ systems. It is free software under the GNU Lesser General Public License.
</para>
<para>
- Libvirt is designed to work across multiple virtualization environments,
- which means that more common capabilities are provided as APIs. Due to
- this, certain specific capabilities may not be provided. For example,
- it does not provide high level virtualization policies or multi-node
- management features such as load balancing. However, API stability
- ensures that these features can be implemented on top of libvirt. To
- maintain this level of stability, libvirt seeks to isolate applications
- from the frequent changes expected at the lower level of the virtualization
- framework.
+ This chapter provides an introduction to libvirt and defines common terms
+ that will be used throughout the guide.
</para>
- <para>
- Libvirt is intended as a building block for higher level management tools
- and applications focusing on virtualization of a single node, with the
- only exception being domain migration between multiple node capabilities.
- It provides APIs to enumerate, monitor and use the resources available
- on the managed node, including CPUs, memory, storage, networking and
- Non-Uniform Memory Access (NUMA) partitions. Although a management node
- can be located on a separate physical machine to the management program,
- this should only be done using secure protocols.
- </para>
+ <section id="libvirt_application_development_guide_using_python-Introduction-Overview">
+ <title>Overview</title>
+ <para>
+ Libvirt provides a common, generic and stable layer to securely manage
+ domains on a node. As nodes may be remotely located, libvirt provides
+ all APIs required to provision, create, modify, monitor, control, migrate
+ and stop the domains, within the limits of hypervisor support for these
+ operations. Although multiple nodes may be accessed with libvirt
+ simultaneously, the APIs are limited to single node operations.
+ </para>
- </section>
+ <para>
+ Libvirt is designed to work across multiple virtualization environments,
+ which means that more common capabilities are provided as APIs. Due to
+ this, certain specific capabilities may not be provided. For example,
+ it does not provide high level virtualization policies or multi-node
+ management features such as load balancing. However, API stability
+ ensures that these features can be implemented on top of libvirt. To
+ maintain this level of stability, libvirt seeks to isolate applications
+ from the frequent changes expected at the lower level of the virtualization
+ framework.
+ </para>
- <section id="libvirt_application_development_guide_using_python-Introduction-Glossary">
- <title>Glossary of terms</title>
+ <para>
+ Libvirt is intended as a building block for higher level management tools
+ and applications focusing on virtualization of a single node, with the
+ only exception being domain migration between multiple node capabilities.
+ It provides APIs to enumerate, monitor and use the resources available
+ on the managed node, including CPUs, memory, storage, networking and
+ Non-Uniform Memory Access (NUMA) partitions. Although a management node
+ can be located on a separate physical machine to the management program,
+ this should only be done using secure protocols.
+ </para>
- <para>
- To avoid ambiguity regarding terms and concepts used in this guide,
- refer to the following table for their definitions.
- </para>
+ </section>
+
+ <section id="libvirt_application_development_guide_using_python-Introduction-Glossary">
+ <title>Glossary of terms</title>
- <table id='terms' frame='none'><title>Terminology</title>
- <tgroup cols='2' align='left' colsep='1' rowsep='1'>
- <colspec colname='c1' colwidth="20%"/>
- <colspec colname='c2' colwidth="80%"/>
- <thead>
- <row>
- <entry><para><emphasis role="bold">Term</emphasis></para></entry>
- <entry><para><emphasis role="bold">Definition</emphasis></para></entry>
+ <para>
+ To avoid ambiguity regarding terms and concepts used in this guide,
+ refer to the following table for their definitions.
+ </para>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><para><application>Domain</application></para></entry>
- <entry>
- <para>
- An instance of an operating system (or subsystem in the case of
- container virtualization) running on a virtualized machine provided
- by the hypervisor.
- </para>
- </entry>
- </row>
- <row>
- <entry><para><application>Hypervisor</application></para></entry>
- <entry>
- <para>
- A layer of software allowing virtualization of a node in a set
- of virtual machines, which may have different configurations to the
- node itself.
- </para>
- </entry>
- </row>
- <row>
- <entry><para><application>Node</application></para></entry>
- <entry>
- <para>
- A single physical server. Nodes may be any one of many
- different types, and are commonly referred to by their primary
- purpose. Examples are storage nodes, cluster nodes, and database
- nodes.
- </para>
- </entry>
- </row>
- <row>
- <entry><para><application>Storage Pool</application></para></entry>
- <entry>
- <para>
- A collection of storage media, such as physical hard drives. A
- Storage Pool is sub-divided into smaller containers called
- Volumes, which may then be allocated to one or more Domains.
- </para>
- </entry>
- </row>
- <row>
- <entry><para><application>Volume</application></para></entry>
- <entry>
- <para>
- A storage space, allocated from a Storage Pool. A Volume may
- be assigned to one or more Domains for use, and are commonly
- used inside Domains as virtual hard drives.
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
+ <table id='terms' frame='none'><title>Terminology</title>
+ <tgroup cols='2' align='left' colsep='1' rowsep='1'>
+ <colspec colname='c1' colwidth="20%"/>
+ <colspec colname='c2' colwidth="80%"/>
+ <thead>
+ <row>
+ <entry><para><emphasis role="bold">Term</emphasis></para></entry>
+ <entry><para><emphasis role="bold">Definition</emphasis></para></entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><para><application>Domain</application></para></entry>
+ <entry>
+ <para>
+ An instance of an operating system (or subsystem in the case of
+ container virtualization) running on a virtualized machine provided
+ by the hypervisor.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry><para><application>Hypervisor</application></para></entry>
+ <entry>
+ <para>
+ A layer of software allowing virtualization of a node in a set
+ of virtual machines, which may have different configurations to the
+ node itself.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry><para><application>Node</application></para></entry>
+ <entry>
+ <para>
+ A single physical server. Nodes may be any one of many
+ different types, and are commonly referred to by their primary
+ purpose. Examples are storage nodes, cluster nodes, and database
+ nodes.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry><para><application>Storage Pool</application></para></entry>
+ <entry>
+ <para>
+ A collection of storage media, such as physical hard drives. A
+ Storage Pool is sub-divided into smaller containers called
+ Volumes, which may then be allocated to one or more Domains.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry><para><application>Volume</application></para></entry>
+ <entry>
+ <para>
+ A storage space, allocated from a Storage Pool. A Volume may
+ be assigned to one or more Domains for use, and are commonly
+ used inside Domains as virtual hard drives.
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
</chapter>