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>