commit 80c7b2c4c5482c32047982b49ef2f5ee61c43bc2
Author: W. David Ashley <w.david.ashley(a)gmail.com>
Date: Wed Jul 8 13:55:21 2015 -0500
Domains Chapter
- started indexing this chapter
- some minor edits on method names
en-US/Guest_Domains.xml | 104 +++++++++++++++++++++++++++++++++++++++++-----
1 files changed, 92 insertions(+), 12 deletions(-)
---
diff --git a/en-US/Guest_Domains.xml b/en-US/Guest_Domains.xml
index 5e7130a..822b91c 100644
--- a/en-US/Guest_Domains.xml
+++ b/en-US/Guest_Domains.xml
@@ -5,6 +5,8 @@
]>
<chapter
id="libvirt_application_development_guide_using_python-Guest_Domains">
<title>Guest Domains</title>
+ <indexterm><primary>Guest domains</primary></indexterm>
+ <indexterm><primary>Domains</primary></indexterm>
<section
id="libvirt_application_development_guide_using_python-Guest_Domains-Domain_Overview">
<title>Domain Overview</title>
@@ -64,6 +66,15 @@
</para>
<para>
+ <indexterm><primary>lookupByName,
Domains</primary></indexterm>
+ <indexterm><primary>Domains</primary>
+ <secondary>lookupByName</secondary></indexterm>
+ <indexterm><primary>lookupByID,
Domains</primary></indexterm>
+ <indexterm><primary>Domains</primary>
+ <secondary>lookupByID</secondary></indexterm>
+ <indexterm><primary>lookupByUUID,
Domains</primary></indexterm>
+ <indexterm><primary>Domains</primary>
+ <secondary>lookupByUUID</secondary></indexterm>
Once an application has a unique identifier for a domain, it will
often want to obtain the corresponding
<literal>virDomain</literal>
object. There are three, imaginatively named, methods to do lookup
@@ -99,6 +110,9 @@
<section
id="libvirt_application_development_guide_using_python-Guest_Domains-Listing_Domains">
<title>Listing Domains</title>
+ <indexterm><primary>listing
Domains</primary></indexterm>
+ <indexterm><primary>Domains</primary>
+ <secondary>listing</secondary></indexterm>
<para>
The libvirt classes expose two lists of domains, the first
@@ -112,6 +126,9 @@
</para>
<para>
+
<indexterm><primary>listDomainsID</primary></indexterm>
+ <indexterm><primary>Domains</primary>
+ <secondary>listDomainsID</secondary></indexterm>
The method for listing active domains, returns a list of domain
IDs. Every running domain has a positive integer ID, uniquely
identifying it amongst all running domains on the host. The
@@ -129,6 +146,9 @@
<para>
+
<indexterm><primary>listDefinedDomains</primary></indexterm>
+ <indexterm><primary>Domains</primary>
+ <secondary>listDefinedDmamins</secondary></indexterm>
In addition to the running domains, there may be some persistent
inactive domain configurations stored on the host. Since an inactive
domain does not have any ID identifier, the listing of inactive
@@ -143,6 +163,9 @@
</example>
<para>
+
<indexterm><primary>lisAllDomains</primary></indexterm>
+ <indexterm><primary>Domains</primary>
+ <secondary>listAllDmamins</secondary></indexterm>
The methods for listing domains do not directly return the
<literal>virDomain</literal> objects, since this may
incur undue performance penalty for applications which wish
@@ -162,6 +185,9 @@
<section
id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle_Control">
<title>Lifecycle Control</title>
+ <indexterm><primary>Lifecycle,
Domains</primary></indexterm>
+ <indexterm><primary>Domains</primary>
+ <secondary>Lifecycle</secondary></indexterm>
<para>
Libvirt can control the entire lifecycle of guest domains. Guest domains can
transition through
@@ -222,6 +248,9 @@
<section
id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Provisioning_and_Starting">
<title>Provisioning and Starting</title>
+ <indexterm><primary>Provisioning and Starting,
Domains</primary></indexterm>
+ <indexterm><primary>Domains</primary>
+ <secondary>Provisioning and
starting</secondary></indexterm>
<para>
Provisioning refers to the task of creating new guest domains,
@@ -238,6 +267,12 @@
<title>Methods For Provisioning</title>
<para>
+
<indexterm><primary>createXML</primary></indexterm>
+ <indexterm><primary>Domains</primary>
+ <secondary>createXML</secondary></indexterm>
+
<indexterm><primary>defineXML</primary></indexterm>
+ <indexterm><primary>Domains</primary>
+ <secondary>defineXML</secondary></indexterm>
There are up to three methods involved in provisioning guests.
The <literal>createXML</literal> method will create
and immediately boot a new transient guest domain. When this
@@ -319,6 +354,9 @@
<section
id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Provisioning-Provisioning_Techniques">
<title>New Guest Domain Provisioning Techniques</title>
+ <indexterm><primary>New guest domain
provisioning</primary></indexterm>
+ <indexterm><primary>Guest domain provisioning,
New</primary></indexterm>
+ <indexterm><primary>Domain provisioning, New
guest</primary></indexterm>
<para>
This section will first illustrate two configurations that
@@ -344,6 +382,8 @@
<section
id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Provisioning-ISO">
<title>CDROM/ISO image provisioning</title>
+ <indexterm><primary>CDROM/ISO image
provisioning</primary></indexterm>
+ <indexterm><primary>ISO/CDROM image
provisioning</primary></indexterm>
<para>
All full virtualization technologies have support for emulating
@@ -409,6 +449,7 @@
<section
id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Provisioning-PXE">
<title>PXE Boot Provisioning</title>
+ <indexterm><primary>PXE boot
provisioning</primary></indexterm>
<para>
Some newer full virtualization technologies provide a BIOS that
@@ -466,6 +507,7 @@
<section
id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Provisioning-Kernel">
<title>Direct Kernel Boot Provisioning</title>
+ <indexterm><primary>Kernel boot
provisioning</primary></indexterm>
<para>
Paravirtualization technologies emulate a fairly restrictive
@@ -559,6 +601,8 @@
<section
id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Stopping">
<title>Stopping</title>
+ <indexterm><primary>Stopping a
domain</primary></indexterm>
+ <indexterm><primary>Domain, stopping
a</primary></indexterm>
<para>
Stopping refers to the process of halting a running guest. A guest can be
stopped by two methods:
shutdown and destroy.
@@ -578,14 +622,30 @@
<section
id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Save">
<title>Suspend / Resume and Save / Restore</title>
+ <indexterm><primary>Suspend a
domain</primary></indexterm>
+ <indexterm><primary>Resume a
domain</primary></indexterm>
+ <indexterm><primary>Save a
domain</primary></indexterm>
+ <indexterm><primary>Restore a
domain</primary></indexterm>
<para>
+
<indexterm><primary>suspend</primary></indexterm>
+ <indexterm><primary>Domains</primary>
+ <secondary>suspend</secondary></indexterm>
+ <indexterm><primary>resume</primary></indexterm>
+ <indexterm><primary>Domains</primary>
+ <secondary>resume</secondary></indexterm>
the <literal>suspend</literal> and
<literal>resume</literal> methods refer to the process of taking a running
guest and
temporarily saving its memory state. At a later time, it is possible to
resume the guest
to its original running state, contiuining execution where it left off.
Suspend does not
save a persistent image of the guest's memory. For this,
<literal>save</literal> is used.
</para>
<para>
+ <indexterm><primary>save</primary></indexterm>
+ <indexterm><primary>Domains</primary>
+ <secondary>save</secondary></indexterm>
+
<indexterm><primary>restore</primary></indexterm>
+ <indexterm><primary>Domains</primary>
+ <secondary>restore</secondary></indexterm>
The <literal>save</literal> and
<literal>restore</literal> methods refer to the process of taking a running
guest
and saving its memory state to a file. At some time later, it
is possible to restore the guest to its original running state,
@@ -645,8 +705,15 @@
<section
id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Migration">
<title>Migration</title>
+ <indexterm><primary>Migration,
domain</primary></indexterm>
<para>
+
<indexterm><primary>migrate</primary></indexterm>
+ <indexterm><primary>Domains</primary>
+ <secondary>migrate</secondary></indexterm>
+
<indexterm><primary>migrateToURI</primary></indexterm>
+ <indexterm><primary>Domains</primary>
+ <secondary>migrateToURI</secondary></indexterm>
Migration is the process of taking the image of a guest domain and moving
it somewhere,
typically from a hypervisor on one node to a hypervisor on another node.
There are two
methods for migration. The <literal>migrate</literal> method
takes an established
@@ -717,8 +784,12 @@
<section
id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Autostart">
<title>Autostart</title>
+ <indexterm><primary>Autostart</primary></indexterm>
<para>
+
<indexterm><primary>setAutostart</primary></indexterm>
+ <indexterm><primary>Domains</primary>
+ <secondary>setAutostart</secondary></indexterm>
A guest domain can be configured to autostart on a particular hypervisor,
either by the
hypervisor itself or libvirt. In combination with managed save, this
allows the operating
system on a guest domain to withstand host reboots without ever
considering itself to have
@@ -736,6 +807,8 @@
<section
id="libvirt_application_development_guide_using_python-Guest_Domains-Domain_Config">
<title>Domain Configuration</title>
+ <indexterm><primary>Domain
configuration</primary></indexterm>
+ <indexterm><primary>Configuration,
domain</primary></indexterm>
<para>
Domains are defined in libvirt using XML. Everything related only to the
domain, such as
@@ -929,6 +1002,7 @@
<section
id="libvirt_application_development_guide_using_python-Guest_Domains-Device_Config-PCI_Pass">
<title>PCI device passthrough</title>
+ <indexterm><primary>PCI device
passthrough</primary></indexterm>
<para>
The PCI device passthrough capability allows a physical PCI device
from
@@ -1071,12 +1145,16 @@
<section
id="libvirt_application_development_guide_using_python-Guest_Domains-Live_Config-Block_Jobs">
<title>Block Device Jobs</title>
+ <indexterm><primary>Block device
jobs</primary></indexterm>
<para>
+
<indexterm><primary>blockPull</primary></indexterm>
+ <indexterm><primary>Domains</primary>
+ <secondary>blockPull</secondary></indexterm>
Libvirt provides a generic Block Job API that can be used to initiate
and manage operations on disks that belong to a domain. Jobs are
started by calling the function associated with the desired operation
- (eg. <literal>virDomainBlockPull</literal>). Once started,
all block
+ (eg. <literal>blockPull</literal>). Once started, all
block
jobs are managed in the same manner. They can be aborted, throttled,
and queried. Upon completion, an asynchronous event is issued to
indicate the final status.
@@ -1088,9 +1166,9 @@
<orderedlist>
<listitem>
<para>
- <literal>virDomainBlockPull()</literal> starts a
block pull
+ <literal>blockPull()</literal> starts a block pull
operation for the specified disk. This operation is valid only
for
- specially configured disks. BlockPull will populate a disk
image
+ specially configured disks.
<literal>blockPull</literal> will populate a disk image
with data from its backing image. Once all data from its
backing
image has been pulled, the disk no longer depends on a backing
image.
@@ -1099,30 +1177,32 @@
</orderedlist>
<para>
+
<indexterm><primary>blockJobInfo</primary></indexterm>
+ <indexterm><primary>Domains</primary>
+ <secondary>blockJobInfo</secondary></indexterm>
A disk can be queried for active block jobs by using
- <literal>virDomainGetBlockJobInfo()</literal>. If found,
job
+ <literal>blockJobInfo</literal>. If found, job
information is reported in a structure that contains: the job type,
bandwidth throttling setting, and progress information.
</para>
<para>
+
<indexterm><primary>blockJobAbort</primary></indexterm>
+ <indexterm><primary>Domains</primary>
+ <secondary>blockJobAbort</secondary></indexterm>
<literal>virDomainBlockJobAbort()</literal> can be used to
cancel the
active block job on the specified disk.
</para>
<para>
- Use <literal>virDomainBlockJobSetSpeed()</literal> to limit
the amount
+
<indexterm><primary>blockJobSetSpeed</primary></indexterm>
+ <indexterm><primary>Domains</primary>
+ <secondary>blockJobSetSpeed</secondary></indexterm>
+ Use <literal>blockJobSetSpeed()</literal> to limit the
amount
of bandwidth that a block job may consume. Bandwidth is specified in
units of MB/sec.
</para>
- <para>
- When a block job operation completes, the final status is reported using
- an asynchronous event. To receive this event, register a
- <literal>virConnectDomainEventBlockJobCallback</literal>
function which
- will receive the disk, event type, and status as parameters.
- </para>
-
<programlisting>
<![CDATA[/* example blockpull-example.c */
/* compile with: gcc -g -Wall blockpull-example.c -o blockpull-example -lvirt */