commit d8457b42bd22b0c750d4c2019107e734a70a1662
Author: W. David Ashley <w.david.ashley(a)gmail.com>
Date: Fri Jul 3 19:02:30 2015 -0500
Domain Chapter
Stopping section
- Finished converting to Python
Suspend/Resume and Save/Restore section
- Finished converting to Python
- added examples 20 and 21
General
- fixed some errors on specifying the language in examples
en-US/Guest_Domains.xml | 155 ++++++++++++++---------------------
en-US/extras/Domains-Example-20.py | 33 ++++++++
en-US/extras/Domains-Example-21.py | 25 ++++++
3 files changed, 120 insertions(+), 93 deletions(-)
---
diff --git a/en-US/Guest_Domains.xml b/en-US/Guest_Domains.xml
index a841cf2..808cdec 100644
--- a/en-US/Guest_Domains.xml
+++ b/en-US/Guest_Domains.xml
@@ -488,7 +488,7 @@
<example>
<title>Kernel Boot Provisioning XML</title>
- <programlisting language="Python"><xi:include
href="extras/Domains-Example-15.xml" parse="text"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ <programlisting language="XML"><xi:include
href="extras/Domains-Example-15.xml" parse="text"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
</example>
<para>
@@ -535,13 +535,13 @@
would thus look like:
</para>
- <programlisting language="Python"><xi:include
href="extras/Domains-Example-17.xml" parse="text"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ <programlisting language="XML"><xi:include
href="extras/Domains-Example-17.xml" parse="text"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
<para>
while a fully-virtualized guest would use:
</para>
- <programlisting language="Python"><xi:include
href="extras/Domains-Example-18.xml" parse="text"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ <programlisting language="XML"><xi:include
href="extras/Domains-Example-18.xml" parse="text"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
<para>
With the second phase configuration determined, the guest can
@@ -557,122 +557,91 @@
</section>
</section>
- <section
id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Stopping">
+ <section
id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Stopping">
<title>Stopping</title>
<para>
- Stopping refers to the process of halting a running guest. A guest can be
stopped by two methods: shutdown and destroy.
+ Stopping refers to the process of halting a running guest. A guest can be
stopped by two methods:
+ shutdown and destroy.
</para>
<para>
- Shutdown is a clean stop process, which sends a signal to the guest domain
operating system asking it to shut down immediately. The guest will only be stopped once
the operating system has successfuly shut down. The shutdown process is analagous to
running a shutdown command on a physical machine.
+ The <literal>shutdown</literal> method is a clean stop process,
which sends a signal to the guest domain operating system
+ asking it to shut down immediately. The guest will only be stopped once the
operating system
+ has successfuly shut down. The shutdown process is analagous to running a
shutdown command on
+ a physical machine. There is also a
<literal>shutdownFlags</literal> method which can, depending
+ on what the guest OS supports, can shudoown the domain and leave the objct in
a usable state.
</para>
<para>
- Destroy immediately terminates the guest domain. The destroy process is
analogous to pulling the plug on a physical machine.
+ The <literal>destroy</literal> method immediately terminates the
guest domain. The destroy process is analogous to pulling
+ the plug on a physical machine.
</para>
- </section>
+ </section>
- <section
id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Save">
+ <section
id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Save">
<title>Suspend / Resume and Save / Restore</title>
<para>
- Suspend and resume refers 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, save is used.
+ 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>
- Save and restore refers 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,
- continuing execution where it left off.
+ 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,
+ continuing execution where it left off.
</para>
<para>
- It is important to note that the save/restore APIs only save the
- memory state, no storage state is preserved. Thus when the guest
- is restored, the underlying guest storage must be in exactly the
- same state as it was when the guest was initially saved. For
- basic usage this implies that a guest can only be restored once
- from any given saved state image. To allow a guest to be restored
- from the same saved state multiple times, the application must
- also have taken a snapshot of the guest storage at time of saving,
- and explicitly revert to this storage snapshot when restoring.
- A future API enhancement in libvirt will allow for an automated
- snapshot capability which saves memory and storage state in
- one operation.
+ It is important to note that the save/restore methods only save the
+ memory state, no storage state is preserved. Thus when the guest
+ is restored, the underlying guest storage must be in exactly the
+ same state as it was when the guest was initially saved. For
+ basic usage this implies that a guest can only be restored once
+ from any given saved state image. To allow a guest to be restored
+ from the same saved state multiple times, the application must
+ also have taken a snapshot of the guest storage at time of saving,
+ and explicitly revert to this storage snapshot when restoring.
+ A future enhancement in libvirt will allow for an automated
+ snapshot capability which saves memory and storage state in
+ one operation.
</para>
<para>
- The save operation requires the fully qualified path to a file
- in which the guest memory state will be saved. This filename
- is in the hypervisor's file system, not the libvirt client
- application's. There's no difference between the two if managing
- a local hypervisor, but it is critically important if connecting
- remotely to a hypervisor across the network. The example that
- follows demonstrates saving a guest called 'demo-guest' to a
- file. It checks to verify that the guest is running before
- saving, though this is technically redundant since the
- hypervisor driver will do such a check itself.
+ The save operation requires the fully qualified path to a file
+ in which the guest memory state will be saved. This filename
+ is in the hypervisor's file system, not the libvirt client
+ application's. There's no difference between the two if managing
+ a local hypervisor, but it is critically important if connecting
+ remotely to a hypervisor across the network. The example that
+ follows demonstrates saving a guest called 'demo-guest' to a
+ file. It checks to verify that the guest is running before
+ saving, though this is technically redundant since the
+ hypervisor driver will do such a check itself.
</para>
- <programlisting>
- <![CDATA[
- virDomainPtr dom;
- virDomainInfoPtr info;
- const char *filename = "/var/lib/libvirt/save/demo-guest.img";
-
- dom = virDomainLookupByName(conn, "demo-guest");
- if (!dom) {
- fprintf(stderr, "Cannot find guest to be saved");
- return;
- }
-
- if (virDomainGetInfo(dom, &info) < 0) {
- fprintf(stderr, "Cannot check guest state");
- return;
- }
-
- if (info.state == VIR_DOMAIN_SHUTOFF) {
- fprintf(stderr, "Not saving guest that isn't running");
- return;
- }
-
- if (virDomainSave(dom, filename) < 0) {
- fprintf(stderr, "Unable to save guest to %s", filename);
- }
-
- fprintf(stderr, "Guest state saved to %s", filename);
- ]]>
- </programlisting>
+ <example>
+ <title>Saving a Guest Domain</title>
+ <programlisting language="Python"><xi:include
href="extras/Domains-Example-20.py" parse="text"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </example>
<para>
- Some period of time later, the saved state file can then be
- used to restart the guest where it left of, using the
- virDomainRestore API. The hypervisor driver will return an
- error if the guest is already running, however, it won't
- prevent attempts to restore from the same state file multiple
- times. As noted earlier, it is the applications' responsibility
- to ensure the guest storage is in exactly the same state as it
- was when the save image was created
+ Some period of time later, the saved state file can then be
+ used to restart the guest where it left of, using the
+ virDomainRestore API. The hypervisor driver will return an
+ error if the guest is already running, however, it won't
+ prevent attempts to restore from the same state file multiple
+ times. As noted earlier, it is the applications' responsibility
+ to ensure the guest storage is in exactly the same state as it
+ was when the save image was created
</para>
- <programlisting>
- <![CDATA[
- virDomainPtr dom;
- int id;
- const char *filename = "/var/lib/libvirt/save/demo-guest.img";
-
- if ((id = virDomainRestore(conn, filename)) < 0) {
- fprintf(stderr, "Unable to restore guest from %s", filename);
- }
-
- dom = virDomainLookupByID(conn, id);
- if (!dom) {
- fprintf(stderr, "Cannot find guest that was restored");
- return;
- }
-
- fprintf(stderr, "Guest state restored from %s", filename);
- ]]>
- </programlisting>
+ <example>
+ <title>Restoring a Guest Domain</title>
+ <programlisting language="Python"><xi:include
href="extras/Domains-Example-21.py" parse="text"
xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </example>
- </section>
+ </section>
<section
id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Migration">
<title>Migration</title>
diff --git a/en-US/extras/Domains-Example-20.py b/en-US/extras/Domains-Example-20.py
new file mode 100644
index 0000000..b206edb
--- /dev/null
+++ b/en-US/extras/Domains-Example-20.py
@@ -0,0 +1,33 @@
+# Example-20.py
+from __future__ import print_function
+import sys
+import libvirt
+
+filename = '/var/lib/libvirt/save/demo-guest.img'
+
+conn = libvirt.open('qemu:///system')
+if conn == None:
+ print('Failed to open connection to qemu:///system', file=sys.stderr)
+ exit(1)
+
+dom = conn.lookupByName('demo-guest')
+if dom == None:
+ print('Cannot find guest to be saved.', file=sys.stderr)
+ exit(1)
+
+info = dom.info()
+if info == None:
+ print('Cannot check guest state', file=sys.stderr)
+ exit(1)
+
+if info.state == VIR_DOMAIN_SHUTOFF:
+ print('Not saving guest that is not running', file=sys.stderr)
+ exit(1)
+
+if dom.save(filename) < 0:
+ print('Unable to save guest to '+filename, file=sys.stderr)
+
+print('Guest state saved to '+filename, file=sys.stderr)
+
+conn.close()
+exit(0)
diff --git a/en-US/extras/Domains-Example-21.py b/en-US/extras/Domains-Example-21.py
new file mode 100644
index 0000000..0df25f5
--- /dev/null
+++ b/en-US/extras/Domains-Example-21.py
@@ -0,0 +1,25 @@
+# Example-21.py
+from __future__ import print_function
+import sys
+import libvirt
+
+filename = '/var/lib/libvirt/save/demo-guest.img'
+
+conn = libvirt.open('qemu:///system')
+if conn == None:
+ print('Failed to open connection to qemu:///system', file=sys.stderr)
+ exit(1)
+
+if id = conn.restore(filename)) < 0:
+ print('Unable to restore guest from '+filename, file=sys.stderr)
+ exit(1)
+
+dom = conn.lookupByID(id);
+if dom == None:
+ print('Cannot find guest that was restored', file=sys.stderr)
+ exit(1)
+
+print('Guest state restored from '+filename, file=sys.stderr)
+
+conn.close()
+exit(0)