commit f10e419ae3c238172661aa66ee821cda73757dc8
Author: W. David Ashley <w.david.ashley(a)gmail.com>
Date: Mon Jun 29 21:33:01 2015 -0500
Updated the Guest Domains chapter
- Updated the Provisioning and Starting section for Python.
- Added the Guest Domains Example 7 Provisioning and Starting (Python code).
en-US/Guest_Domains.xml | 319 +++++++++++++++++++------------------
en-US/extras/Domains-Example-7.py | 21 +++
2 files changed, 182 insertions(+), 158 deletions(-)
---
diff --git a/en-US/Guest_Domains.xml b/en-US/Guest_Domains.xml
index 6f822b7..943667d 100644
--- a/en-US/Guest_Domains.xml
+++ b/en-US/Guest_Domains.xml
@@ -3,10 +3,10 @@
<!ENTITY % BOOK_ENTITIES SYSTEM
"Libvirt_Application_Development_Guide_Using_Python.ent">
%BOOK_ENTITIES;
]>
- <chapter
id="libvirt_application_development_guide_using_python-Guest_Domains">
+<chapter
id="libvirt_application_development_guide_using_python-Guest_Domains">
<title>Guest Domains</title>
- <section
id="libvirt_application_development_guide_using_python-Guest_Domains-Overview">
- <title>Domain overview</title>
+ <section
id="libvirt_application_development_guide_using_python-Guest_Domains-Domain_Overview">
+ <title>Domain Overview</title>
<para>
A domain is an instance of an operating system running on a virtualized
machine.
@@ -97,8 +97,8 @@
</para>
</section>
- <section
id="libvirt_application_development_guide_using_python-Guest_Domains-Listing">
- <title>Listing domains</title>
+ <section
id="libvirt_application_development_guide_using_python-Guest_Domains-Listing_Domains">
+ <title>Listing Domains</title>
<para>
The libvirt cklasses expose two lists of domains, the first
@@ -143,7 +143,7 @@
</example>
<para>
- The APIs for listing domains do not directly return the
+ 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
to query the list of domains on a frequent basis. However,
@@ -160,165 +160,168 @@
</example>
</section>
- <section
id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle">
- <title>Lifecycle control</title>
+ <section
id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle_Control">
+ <title>Lifecycle Control</title>
- <para>
- libvirt can control the entire lifecycle of guest domains. Guest domains can
transition through several states throughout their lifecycle:
- </para>
- <orderedlist>
- <listitem>
- <para>
- <literal>Undefined</literal>. This is the baseline state. An
undefined guest domain has not been defined or created in any way.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>Defined</literal>. A defined guest domain has been
defined but is not running. This state could also be described as
<literal>Stopped</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>Running</literal>. A running guest domain is defined and
being executed on a hypervisor.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>Paused</literal>. A paused guest domain is in a
suspended state from the <literal>Running</literal> state. Its memory image
has been temporarily stored, and it can be resumed to the
<literal>Running</literal> state without the guest domain operating system
being aware it was ever suspended.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>Saved</literal>. A saved domain has had its memory
image, as captured in the <literal>Paused</literal> state, saved to persistent
storage. It can be restored to the <literal>Running</literal> state without
the guest domain operating system being aware it was ever suspended.
- </para>
- </listitem>
- </orderedlist>
- <para>
- The transitions between these states fall into several categories: <xref
linkend="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Provisioning"
/>, <xref
linkend="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Save"
/>, <xref
linkend="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Migration"
/> and <xref
linkend="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Autostart"
/>.
- </para>
- <figure id="guest_domain_state_transition">
- <title>Guest domain lifecycle</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/guest-state-transition.png"
format="PNG" />
- </imageobject>
- </mediaobject>
- </figure>
-
- <section
id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Provisioning">
- <title>Provisioning and starting</title>
-
- <para>
- Provisioning refers to the task of creating new guest domains,
- typically using some form of operating system installation
- media. There are a wide variety of ways in which a guest can
- be provisioned, but the choices available will vary according
- to the hypervisor and type of guest domain being provisioned.
- It is not uncommon for an application to support several
- different provisioning methods. Starting refers to executing a provisioned
guest domain on a hypervisor.
- </para>
-
- <section
id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Provisioning-apis">
- <title>APIs for provisioning</title>
+ <para>
+ Libvirt can control the entire lifecycle of guest domains. Guest domains can
transition through
+ several states throughout their lifecycle:
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ <literal>Undefined</literal>. This is the baseline state.
An undefined guest domain
+ has not been defined or created in any way.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+
+ <literal>Defined</literal>. A defined guest domain has
been defined but is not running.
+ This state could also be described as
<literal>Stopped</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>Running</literal>. A running guest domain is
defined and being executed on a
+ hypervisor.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>Paused</literal>. A paused guest domain is in a
suspended state from the
+ <literal>Running</literal> state. Its memory image has
been temporarily stored, and
+ it can be resumed to the <literal>Running</literal> state
without the guest domain
+ operating system being aware it was ever suspended.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>Saved</literal>. A saved domain has had its
memory image, as captured in
+ the <literal>Paused</literal> state, saved to persistent
storage. It can be restored
+ to the <literal>Running</literal> state without the guest
domain operating system
+ being aware it was ever suspended.
+ </para>
+ </listitem>
+ </orderedlist>
+ <para>
+ The transitions between these states fall into several categories:
+ <xref
linkend="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Provisioning_and_Starting"
/>,
+ <xref
linkend="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Save"
/>,
+ <xref
linkend="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Migration"
/>
+ and <xref
linkend="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Autostart"
/>.
+ </para>
+ <figure id="guest_domain_state_transition">
+ <title>Guest domain lifecycle</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/guest-state-transition.png"
format="PNG" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <section
id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Provisioning_and_Starting">
+ <title>Provisioning and Starting</title>
<para>
- There are up to three APIs involved in provisioning guests.
- The <literal>virDomainCreateXML</literal> command will create
- and immediately boot a new transient guest domain. When this
- guest domain shuts down, all trace of it will disappear. The
- <literal>virDomainDefineXML</literal> command will store the
- configuration for a persistent guest domain. The
<literal>virDomainCreate</literal>
- command will boot a previously defined guest domain
- from its persistent configuration. One important thing to
- note, is that the <literal>virDomainDefineXML</literal>
command
- can be used to turn a previously booted transient guest domain,
- into a persistent domain. This can be useful for some provisioning
- scenarios that will be illustrated later.
+ Provisioning refers to the task of creating new guest domains,
+ typically using some form of operating system installation
+ media. There are a wide variety of ways in which a guest can
+ be provisioned, but the choices available will vary according
+ to the hypervisor and type of guest domain being provisioned.
+ It is not uncommon for an application to support several
+ different provisioning methods. Starting refers to executing a
provisioned
+ guest domain on a hypervisor.
</para>
- <section
id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Provisioning-apis-transient">
- <title>Booting a transient guest domain</title>
+ <section
id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Provisioning-Methods_For_Provisioning">
+ <title>Methods For Provisioning</title>
- <para>
- To boot a transient guest domain, simply requires a connection to
- libvirt and a string containing the XML document describing the
- required guest configuration. The following example assumes that
- <literal>conn</literal> is an instance of the
<literal>virConnectPtr</literal>
- object.
- </para>
-
- <programlisting>
- <![CDATA[
- virDomainPtr dom;
- const char *xmlconfig = "<domain>........</domain>";
-
- dom = virConnectCreateXML(conn, xmlconfig, 0);
-
- if (!dom) {
- fprintf(stderr, "Domain creation failed");
- return;
- }
-
- fprintf(stderr, "Guest %s has booted", virDomainName(dom));
- virDomainFree(dom);
- ]]>
- </programlisting>
-
- <para>
- If the domain creation attempt succeeded, then the returned
- <literal>virDomainPtr</literal> will be a handle to the
guest
- domain. This must be released later when no longer needed by
- using the <literal>virDomainFree</literal> method. Although
- the domain was booted successfully, this does not guarantee
- that the domain is still running. It is entirely possible for
- the guest domain to crash, in which case attempts to use the
- returned <literal>virDomainPtr</literal> object will
generate
- an error, since transient guests cease to exist when they
- shutdown (whether a planned shutdown, or a crash). To cope
- with this scenario requires use of a persistent guest.
- </para>
-
- </section>
-
- <section
id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Provisioning-apis-persistent">
- <title>Defining and booting a persistent guest domain</title>
-
- <para>
- Before a persistent domain can be booted, it must have its configuration
- defined. This again requires a connection to libvirt and a string
containing
- the XML document describing the required guest configuration. The
- <literal>virDomainPtr</literal> object obtained from defining
the guest,
- can then be used to boot it. The following example assumes that
- <literal>conn</literal> is an instance of the
<literal>virConnectPtr</literal>
- object.
- </para>
-
- <programlisting>
- <![CDATA[
- virDomainPtr dom;
- const char *xmlconfig = "<domain>........</domain>";
-
- dom = virConnectDefineXML(conn, xmlconfig, 0);
-
- if (!dom) {
- fprintf(stderr, "Domain definition failed");
- return;
- }
+ <para>
+ There are up to three APIs involved in provisioning guests.
+ The <literal>virDomainCreateXML</literal> command will
create
+ and immediately boot a new transient guest domain. When this
+ guest domain shuts down, all trace of it will disappear. The
+ <literal>virDomainDefineXML</literal> command will store
the
+ configuration for a persistent guest domain. The
<literal>virDomainCreate</literal>
+ command will boot a previously defined guest domain
+ from its persistent configuration. One important thing to
+ note, is that the <literal>virDomainDefineXML</literal>
command
+ can be used to turn a previously booted transient guest domain,
+ into a persistent domain. This can be useful for some provisioning
+ scenarios that will be illustrated later.
+ </para>
- if (virDomainCreate(dom) < 0) {
+ <section
id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Provisioning-apis-Booting_Transient_Domain">
+ <title>Booting a Transient Guest Domain</title>
+
+ <para>
+ To boot a transient guest domain, simply requires a connection
to
+ libvirt and a string containing the XML document describing the
+ required guest configuration. The following example assumes that
+ <literal>conn</literal> is an instance of the
<literal>virConnectPtr</literal>
+ object.
+ </para>
+
+ <example>
+ <title>Prvisioning a Transient Guest Domain</title>
+ <programlisting language="Python"><xi:include
href="extras/Domains-Example-1.py" parse="text"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </example>
+
+ <para>
+ If the domain creation attempt succeeded, then the returned
+ <literal>virDomain</literal> instance will be returned,
otherwise
+ <literal>None</literal> will be returned. Although
+ the domain was booted successfully, this does not guarantee
+ that the domain is still running. It is entirely possible for
+ the guest domain to crash, in which case attempts to use the
+ returned <literal>virDomain</literal> object will
generate
+ an error, since transient guests cease to exist when they
+ shutdown (whether a planned shutdown, or a crash). To cope
+ with this scenario requires use of a persistent guest.
+ </para>
+
+ </section>
+
+ <section
id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Provisioning-apis-persistent">
+ <title>Defining and booting a persistent guest
domain</title>
+
+ <para>
+ Before a persistent domain can be booted, it must have its
configuration
+ defined. This again requires a connection to libvirt and a string
containing
+ the XML document describing the required guest configuration. The
+ <literal>virDomainPtr</literal> object obtained from
defining the guest,
+ can then be used to boot it. The following example assumes that
+ <literal>conn</literal> is an instance of the
<literal>virConnectPtr</literal>
+ object.
+ </para>
+
+ <programlisting>
+ <![CDATA[
+ virDomainPtr dom;
+ const char *xmlconfig = "<domain>........</domain>";
+
+ dom = virConnectDefineXML(conn, xmlconfig, 0);
+
+ if (!dom) {
+ fprintf(stderr, "Domain definition failed");
+ return;
+ }
+
+ if (virDomainCreate(dom) < 0) {
+ virDomainFree(dom);
+ fprintf(stderr, "Cannot boot guest");
+ return;
+ }
+
+ fprintf(stderr, "Guest %s has booted", virDomainName(dom));
virDomainFree(dom);
- fprintf(stderr, "Cannot boot guest");
- return;
- }
+ ]]>
+ </programlisting>
- fprintf(stderr, "Guest %s has booted", virDomainName(dom));
- virDomainFree(dom);
- ]]>
- </programlisting>
-
- </section>
+ </section>
- </section>
+ </section>
<section
id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Provisioning-config">
<title>New guest provisioning techniques</title>
diff --git a/en-US/extras/Domains-Example-7.py b/en-US/extras/Domains-Example-7.py
new file mode 100644
index 0000000..41e95ba
--- /dev/null
+++ b/en-US/extras/Domains-Example-7.py
@@ -0,0 +1,21 @@
+# Example-7.py
+from __future__ import print_function
+import sys
+import libvirt
+
+xmlconfig = '<domain>........</domain>'
+
+conn = libvirt.open('qemu:///system')
+if conn == None:
+ print('Failed to open connection to qemu:///system', file=sys.stderr)
+ exit(1)
+
+dom = conn.createXML(xmlconfig, 0)
+if dom == None:
+ print('Failed to create a domain from an XML definition.', file=sys.stderr)
+ exit(1)
+
+print('Guest '+dom.name()+' has booted', file=sys.stderr)
+
+conn.close()
+exit(0)