[libvirt_application_development_guide_using_python] Domains Chapter General - fixed some spelling and indentation issues Boot Modes section - conv
by David Ashley
commit 10e724d5a1ba43b93cbfada88116f0410d4bb8ba
Author: W. David Ashley <w.david.ashley(a)gmail.com>
Date: Sun Jul 5 12:42:46 2015 -0500
Domains Chapter
General
- fixed some spelling and indentation issues
Boot Modes section
- converted to python
- added example 26
en-US/Guest_Domains.xml | 827 ++++++++++++++++++-----------------
en-US/extras/Domains-Example-26.xml | 12 +
2 files changed, 430 insertions(+), 409 deletions(-)
---
diff --git a/en-US/Guest_Domains.xml b/en-US/Guest_Domains.xml
index 8039ccb..ce78e1e 100644
--- a/en-US/Guest_Domains.xml
+++ b/en-US/Guest_Domains.xml
@@ -77,17 +77,17 @@
</para>
<example>
- <title>Fetching a domain object from an ID</title>
- <programlisting language="Python"><xi:include href="extras/Domains-Example-1.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ <title>Fetching a domain object from an ID</title>
+ <programlisting language="Python"><xi:include href="extras/Domains-Example-1.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
</example>
<example>
- <title>Fetching a domain object from an name</title>
+ <title>Fetching a domain object from a name</title>
<programlisting language="Python"><xi:include href="extras/Domains-Example-2.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
</example>
<example>
- <title>Fetching a domain object from an UUID</title>
+ <title>Fetching a domain object from a UUID</title>
<programlisting language="Python"><xi:include href="extras/Domains-Example-3.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
</example>
@@ -101,7 +101,7 @@
<title>Listing Domains</title>
<para>
- The libvirt cklasses expose two lists of domains, the first
+ The libvirt classes expose two lists of domains, the first
contains running domains, while the second contains
inactive, persistent domains. The lists are intended to
be non-overlapping, exclusive sets, though there is always
@@ -298,458 +298,467 @@
</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>virDomain</literal> object obtained from defining the guest,
- can then be used to boot it.
- </para>
-
- <example>
- <title>Defining and Booting a Persistent Guest Domain</title>
- <programlisting language="Python"><xi:include href="extras/Domains-Example-8.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-Provisioning-Provisioning_Techniques">
- <title>New Guest Domain Provisioning Techniques</title>
-
- <para>
- This section will first illustrate two configurations that
- allow for a provisioning approach that is comparable to those
- used for physical machines. It then outlines a third option
- which is specific to virtualized hardware, but has some
- interesting benefits. For the purposes of illustration, the
- examples that follow will use an XML configuration that sets
- up a KVM fully virtualized guest, with a single disk and
- network interface and a video card using VNC for display.
- </para>
-
- <programlisting language="XML"><xi:include href="extras/Domains-Example-9.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
- <important>
- <para>
- Be careful in the choice of initial memory allocation, since
- too low a value may cause mysterious crashes and installation
- failures. Some operating systems need as much as 600 MB of memory
- for initial installation, though this can often be reduced
- post-install.
- </para>
- </important>
-
- <section id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Provisioning-ISO">
- <title>CDROM/ISO image provisioning</title>
-
- <para>
- All full virtualization technologies have support for emulating
- a CDROM device in a guest domain, making this an obvious choice
- for provisioning new guest domains. It is, however, fairly rare
- to find a hypervisor which provides CDROM devices for paravirtualized
- guests.
- </para>
-
- <para>
- The first obvious change required to the XML configuration to
- support CDROM installation, is to add a CDROM device. A guest
- domains' CDROM device can be pointed to either a host CDROM
- device, or to a ISO image file. The next change is to determine
- what the BIOS boot order should be, with there being two
- possible options. If the hard disk is listed ahead of the
- CDROM device, then the CDROM media won't be booted unless
- the first boot sector on the hard disk is blank. If the
- CDROM device is listed ahead of the hard disk, then it will
- be necessary to alter the guest config after install to
- make it boot off the installed disk. While both can be made
- to work, the first option is easiest to implement.
- </para>
-
- <para>
- The guest configuration shown earlier would have the following
- XML chunk inserted:
- </para>
-
- <programlisting language="XML"><xi:include href="extras/Domains-Example-10.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
-
- <para>
- NB, this assumes the hard disk boot sector is blank initially,
- so that the first boot attempt falls through to the CD-ROM drive.
- It will also need a CD-ROM drive device added.
- </para>
-
- <programlisting language="XML"><xi:include href="extras/Domains-Example-11.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
-
- <para>
- With the configuration determined, it is now possible
- to provision the guest. This is an easy process, simply
- requiring a persistent guest to be defined, and then
- booted.
- </para>
-
- <example>
- <title>Defining and Booting a Persistent Guest Domain</title>
- <programlisting language="Python"><xi:include href="extras/Domains-Example-12.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
- </example>
-
- <para>
- If it was not possible to guarantee that the boot
- sector of the hard disk is blank, then provisioning
- would have been a two step process. First a transient
- guest would have been booted using CD-ROM drive as the
- primary boot device. Once that completed, then
- a persistent configuration for the guest would be
- defined to boot off the hard disk.
- </para>
-
- </section>
-
- <section id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Provisioning-PXE">
- <title>PXE Boot Provisioning</title>
+ <title>Defining and Booting a Persistent Guest Domain</title>
- <para>
- Some newer full virtualization technologies provide a BIOS that
- is able to use the PXE boot protocol to boot off the network. If
- an environment already has a PXE boot provisioning server deployed,
- this is a desirable method to use for guest domains.
- </para>
+ <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>virDomain</literal> object obtained from defining the guest,
+ can then be used to boot it.
+ </para>
- <para>
- PXE booting a guest obviously requires that the guest has a
- network device configured. The LAN that this network card is
- attached to, also needs a PXE / TFTP server available.
- The next change is to determine
- what the BIOS boot order should be, with there being two
- possible options. If the hard disk is listed ahead of the
- network device, then the network card won't PXE boot unless
- the first boot sector on the hard disk is blank. If the
- network device is listed ahead of the hard disk, then it will
- be necessary to alter the guest config after install to
- make it boot off the installed disk. While both can be made
- to work, the first option is easiest to implement.
- </para>
+ <example>
+ <title>Defining and Booting a Persistent Guest Domain</title>
+ <programlisting language="Python"><xi:include href="extras/Domains-Example-8.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </example>
- <para>
- The guest configuration shown earlier would have the following
- XML chunk inserted:
- </para>
+ </section>
- <programlisting language="XML"><xi:include href="extras/Domains-Example-13.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </section>
+
+ <section id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Provisioning-Provisioning_Techniques">
+ <title>New Guest Domain Provisioning Techniques</title>
<para>
- NB, this assumes the hard disk boot sector is blank initially,
- so that the first boot attempt falls through to the NIC.
- With the configuration determined, it is now possible
- to provision the guest. This is an easy process, simply
- requiring a persistent guest to be defined, and then
- booted.
+ This section will first illustrate two configurations that
+ allow for a provisioning approach that is comparable to those
+ used for physical machines. It then outlines a third option
+ which is specific to virtualized hardware, but has some
+ interesting benefits. For the purposes of illustration, the
+ examples that follow will use an XML configuration that sets
+ up a KVM fully virtualized guest, with a single disk and
+ network interface and a video card using VNC for display.
</para>
- <example>
+ <programlisting language="XML"><xi:include href="extras/Domains-Example-9.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ <important>
+ <para>
+ Be careful in the choice of initial memory allocation, since
+ too low a value may cause mysterious crashes and installation
+ failures. Some operating systems need as much as 600 MB of memory
+ for initial installation, though this can often be reduced
+ post-install.
+ </para>
+ </important>
+
+ <section id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Provisioning-ISO">
+ <title>CDROM/ISO image provisioning</title>
+
+ <para>
+ All full virtualization technologies have support for emulating
+ a CDROM device in a guest domain, making this an obvious choice
+ for provisioning new guest domains. It is, however, fairly rare
+ to find a hypervisor which provides CDROM devices for paravirtualized
+ guests.
+ </para>
+
+ <para>
+ The first obvious change required to the XML configuration to
+ support CDROM installation, is to add a CDROM device. A guest
+ domains' CDROM device can be pointed to either a host CDROM
+ device, or to a ISO image file. The next change is to determine
+ what the BIOS boot order should be, with there being two
+ possible options. If the hard disk is listed ahead of the
+ CDROM device, then the CDROM media won't be booted unless
+ the first boot sector on the hard disk is blank. If the
+ CDROM device is listed ahead of the hard disk, then it will
+ be necessary to alter the guest config after install to
+ make it boot off the installed disk. While both can be made
+ to work, the first option is easiest to implement.
+ </para>
+
+ <para>
+ The guest configuration shown earlier would have the following
+ XML chunk inserted:
+ </para>
+
+ <programlisting language="XML"><xi:include href="extras/Domains-Example-10.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+
+ <para>
+ NB, this assumes the hard disk boot sector is blank initially,
+ so that the first boot attempt falls through to the CD-ROM drive.
+ It will also need a CD-ROM drive device added.
+ </para>
+
+ <programlisting language="XML"><xi:include href="extras/Domains-Example-11.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+
+ <para>
+ With the configuration determined, it is now possible
+ to provision the guest. This is an easy process, simply
+ requiring a persistent guest to be defined, and then
+ booted.
+ </para>
+
+ <example>
+ <title>Defining and Booting a Persistent Guest Domain</title>
+ <programlisting language="Python"><xi:include href="extras/Domains-Example-12.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </example>
+
+ <para>
+ If it was not possible to guarantee that the boot
+ sector of the hard disk is blank, then provisioning
+ would have been a two step process. First a transient
+ guest would have been booted using CD-ROM drive as the
+ primary boot device. Once that completed, then
+ a persistent configuration for the guest would be
+ defined to boot off the hard disk.
+ </para>
+
+ </section>
+
+ <section id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Provisioning-PXE">
<title>PXE Boot Provisioning</title>
- <programlisting language="Python"><xi:include href="extras/Domains-Example-14.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
- </example>
- <para>
- If it was not possible to guarantee that the boot
- sector of the hard disk is blank, then provisioning
- would have been a two step process. First a transient
- guest would have been booted using network as the
- primary boot device. Once that completed, then
- a persistent configuration for the guest would be
- defined to boot off the hard disk.
- </para>
- </section>
+ <para>
+ Some newer full virtualization technologies provide a BIOS that
+ is able to use the PXE boot protocol to boot off the network. If
+ an environment already has a PXE boot provisioning server deployed,
+ this is a desirable method to use for guest domains.
+ </para>
- <section id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Provisioning-Kernel">
- <title>Direct Kernel Boot Provisioning</title>
+ <para>
+ PXE booting a guest obviously requires that the guest has a
+ network device configured. The LAN that this network card is
+ attached to, also needs a PXE / TFTP server available.
+ The next change is to determine
+ what the BIOS boot order should be, with there being two
+ possible options. If the hard disk is listed ahead of the
+ network device, then the network card won't PXE boot unless
+ the first boot sector on the hard disk is blank. If the
+ network device is listed ahead of the hard disk, then it will
+ be necessary to alter the guest config after install to
+ make it boot off the installed disk. While both can be made
+ to work, the first option is easiest to implement.
+ </para>
- <para>
- Paravirtualization technologies emulate a fairly restrictive
- set of hardware, often making it impossible to use the provisioning
- options just outlined. For such scenarios it is often possible to
- boot a new guest domain directly from an kernel and initrd image
- stored on the host file system. This has one interesting advantage,
- which is that it is possible to directly set kernel command line
- boot arguments, making it very easy to do fully automated
- installation. This advantage can be compelling enough that this
- technique is used even for fully virtualized guest domains with
- CD-ROM drive/PXE support.
- </para>
+ <para>
+ The guest configuration shown earlier would have the following
+ XML chunk inserted:
+ </para>
- <para>
- The one complication with direct kernel booting is that provisioning
- becomes a two step process. For the first step, it is necessary to
- configure the guest XML configuration to point to a kernel/initrd.
- </para>
+ <programlisting language="XML"><xi:include href="extras/Domains-Example-13.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
- <example>
- <title>Kernel Boot Provisioning XML</title>
- <programlisting language="XML"><xi:include href="extras/Domains-Example-15.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
- </example>
+ <para>
+ NB, this assumes the hard disk boot sector is blank initially,
+ so that the first boot attempt falls through to the NIC.
+ With the configuration determined, it is now possible
+ to provision the guest. This is an easy process, simply
+ requiring a persistent guest to be defined, and then
+ booted.
+ </para>
- <para>
- Notice how the kernel command line provides the URL of download
- site containing the distro install tree matching the kernel/initrd.
- This allows the installer to automatically download all its resources
- without prompting the user for install URL. It could also be used to
- provide a kickstart file for completely unattended installation.
- Finally, this command line also tells the kernel to activate both
- the first serial port and the VGA card as consoles, with the latter
- being the default. Having kernel messages duplicated on the serial
- port in this manner can be a useful debugging avenue. Of course
- valid command line arguments vary according to the particular kernel
- being booted. Consult the kernel vendor/distributor's documentation
- for valid options.
- </para>
+ <example>
+ <title>PXE Boot Provisioning</title>
+ <programlisting language="Python"><xi:include href="extras/Domains-Example-14.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </example>
- <para>
- The last XML configuration detail before starting the guest, is to
- change the 'on_reboot' element action to be 'destroy'. This ensures
- that when the guest installer finishes and requests a reboot, the
- guest is instead powered off. This allows the management application
- to change the configuration to make it boot off, just installed, the
- hard disk again. The provisioning process can be started now by
- creating a transient guest with the first XML configuration
- </para>
+ <para>
+ If it was not possible to guarantee that the boot
+ sector of the hard disk is blank, then provisioning
+ would have been a two step process. First a transient
+ guest would have been booted using network as the
+ primary boot device. Once that completed, then
+ a persistent configuration for the guest would be
+ defined to boot off the hard disk.
+ </para>
+ </section>
- <example>
- <title>Kernel Boot Provisioning</title>
- <programlisting language="Python"><xi:include href="extras/Domains-Example-16.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
- </example>
+ <section id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Provisioning-Kernel">
+ <title>Direct Kernel Boot Provisioning</title>
- <para>
- Once this guest shuts down, the second phase of the provisioning
- process can be started. For this phase, the 'OS' element will
- have the kernel/initrd/cmdline elements removed, and replaced
- by either a reference to a host side bootloader, or a BIOS
- boot setup. The former is used for Xen paravirtualized guests,
- while the latter is used for fully virtualized guests.
- </para>
+ <para>
+ Paravirtualization technologies emulate a fairly restrictive
+ set of hardware, often making it impossible to use the provisioning
+ options just outlined. For such scenarios it is often possible to
+ boot a new guest domain directly from an kernel and initrd image
+ stored on the host file system. This has one interesting advantage,
+ which is that it is possible to directly set kernel command line
+ boot arguments, making it very easy to do fully automated
+ installation. This advantage can be compelling enough that this
+ technique is used even for fully virtualized guest domains with
+ CD-ROM drive/PXE support.
+ </para>
- <para>
- The phase 2 configuration for a Xen paravirtualized guest
- would thus look like:
- </para>
+ <para>
+ The one complication with direct kernel booting is that provisioning
+ becomes a two step process. For the first step, it is necessary to
+ configure the guest XML configuration to point to a kernel/initrd.
+ </para>
- <programlisting language="XML"><xi:include href="extras/Domains-Example-17.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ <example>
+ <title>Kernel Boot Provisioning XML</title>
+ <programlisting language="XML"><xi:include href="extras/Domains-Example-15.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </example>
- <para>
- while a fully-virtualized guest would use:
- </para>
+ <para>
+ Notice how the kernel command line provides the URL of download
+ site containing the distro install tree matching the kernel/initrd.
+ This allows the installer to automatically download all its resources
+ without prompting the user for install URL. It could also be used to
+ provide a kickstart file for completely unattended installation.
+ Finally, this command line also tells the kernel to activate both
+ the first serial port and the VGA card as consoles, with the latter
+ being the default. Having kernel messages duplicated on the serial
+ port in this manner can be a useful debugging avenue. Of course
+ valid command line arguments vary according to the particular kernel
+ being booted. Consult the kernel vendor/distributor's documentation
+ for valid options.
+ </para>
+
+ <para>
+ The last XML configuration detail before starting the guest, is to
+ change the 'on_reboot' element action to be 'destroy'. This ensures
+ that when the guest installer finishes and requests a reboot, the
+ guest is instead powered off. This allows the management application
+ to change the configuration to make it boot off, just installed, the
+ hard disk again. The provisioning process can be started now by
+ creating a transient guest with the first XML configuration
+ </para>
- <programlisting language="XML"><xi:include href="extras/Domains-Example-18.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ <example>
+ <title>Kernel Boot Provisioning</title>
+ <programlisting language="Python"><xi:include href="extras/Domains-Example-16.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </example>
- <para>
- With the second phase configuration determined, the guest can
- be recreated, this time using a persistent configuration
- </para>
+ <para>
+ Once this guest shuts down, the second phase of the provisioning
+ process can be started. For this phase, the 'OS' element will
+ have the kernel/initrd/cmdline elements removed, and replaced
+ by either a reference to a host side bootloader, or a BIOS
+ boot setup. The former is used for Xen paravirtualized guests,
+ while the latter is used for fully virtualized guests.
+ </para>
+
+ <para>
+ The phase 2 configuration for a Xen paravirtualized guest
+ would thus look like:
+ </para>
+
+ <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>
- <example>
- <title>Kernel Boot Provisioning for a Persistent Guest Domain</title>
- <programlisting language="Python"><xi:include href="extras/Domains-Example-19.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
- </example>
+ <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
+ be recreated, this time using a persistent configuration
+ </para>
+
+ <example>
+ <title>Kernel Boot Provisioning for a Persistent Guest Domain</title>
+ <programlisting language="Python"><xi:include href="extras/Domains-Example-19.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </example>
+
+ </section>
</section>
</section>
- </section>
- <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.
- </para>
- <para>
- 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>
- 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 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.
+ </para>
+ <para>
+ 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>
+ 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 id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Save">
- <title>Suspend / Resume and Save / Restore</title>
+ <section id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Save">
+ <title>Suspend / Resume and Save / Restore</title>
- <para>
- 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>
- 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>
+ 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>
+ 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 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>
+ 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.
- </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.
+ </para>
- <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>
+ <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
- </para>
+ <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
+ </para>
- <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>
+ <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>
+ <section id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Migration">
+ <title>Migration</title>
- <para>
- 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
- hypervisor connection, and instructs the domain to migrate to this connection. The
- <literal>migrateToUri</literal> method takes a URI specifying a hypervisor connection,
- opens the connection, then instructions the domain to migrate to this connection. Both
- these methods can be passed a parameter to specify live migration. For migration to
- complete successfully, storage needs to be shared between the source and target hypervisors.
- </para>
- <para>
- The first parameter of the <literal>migrate</literal> method specifies the connectiion to be used to the
- target of the migration. This parameter is required.
- </para>
- <para>
- The second parameter of the <literal>migrate</literal> method specifies a set of flags that control how the
- migration takes place over the connection. If npo flags are needed then the parameter should
- be set to zero.
- </para>
- <para>
- The third parameter of the <literal>migrate</literal> method specifies a new name for the domain on the target
- of the migration. Not all hypervisors support this operation. If no rename of the domain is
- required then the parameter shoule be set to <literal>None</literal>.
- </para>
- <para>
- The third parameter of the <literal>migrate</literal> method specifies a new name for the domain on the target
- of the migration. Not all hypervisors support this operation. If no rename of the domain is
- required then the parameter can be set to <literal>None</literal>.
- </para>
- <para>
- The forth parameter of the <literal>migrate</literal> method specifies the URI to be used as the
- target of the migration. A URI is only required when the target system supports multiple
- hypervisors. If ther is only a single hypervisor on the target system then
- the parameter can be set to <literal>None</literal>.
- </para>
- <para>
- The fifth and last parameter of the <literal>migrate</literal> method specifies the bandwidth in
- MiB/s to be used. If this maximum is not needed then set the parameter to zero.
- </para>
- <para>
- To migrate a guest domain to a connection that is already open use the <literal>migrate</literal>
- method. An example follows:
- </para>
- <example>
- <title>Migrate a Domain to an Open Connection</title>
- <programlisting language="Python"><xi:include href="extras/Domains-Example-22.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
- </example>
- <para>
- The <literal>migrateToURI</literal> method similar except that the destination URI is the first
- parameter instead of an existing connection.
- </para>
- <para>
- To migrate a guest domain to a URI use the <literal>migrateToURI</literal>
- method. An example follows:
- </para>
- <example>
- <title>Migrate a Domain to an Open Connection</title>
- <programlisting language="Python"><xi:include href="extras/Domains-Example-23.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
- </example>
- <para>
- To migrate a live guest domain to a URI use the <literal>migrate</literal> or the
- <literal>migrateToURI</literal> with the <literal>VIR_MIGRATE_LIVE</literal> flag set. An example follows:
- </para>
- <example>
- <title>Migrate a Domain to an Open Connection</title>
- <programlisting language="Python"><xi:include href="extras/Domains-Example-24.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
- </example>
- </section>
+ <para>
+ 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
+ hypervisor connection, and instructs the domain to migrate to this connection. The
+ <literal>migrateToUri</literal> method takes a URI specifying a hypervisor connection,
+ opens the connection, then instructions the domain to migrate to this connection. Both
+ these methods can be passed a parameter to specify live migration. For migration to
+ complete successfully, storage needs to be shared between the source and target hypervisors.
+ </para>
+ <para>
+ The first parameter of the <literal>migrate</literal> method specifies the connectiion to be used to the
+ target of the migration. This parameter is required.
+ </para>
+ <para>
+ The second parameter of the <literal>migrate</literal> method specifies a set of flags that control how the
+ migration takes place over the connection. If npo flags are needed then the parameter should
+ be set to zero.
+ </para>
+ <para>
+ The third parameter of the <literal>migrate</literal> method specifies a new name for the domain on the target
+ of the migration. Not all hypervisors support this operation. If no rename of the domain is
+ required then the parameter shoule be set to <literal>None</literal>.
+ </para>
+ <para>
+ The third parameter of the <literal>migrate</literal> method specifies a new name for the domain on the target
+ of the migration. Not all hypervisors support this operation. If no rename of the domain is
+ required then the parameter can be set to <literal>None</literal>.
+ </para>
+ <para>
+ The forth parameter of the <literal>migrate</literal> method specifies the URI to be used as the
+ target of the migration. A URI is only required when the target system supports multiple
+ hypervisors. If ther is only a single hypervisor on the target system then
+ the parameter can be set to <literal>None</literal>.
+ </para>
+ <para>
+ The fifth and last parameter of the <literal>migrate</literal> method specifies the bandwidth in
+ MiB/s to be used. If this maximum is not needed then set the parameter to zero.
+ </para>
+ <para>
+ To migrate a guest domain to a connection that is already open use the <literal>migrate</literal>
+ method. An example follows:
+ </para>
+ <example>
+ <title>Migrate a Domain to an Open Connection</title>
+ <programlisting language="Python"><xi:include href="extras/Domains-Example-22.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </example>
+ <para>
+ The <literal>migrateToURI</literal> method is similar except that the destination URI is the first
+ parameter instead of an existing connection.
+ </para>
+ <para>
+ To migrate a guest domain to a URI use the <literal>migrateToURI</literal>
+ method. An example follows:
+ </para>
+ <example>
+ <title>Migrate a Domain to an Open Connection</title>
+ <programlisting language="Python"><xi:include href="extras/Domains-Example-23.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </example>
+ <para>
+ To migrate a live guest domain to a URI use the <literal>migrate</literal> or the
+ <literal>migrateToURI</literal> with the <literal>VIR_MIGRATE_LIVE</literal> flag set. An example follows:
+ </para>
+ <example>
+ <title>Migrate a Domain to an Open Connection</title>
+ <programlisting language="Python"><xi:include href="extras/Domains-Example-24.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </example>
+ </section>
- <section id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Autostart">
- <title>Autostart</title>
+ <section id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Autostart">
+ <title>Autostart</title>
- <para>
- 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
- rebooted. When libvirt restarts, the guest domain will be automatically restored. This is
- handled by an API separate to regular save and restore, because paths must be known to
- libvirt without user input.
- </para>
- <example>
- <title>Set Autostart for a Domain</title>
- <programlisting language="Python"><xi:include href="extras/Domains-Example-25.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
- </example>
- </section>
+ <para>
+ 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
+ rebooted. When libvirt restarts, the guest domain will be automatically restored. This is
+ handled by an API separate to regular save and restore, because paths must be known to
+ libvirt without user input.
+ </para>
+ <example>
+ <title>Set Autostart for a Domain</title>
+ <programlisting language="Python"><xi:include href="extras/Domains-Example-25.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-Domain_Config">
- <title>Domain configuration</title>
-
- <para>
- Domains are defined in libvirt using XML. Everything related only to the domain, such as memory and CPU, is defined in the domain XML. The domain XML format is specified at <ulink url="http://libvirt.org/formatdomain.html">http://libvirt.org/formatdomain.html</ulink>. This can be accessed locally in <filename>/usr/share/doc/libvirt-devel-version/</filename> if your system has the <package>libvirt-devel</package> package installed.
- </para>
-
- <section id="libvirt_application_development_guide_using_python-Guest_Domains-Domain_Config-Boot">
- <title>Boot modes</title>
+ <title>Domain Configuration</title>
<para>
- TBD
-
+ Domains are defined in libvirt using XML. Everything related only to the domain, such as
+ memory and CPU, is defined in the domain XML. The domain XML format is specified at
+ <ulink url="http://libvirt.org/formatdomain.html">http://libvirt.org/formatdomain.html</ulink>.
+ This can be accessed locally in <filename>/usr/share/doc/libvirt-devel-version/</filename>
+ if your system has the <package>libvirt-devel</package> package installed.
</para>
- </section>
+ <section id="libvirt_application_development_guide_using_python-Guest_Domains-Domain_Config-Boot">
+ <title>Boot Modes</title>
+
+ <para>
+ Booting via the BIOS is available for hypervisors supporting full virtualization. In this
+ case the BIOS has a boot order priority (floppy, harddisk, cdrom, network) determining where
+ to obtain/find the boot image.
+ </para>
+ <example>
+ <title>Setting the Boot Mode</title>
+ <programlisting language="XML"><xi:include href="extras/Domains-Example-26.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </example>
+
+ </section>
<section id="libvirt_application_development_guide_using_python-Guest_Domains-Domain_Config-Memory_CPU">
<title>Memory / CPU resources</title>
diff --git a/en-US/extras/Domains-Example-26.xml b/en-US/extras/Domains-Example-26.xml
new file mode 100644
index 0000000..75b916b
--- /dev/null
+++ b/en-US/extras/Domains-Example-26.xml
@@ -0,0 +1,12 @@
+ ...
+ <os>
+ <type>hvm</type>
+ <loader readonly='yes' type='rom'>/usr/lib/xen/boot/hvmloader</loader>
+ <nvram template='/usr/share/OVMF/OVMF_VARS.fd'>/var/lib/libvirt/nvram/guest_VARS.fd</nvram>
+ <boot dev='hd'/>
+ <boot dev='cdrom'/>
+ <bootmenu enable='yes' timeout='3000'/>
+ <smbios mode='sysinfo'/>
+ <bios useserial='yes' rebootTimeout='0'/>
+ </os>
+ ...
8 years, 9 months
[libvirt_application_development_guide_using_python] Domains Chapter Autostart section - converted the section to Python - added example 25
by David Ashley
commit 8e8d4230eccd4239cc93576e795f8661ea94623d
Author: W. David Ashley <w.david.ashley(a)gmail.com>
Date: Sun Jul 5 11:41:58 2015 -0500
Domains Chapter
Autostart section
- converted the section to Python
- added example 25
en-US/Guest_Domains.xml | 14 ++++++++++----
en-US/extras/Domains-Example-25.py | 21 +++++++++++++++++++++
2 files changed, 31 insertions(+), 4 deletions(-)
---
diff --git a/en-US/Guest_Domains.xml b/en-US/Guest_Domains.xml
index b633cf9..8039ccb 100644
--- a/en-US/Guest_Domains.xml
+++ b/en-US/Guest_Domains.xml
@@ -719,11 +719,17 @@
<title>Autostart</title>
<para>
- 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 rebooted. When libvirt restarts, the guest domain will be automatically restored. This is handled by an API separate to regular save and restore, because paths must be known to libvirt without user input.
- </para>
- <para>
- TODO: code example.
+ 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
+ rebooted. When libvirt restarts, the guest domain will be automatically restored. This is
+ handled by an API separate to regular save and restore, because paths must be known to
+ libvirt without user input.
</para>
+ <example>
+ <title>Set Autostart for a Domain</title>
+ <programlisting language="Python"><xi:include href="extras/Domains-Example-25.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </example>
</section>
</section>
diff --git a/en-US/extras/Domains-Example-25.py b/en-US/extras/Domains-Example-25.py
new file mode 100644
index 0000000..12c8e1a
--- /dev/null
+++ b/en-US/extras/Domains-Example-25.py
@@ -0,0 +1,21 @@
+# Example-25.py
+from __future__ import print_function
+import sys
+import libvirt
+
+domName = 'Fedora22-x86_64-1'
+
+conn = libvirt.open('qemu:///system')
+if conn == None:
+ print('Failed to open connection to qemu:///system', file=sys.stderr)
+ exit(1)
+
+dom = conn.lookupByID(6)
+if dom == None:
+ print('Failed to find the domain '+domName, file=sys.stderr)
+ exit(1)
+
+dom.setAutostart(1) # turn on autostart
+
+conn.close()
+exit(0)
8 years, 9 months
[libvirt_application_development_guide_using_python] Domains Chapter Migration section -added attitional parameter information for thr migrate and mig
by David Ashley
commit 95094d69b16b952255de97325a2ae70722aa5700
Author: W. David Ashley <w.david.ashley(a)gmail.com>
Date: Sun Jul 5 11:21:29 2015 -0500
Domains Chapter
Migration section
-added attitional parameter information for thr migrate and migrateToURI methods.
en-US/Guest_Domains.xml | 35 ++++++++++++++++++++++++++++++++++-
1 files changed, 34 insertions(+), 1 deletions(-)
---
diff --git a/en-US/Guest_Domains.xml b/en-US/Guest_Domains.xml
index ee411e9..b633cf9 100644
--- a/en-US/Guest_Domains.xml
+++ b/en-US/Guest_Domains.xml
@@ -657,6 +657,35 @@
complete successfully, storage needs to be shared between the source and target hypervisors.
</para>
<para>
+ The first parameter of the <literal>migrate</literal> method specifies the connectiion to be used to the
+ target of the migration. This parameter is required.
+ </para>
+ <para>
+ The second parameter of the <literal>migrate</literal> method specifies a set of flags that control how the
+ migration takes place over the connection. If npo flags are needed then the parameter should
+ be set to zero.
+ </para>
+ <para>
+ The third parameter of the <literal>migrate</literal> method specifies a new name for the domain on the target
+ of the migration. Not all hypervisors support this operation. If no rename of the domain is
+ required then the parameter shoule be set to <literal>None</literal>.
+ </para>
+ <para>
+ The third parameter of the <literal>migrate</literal> method specifies a new name for the domain on the target
+ of the migration. Not all hypervisors support this operation. If no rename of the domain is
+ required then the parameter can be set to <literal>None</literal>.
+ </para>
+ <para>
+ The forth parameter of the <literal>migrate</literal> method specifies the URI to be used as the
+ target of the migration. A URI is only required when the target system supports multiple
+ hypervisors. If ther is only a single hypervisor on the target system then
+ the parameter can be set to <literal>None</literal>.
+ </para>
+ <para>
+ The fifth and last parameter of the <literal>migrate</literal> method specifies the bandwidth in
+ MiB/s to be used. If this maximum is not needed then set the parameter to zero.
+ </para>
+ <para>
To migrate a guest domain to a connection that is already open use the <literal>migrate</literal>
method. An example follows:
</para>
@@ -665,6 +694,10 @@
<programlisting language="Python"><xi:include href="extras/Domains-Example-22.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
</example>
<para>
+ The <literal>migrateToURI</literal> method similar except that the destination URI is the first
+ parameter instead of an existing connection.
+ </para>
+ <para>
To migrate a guest domain to a URI use the <literal>migrateToURI</literal>
method. An example follows:
</para>
@@ -674,7 +707,7 @@
</example>
<para>
To migrate a live guest domain to a URI use the <literal>migrate</literal> or the
- <literal>migrateToURI</literal> with the <literal>VIR_MIGRATE_LIVE</literal>. An example follows:
+ <literal>migrateToURI</literal> with the <literal>VIR_MIGRATE_LIVE</literal> flag set. An example follows:
</para>
<example>
<title>Migrate a Domain to an Open Connection</title>
8 years, 9 months
[libvirt_application_development_guide_using_python] Domain Chapter Migration section - Oops, forgot to save it in the last commit
by David Ashley
commit 1676a4ffd9c800d14fea0f2616ec3e67938b1c2f
Author: W. David Ashley <w.david.ashley(a)gmail.com>
Date: Fri Jul 3 20:55:34 2015 -0500
Domain Chapter
Migration section
- Oops, forgot to save it in the last commit
en-US/Guest_Domains.xml | 24 ++++++++++++++++++++++--
1 files changed, 22 insertions(+), 2 deletions(-)
---
diff --git a/en-US/Guest_Domains.xml b/en-US/Guest_Domains.xml
index e1c66eb..ee411e9 100644
--- a/en-US/Guest_Domains.xml
+++ b/en-US/Guest_Domains.xml
@@ -657,9 +657,29 @@
complete successfully, storage needs to be shared between the source and target hypervisors.
</para>
<para>
- TODO: Add 2 cold examples, 1 live example.
+ To migrate a guest domain to a connection that is already open use the <literal>migrate</literal>
+ method. An example follows:
</para>
-
+ <example>
+ <title>Migrate a Domain to an Open Connection</title>
+ <programlisting language="Python"><xi:include href="extras/Domains-Example-22.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </example>
+ <para>
+ To migrate a guest domain to a URI use the <literal>migrateToURI</literal>
+ method. An example follows:
+ </para>
+ <example>
+ <title>Migrate a Domain to an Open Connection</title>
+ <programlisting language="Python"><xi:include href="extras/Domains-Example-23.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </example>
+ <para>
+ To migrate a live guest domain to a URI use the <literal>migrate</literal> or the
+ <literal>migrateToURI</literal> with the <literal>VIR_MIGRATE_LIVE</literal>. An example follows:
+ </para>
+ <example>
+ <title>Migrate a Domain to an Open Connection</title>
+ <programlisting language="Python"><xi:include href="extras/Domains-Example-24.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </example>
</section>
<section id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Autostart">
8 years, 9 months
[libvirt_application_development_guide_using_python] Domains Chapter Migration section - Finished converting the section to Python - added examples
by David Ashley
commit 88d529159eea084ff825b6c0ffb37817975f0f47
Author: W. David Ashley <w.david.ashley(a)gmail.com>
Date: Fri Jul 3 20:53:32 2015 -0500
Domains Chapter
Migration section
- Finished converting the section to Python
- added examples 22-24
en-US/Guest_Domains.xml | 23 +++++++++++++++--------
en-US/extras/Domains-Example-22.py | 32 ++++++++++++++++++++++++++++++++
en-US/extras/Domains-Example-23.py | 26 ++++++++++++++++++++++++++
en-US/extras/Domains-Example-24.py | 32 ++++++++++++++++++++++++++++++++
4 files changed, 105 insertions(+), 8 deletions(-)
---
diff --git a/en-US/Guest_Domains.xml b/en-US/Guest_Domains.xml
index 808cdec..e1c66eb 100644
--- a/en-US/Guest_Domains.xml
+++ b/en-US/Guest_Domains.xml
@@ -643,28 +643,35 @@
</section>
- <section id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Migration">
+ <section id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Migration">
<title>Migration</title>
<para>
- 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 APIs for migration. The <literal>virDomainMigrate</literal> command takes an established hypervisor connection, and instructs the domain to migrate to this connection. The <literal>virMigrateToUri</literal> command takes a URI specifying a hypervisor connection, opens the connection, then instructions the domain to migrate to this connection. Both these commands can be passed a parameter to specify live migration. For migration to complete successfully, storage needs to be shared between the source and target hypervisors.
+ 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
+ hypervisor connection, and instructs the domain to migrate to this connection. The
+ <literal>migrateToUri</literal> method takes a URI specifying a hypervisor connection,
+ opens the connection, then instructions the domain to migrate to this connection. Both
+ these methods can be passed a parameter to specify live migration. For migration to
+ complete successfully, storage needs to be shared between the source and target hypervisors.
</para>
<para>
- TODO: Add 2 cold examples, 1 live example.
+ TODO: Add 2 cold examples, 1 live example.
</para>
- </section>
+ </section>
- <section id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Autostart">
+ <section id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Autostart">
<title>Autostart</title>
<para>
- 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 rebooted. When libvirt restarts, the guest domain will be automatically restored. This is handled by an API separate to regular save and restore, because paths must be known to libvirt without user input.
+ 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 rebooted. When libvirt restarts, the guest domain will be automatically restored. This is handled by an API separate to regular save and restore, because paths must be known to libvirt without user input.
</para>
<para>
- TODO: code example.
+ TODO: code example.
</para>
- </section>
+ </section>
</section>
diff --git a/en-US/extras/Domains-Example-22.py b/en-US/extras/Domains-Example-22.py
new file mode 100644
index 0000000..7093685
--- /dev/null
+++ b/en-US/extras/Domains-Example-22.py
@@ -0,0 +1,32 @@
+# Example-22.py
+from __future__ import print_function
+import sys
+import libvirt
+
+domName = 'Fedora22-x86_64-1'
+
+conn = libvirt.open('qemu:///system')
+if conn == None:
+ print('Failed to open connection to qemu:///system', file=sys.stderr)
+ exit(1)
+
+dest_conn = libvirt.open('qemu+ssh://desthost/system')
+if conn == None:
+ print('Failed to open connection to qemu+ssh://desthost/system', file=sys.stderr)
+ exit(1)
+
+dom = conn.lookupByName(domName)
+if dom == None:
+ print('Failed to find the domain '+domName, file=sys.stderr)
+ exit(1)
+
+new_dom = dom.migrate(dest_conn, 0, None, None, 0)
+if new_dom == None:
+ print('Could not migrate to the new domain', file=sys.stderr)
+ exit(1)
+
+print('Domain was migrated successfully.', file=sys.stderr)
+
+destconn.close()
+conn.close()
+exit(0)
diff --git a/en-US/extras/Domains-Example-23.py b/en-US/extras/Domains-Example-23.py
new file mode 100644
index 0000000..da5a37c
--- /dev/null
+++ b/en-US/extras/Domains-Example-23.py
@@ -0,0 +1,26 @@
+# Example-23.py
+from __future__ import print_function
+import sys
+import libvirt
+
+domName = 'Fedora22-x86_64-1'
+
+conn = libvirt.open('qemu:///system')
+if conn == None:
+ print('Failed to open connection to qemu:///system', file=sys.stderr)
+ exit(1)
+
+dom = conn.lookupByName(domName)
+if dom == None:
+ print('Failed to find the domain '+domName, file=sys.stderr)
+ exit(1)
+
+new_dom = dom.migrateToURI('qemu+ssh://desthost/system', 0, None, 0)
+if new_dom == None:
+ print('Could not migrate to the new domain', file=sys.stderr)
+ exit(1)
+
+print('Domain was migrated successfully.', file=sys.stderr)
+
+conn.close()
+exit(0)
diff --git a/en-US/extras/Domains-Example-24.py b/en-US/extras/Domains-Example-24.py
new file mode 100644
index 0000000..f2274dd
--- /dev/null
+++ b/en-US/extras/Domains-Example-24.py
@@ -0,0 +1,32 @@
+# Example-24.py
+from __future__ import print_function
+import sys
+import libvirt
+
+domName = 'Fedora22-x86_64-1'
+
+conn = libvirt.open('qemu:///system')
+if conn == None:
+ print('Failed to open connection to qemu:///system', file=sys.stderr)
+ exit(1)
+
+dest_conn = libvirt.open('qemu+ssh://desthost/system')
+if conn == None:
+ print('Failed to open connection to qemu+ssh://desthost/system', file=sys.stderr)
+ exit(1)
+
+dom = conn.lookupByID(6)
+if dom == None:
+ print('Failed to find the domain '+domName, file=sys.stderr)
+ exit(1)
+
+new_dom = dom.migrate(dest_conn, libvirt.VIR_MIGRATE_LIVE, None, None, 0)
+if new_dom == None:
+ print('Could not migrate to the new domain', file=sys.stderr)
+ exit(1)
+
+print('Domain was migrated successfully.', file=sys.stderr)
+
+destconn.close()
+conn.close()
+exit(0)
8 years, 9 months
[libvirt_application_development_guide_using_python] Domain Chapter Stopping section - Finished converting to Python Suspend/Resume and Save/Restore
by David Ashley
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)
8 years, 9 months
[libvirt_application_development_guide_using_python] Domains Chapter Provisioning section - Finished the Provisioning section. - Added examples 15-1
by David Ashley
commit fa6fab3af05e06688bbd80259d96d03ada37611a
Author: W. David Ashley <w.david.ashley(a)gmail.com>
Date: Fri Jul 3 11:42:25 2015 -0500
Domains Chapter
Provisioning section
- Finished the Provisioning section.
- Added examples 15-19.
en-US/Guest_Domains.xml | 165 +++++++++++++----------------------
en-US/extras/Domains-Example-15.xml | 6 ++
en-US/extras/Domains-Example-16.py | 21 +++++
en-US/extras/Domains-Example-17.xml | 4 +
en-US/extras/Domains-Example-18.xml | 5 +
en-US/extras/Domains-Example-19.py | 25 +++++
6 files changed, 122 insertions(+), 104 deletions(-)
---
diff --git a/en-US/Guest_Domains.xml b/en-US/Guest_Domains.xml
index cbf1ba9..a841cf2 100644
--- a/en-US/Guest_Domains.xml
+++ b/en-US/Guest_Domains.xml
@@ -465,140 +465,97 @@
</section>
<section id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Provisioning-Kernel">
- <title>Direct kernel boot provisioning</title>
+ <title>Direct Kernel Boot Provisioning</title>
<para>
- Paravirtualization technologies emulate a fairly restrictive
- set of hardware, often making it impossible to use the provisioning
- options just outlined. For such scenarios it is often possible to
- boot a new guest domain directly from an kernel and initrd image
- stored on the host file system. This has one interesting advantage,
- which is that it is possible to directly set kernel command line
- boot arguments, making it very easy to do fully automated
- installation. This advantage can be compelling enough that this
- technique is used even for fully virtualized guest domains with
- CD-ROM drive/PXE support.
+ Paravirtualization technologies emulate a fairly restrictive
+ set of hardware, often making it impossible to use the provisioning
+ options just outlined. For such scenarios it is often possible to
+ boot a new guest domain directly from an kernel and initrd image
+ stored on the host file system. This has one interesting advantage,
+ which is that it is possible to directly set kernel command line
+ boot arguments, making it very easy to do fully automated
+ installation. This advantage can be compelling enough that this
+ technique is used even for fully virtualized guest domains with
+ CD-ROM drive/PXE support.
</para>
<para>
- The one complication with direct kernel booting is that provisioning
- becomes a two step process. For the first step, it is necessary to
- configure the guest XML configuration to point to a kernel/initrd.
+ The one complication with direct kernel booting is that provisioning
+ becomes a two step process. For the first step, it is necessary to
+ configure the guest XML configuration to point to a kernel/initrd.
</para>
- <programlisting>
- <![CDATA[
- <os>
- <type arch='x86_64' machine='pc'>hvm</type>
- <kernel>/var/lib/libvirt/boot/f11-x86_64-vmlinuz</kernel>
- <initrd>/var/lib/libvirt/boot/f11-x86_64-initrd.img</initrd>
- <cmdline>method=http://download.fedoraproject.org/pub/fedora/linux/releases/11/x86... console=ttyS0 console=tty</cmdline>
- </os>
- ]]>
- </programlisting>
+ <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>
+ </example>
<para>
- Notice how the kernel command line provides the URL of download
- site containing the distro install tree matching the kernel/initrd.
- This allows the installer to automatically download all its resources
- without prompting the user for install URL. It could also be used to
- provide a kickstart file for completely unattended installation.
- Finally, this command line also tells the kernel to activate both
- the first serial port and the VGA card as consoles, with the latter
- being the default. Having kernel messages duplicated on the serial
- port in this manner can be a useful debugging avenue. Of course
- valid command line arguments vary according to the particular kernel
- being booted. Consult the kernel vendor/distributor's documentation
- for valid options.
+ Notice how the kernel command line provides the URL of download
+ site containing the distro install tree matching the kernel/initrd.
+ This allows the installer to automatically download all its resources
+ without prompting the user for install URL. It could also be used to
+ provide a kickstart file for completely unattended installation.
+ Finally, this command line also tells the kernel to activate both
+ the first serial port and the VGA card as consoles, with the latter
+ being the default. Having kernel messages duplicated on the serial
+ port in this manner can be a useful debugging avenue. Of course
+ valid command line arguments vary according to the particular kernel
+ being booted. Consult the kernel vendor/distributor's documentation
+ for valid options.
</para>
<para>
- The last XML configuration detail before starting the guest, is to
- change the 'on_reboot' element action to be 'destroy'. This ensures
- that when the guest installer finishes and requests a reboot, the
- guest is instead powered off. This allows the management application
- to change the configuration to make it boot off, just installed, the
- hard disk again. The provisioning process can be started now by
- creating a transient guest with the first XML configuration
+ The last XML configuration detail before starting the guest, is to
+ change the 'on_reboot' element action to be 'destroy'. This ensures
+ that when the guest installer finishes and requests a reboot, the
+ guest is instead powered off. This allows the management application
+ to change the configuration to make it boot off, just installed, the
+ hard disk again. The provisioning process can be started now by
+ creating a transient guest with the first XML configuration
</para>
- <programlisting>
- <![CDATA[
- const char *xml = "<domain>....</domain>";
- virDomainPtr dom;
-
- dom = virDomainCreateXML(conn, xml);
- if (!dom) {
- fprintf(stderr, "Unable to boot transient guest configuration");
- return;
- }
- ]]>
- </programlisting>
+ <example>
+ <title>Kernel Boot Provisioning</title>
+ <programlisting language="Python"><xi:include href="extras/Domains-Example-16.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </example>
<para>
- Once this guest shuts down, the second phase of the provisioning
- process can be started. For this phase, the 'OS' element will
- have the kernel/initrd/cmdline elements removed, and replaced
- by either a reference to a host side bootloader, or a BIOS
- boot setup. The former is used for Xen paravirtualized guests,
- while the latter is used for fully virtualized guests.
+ Once this guest shuts down, the second phase of the provisioning
+ process can be started. For this phase, the 'OS' element will
+ have the kernel/initrd/cmdline elements removed, and replaced
+ by either a reference to a host side bootloader, or a BIOS
+ boot setup. The former is used for Xen paravirtualized guests,
+ while the latter is used for fully virtualized guests.
</para>
<para>
- The phase 2 configuration for a Xen paravirtualized guest
- would thus look like:
+ The phase 2 configuration for a Xen paravirtualized guest
+ would thus look like:
</para>
- <programlisting>
- <![CDATA[
- <bootloader>/usr/bin/pygrub</bootloader>
- <os>
- <type arch='x86_64' machine='pc'>xen</type>
- </os>
- ]]>
- </programlisting>
+ <programlisting language="Python"><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>
- <![CDATA[
- <bootloader>/usr/bin/pygrub</bootloader>
- <os>
- <type arch='x86_64' machine='pc'>hvm</type>
- <boot dev='hd'/>
- </os>
- ]]>
- </programlisting>
+ <programlisting language="Python"><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
- be recreated, this time using a persistent configuration
+ With the second phase configuration determined, the guest can
+ be recreated, this time using a persistent configuration
</para>
- <programlisting>
- <![CDATA[
- const char *xml = "<domain>....</domain>";
- virDomainPtr dom;
-
- dom = virDomainCreateXML(conn, xml);
- if (!dom) {
- fprintf(stderr, "Unable to define persistent guest configuration\n");
- return;
- }
-
- if (virDomainCreate(dom) < 0) {
- fprintf(stderr, "Unable to boot persistent guest\n");
- return;
- }
+ <example>
+ <title>Kernel Boot Provisioning for a Persistent Guest Domain</title>
+ <programlisting language="Python"><xi:include href="extras/Domains-Example-19.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </example>
- fprintf(stderr, "Guest provisoning complete, OS is running\n");
- ]]>
- </programlisting>
- </section>
- </section>
- </section>
+ </section>
+ </section>
+ </section>
<section id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Stopping">
<title>Stopping</title>
diff --git a/en-US/extras/Domains-Example-15.xml b/en-US/extras/Domains-Example-15.xml
new file mode 100644
index 0000000..4cdbed9
--- /dev/null
+++ b/en-US/extras/Domains-Example-15.xml
@@ -0,0 +1,6 @@
+<os>
+ <type arch='x86_64' machine='pc'>hvm</type>
+ <kernel>/var/lib/libvirt/boot/f11-x86_64-vmlinuz</kernel>
+ <initrd>/var/lib/libvirt/boot/f11-x86_64-initrd.img</initrd>
+ <cmdline>method=http://download.fedoraproject.org/pub/fedora/linux/releases/11/x86... console=ttyS0 console=tty</cmdline>
+</os>
diff --git a/en-US/extras/Domains-Example-16.py b/en-US/extras/Domains-Example-16.py
new file mode 100644
index 0000000..a76ecb2
--- /dev/null
+++ b/en-US/extras/Domains-Example-16.py
@@ -0,0 +1,21 @@
+# Example-14.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('Unable to boot transient guest configuration.', file=sys.stderr)
+ exit(1)
+
+print('Guest '+dom.name()+' has booted', file=sys.stderr)
+
+conn.close()
+exit(0)
diff --git a/en-US/extras/Domains-Example-17.xml b/en-US/extras/Domains-Example-17.xml
new file mode 100644
index 0000000..71f15f1
--- /dev/null
+++ b/en-US/extras/Domains-Example-17.xml
@@ -0,0 +1,4 @@
+<bootloader>/usr/bin/pygrub</bootloader>
+<os>
+ <type arch='x86_64' machine='pc'>xen</type>
+</os>
diff --git a/en-US/extras/Domains-Example-18.xml b/en-US/extras/Domains-Example-18.xml
new file mode 100644
index 0000000..ad83460
--- /dev/null
+++ b/en-US/extras/Domains-Example-18.xml
@@ -0,0 +1,5 @@
+<bootloader>/usr/bin/pygrub</bootloader>
+<os>
+ <type arch='x86_64' machine='pc'>hvm</type>
+ <boot dev='hd'/>
+</os>
diff --git a/en-US/extras/Domains-Example-19.py b/en-US/extras/Domains-Example-19.py
new file mode 100644
index 0000000..7ee682e
--- /dev/null
+++ b/en-US/extras/Domains-Example-19.py
@@ -0,0 +1,25 @@
+# Example-18.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('Unable to define persistent guest configuration.', file=sys.stderr)
+ exit(1)
+
+if dom.create(dom) < 0:
+ print('Can not boot guest domain.', file=sys.stderr)
+ exit(1)
+
+print('Guest '+dom.name()+' has booted', file=sys.stderr)
+
+conn.close()
+exit(0)
8 years, 9 months
[libvirt_application_development_guide_using_python] Domains Chapter Provisioning and Starting Sections - Converted to Python - Added examples 9-14
by David Ashley
commit 029bb3be9b51bb6c4d5dc3a627a4e9e44966b51c
Author: W. David Ashley <w.david.ashley(a)gmail.com>
Date: Fri Jul 3 09:56:00 2015 -0500
Domains Chapter
Provisioning and Starting Sections
- Converted to Python
- Added examples 9-14 (Python and XML)
- still more work to do on this section
en-US/Guest_Domains.xml | 557 +++++++++++++++--------------------
en-US/extras/Domains-Example-10.xml | 5 +
en-US/extras/Domains-Example-11.xml | 4 +
en-US/extras/Domains-Example-12.py | 25 ++
en-US/extras/Domains-Example-13.xml | 5 +
en-US/extras/Domains-Example-14.py | 25 ++
en-US/extras/Domains-Example-9.xml | 25 ++
7 files changed, 330 insertions(+), 316 deletions(-)
---
diff --git a/en-US/Guest_Domains.xml b/en-US/Guest_Domains.xml
index dc79b5e..cbf1ba9 100644
--- a/en-US/Guest_Domains.xml
+++ b/en-US/Guest_Domains.xml
@@ -317,361 +317,286 @@
</section>
- <section id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Provisioning-config">
- <title>New guest provisioning techniques</title>
-
- <para>
- This section will first illustrate two configurations that
- allow for a provisioning approach that is comparable to those
- used for physical machines. It then outlines a third option
- which is specific to virtualized hardware, but has some
- interesting benefits. For the purposes of illustration, the
- examples that follow will use a XML configuration that sets
- up a KVM fully virtualized guest, with a single disk and
- network interface and a video card using VNC for display.
- </para>
-
- <programlisting>
- <![CDATA[
- <domain type='kvm'>
- <name>demo</name>
- <uuid>c7a5fdbd-cdaf-9455-926a-d65c16db1809</uuid>
- <memory>500000</memory>
- <vcpu>1</vcpu>
- .... the <os> block will vary per approach ...
- <clock offset='utc'/>
- <on_poweroff>destroy</on_poweroff>
- <on_reboot>restart</on_reboot>
- <on_crash>destroy</on_crash>
- <devices>
- <emulator>/usr/bin/qemu-kvm</emulator>
- <disk type='file' device='disk'>
- <source file='/var/lib/libvirt/images/demo.img'/>
- <driver name='qemu' type='raw'/>
- <target dev='hda'/>
- </disk>
- <interface type='bridge'>
- <mac address='52:54:00:d8:65:c9'/>
- <source bridge='br0'/>
- </interface>
- <input type='mouse' bus='ps2'/>
- <graphics type='vnc' port='-1' listen='127.0.0.1'/>
- </devices>
- </domain>
- ]]>
- </programlisting>
- <important>
- <para>
- Be careful in the choice of initial memory allocation, since
- too low a value may cause mysterious crashes and installation
- failures. Some operating systems need as much as 600 MB of memory
- for initial installation, though this can often be reduced
- post-install.
- </para>
- </important>
-
- <section id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Provisioning-ISO">
- <title>CDROM/ISO image provisioning</title>
+ <section id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Provisioning-Provisioning_Techniques">
+ <title>New Guest Domain Provisioning Techniques</title>
<para>
- All full virtualization technologies have support for emulating
- a CDROM device in a guest domain, making this an obvious choice
- for provisioning new guest domains. It is, however, fairly rare
- to find a hypervisor which provides CDROM devices for paravirtualized
- guests.
+ This section will first illustrate two configurations that
+ allow for a provisioning approach that is comparable to those
+ used for physical machines. It then outlines a third option
+ which is specific to virtualized hardware, but has some
+ interesting benefits. For the purposes of illustration, the
+ examples that follow will use an XML configuration that sets
+ up a KVM fully virtualized guest, with a single disk and
+ network interface and a video card using VNC for display.
</para>
- <para>
- The first obvious change required to the XML configuration to
- support CDROM installation, is to add a CDROM device. A guest
- domains' CDROM device can be pointed to either a host CDROM
- device, or to a ISO image file. The next change is to determine
- what the BIOS boot order should be, with there being two
- possible options. If the hard disk is listed ahead of the
- CDROM device, then the CDROM media won't be booted unless
- the first boot sector on the hard disk is blank. If the
- CDROM device is listed ahead of the hard disk, then it will
- be necessary to alter the guest config after install to
- make it boot off the installed disk. While both can be made
- to work, the first option is easiest to implement.
- </para>
+ <programlisting language="XML"><xi:include href="extras/Domains-Example-9.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ <important>
+ <para>
+ Be careful in the choice of initial memory allocation, since
+ too low a value may cause mysterious crashes and installation
+ failures. Some operating systems need as much as 600 MB of memory
+ for initial installation, though this can often be reduced
+ post-install.
+ </para>
+ </important>
- <para>
- The guest configuration shown earlier would have the following
- XML chunk inserted:
- </para>
+ <section id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Provisioning-ISO">
+ <title>CDROM/ISO image provisioning</title>
- <programlisting>
- <![CDATA[
- <os>
- <type arch='x86_64' machine='pc'>hvm</type>
- <boot dev='hd'/>
- <boot dev='cdrom'/>
- </os>
- ]]>
- </programlisting>
+ <para>
+ All full virtualization technologies have support for emulating
+ a CDROM device in a guest domain, making this an obvious choice
+ for provisioning new guest domains. It is, however, fairly rare
+ to find a hypervisor which provides CDROM devices for paravirtualized
+ guests.
+ </para>
- <para>
- NB, this assumes the hard disk boot sector is blank initially,
- so that the first boot attempt falls through to the CD-ROM drive.
- It will also need a CD-ROM drive device added
- </para>
+ <para>
+ The first obvious change required to the XML configuration to
+ support CDROM installation, is to add a CDROM device. A guest
+ domains' CDROM device can be pointed to either a host CDROM
+ device, or to a ISO image file. The next change is to determine
+ what the BIOS boot order should be, with there being two
+ possible options. If the hard disk is listed ahead of the
+ CDROM device, then the CDROM media won't be booted unless
+ the first boot sector on the hard disk is blank. If the
+ CDROM device is listed ahead of the hard disk, then it will
+ be necessary to alter the guest config after install to
+ make it boot off the installed disk. While both can be made
+ to work, the first option is easiest to implement.
+ </para>
- <programlisting>
- <![CDATA[
- <disk type='file' device='cdrom'>
- <source file='/var/lib/libvirt/images/rhel5-x86_64-dvd.iso'/>
- <target dev='hdc' bus='ide'/>
- </disk>
- ]]>
- </programlisting>
+ <para>
+ The guest configuration shown earlier would have the following
+ XML chunk inserted:
+ </para>
- <para>
- With the configuration determined, it is now possible
- to provision the guest. This is an easy process, simply
- requiring a persistent guest to be defined, and then
- booted.
- </para>
+ <programlisting language="XML"><xi:include href="extras/Domains-Example-10.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
- <programlisting>
- <![CDATA[
- const char *xml = "<domain>....</domain>";
- virDomainPtr dom;
+ <para>
+ NB, this assumes the hard disk boot sector is blank initially,
+ so that the first boot attempt falls through to the CD-ROM drive.
+ It will also need a CD-ROM drive device added.
+ </para>
- dom = virDomainDefineXML(conn, xml);
- if (!dom) {
- fprintf(stderr, "Unable to define persistent guest configuration");
- return;
- }
+ <programlisting language="XML"><xi:include href="extras/Domains-Example-11.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
- if (virDomainCreate(dom) < 0) {
- fprintf(stderr, "Unable to boot guest configuration");
- }
- ]]>
- </programlisting>
+ <para>
+ With the configuration determined, it is now possible
+ to provision the guest. This is an easy process, simply
+ requiring a persistent guest to be defined, and then
+ booted.
+ </para>
- <para>
- If it was not possible to guarantee that the boot
- sector of the hard disk is blank, then provisioning
- would have been a two step process. First a transient
- guest would have been booted using CD-ROM drive as the
- primary boot device. Once that completed, then
- a persistent configuration for the guest would be
- defined to boot off the hard disk.
- </para>
+ <example>
+ <title>Defining and Booting a Persistent Guest Domain</title>
+ <programlisting language="Python"><xi:include href="extras/Domains-Example-12.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </example>
- </section>
+ <para>
+ If it was not possible to guarantee that the boot
+ sector of the hard disk is blank, then provisioning
+ would have been a two step process. First a transient
+ guest would have been booted using CD-ROM drive as the
+ primary boot device. Once that completed, then
+ a persistent configuration for the guest would be
+ defined to boot off the hard disk.
+ </para>
- <section id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Provisioning-PXE">
- <title>PXE boot provisioning</title>
+ </section>
- <para>
- Some newer full virtualization technologies provide a BIOS that
- is able to use the PXE boot protocol to boot of the network. If
- an environment already has a PXE boot provisioning server deployed,
- this is a desirable method to use for guest domains.
- </para>
+ <section id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Provisioning-PXE">
+ <title>PXE Boot Provisioning</title>
- <para>
- PXE booting a guest obviously requires that the guest has a
- network device configured. The LAN that this network card is
- attached to, also needs a PXE / TFTP server available.
- The next change is to determine
- what the BIOS boot order should be, with there being two
- possible options. If the hard disk is listed ahead of the
- network device, then the network card won't PXE boot unless
- the first boot sector on the hard disk is blank. If the
- network device is listed ahead of the hard disk, then it will
- be necessary to alter the guest config after install to
- make it boot off the installed disk. While both can be made
- to work, the first option is easiest to implement.
- </para>
+ <para>
+ Some newer full virtualization technologies provide a BIOS that
+ is able to use the PXE boot protocol to boot off the network. If
+ an environment already has a PXE boot provisioning server deployed,
+ this is a desirable method to use for guest domains.
+ </para>
- <para>
- The guest configuration shown earlier would have the following
- XML chunk inserted:
- </para>
+ <para>
+ PXE booting a guest obviously requires that the guest has a
+ network device configured. The LAN that this network card is
+ attached to, also needs a PXE / TFTP server available.
+ The next change is to determine
+ what the BIOS boot order should be, with there being two
+ possible options. If the hard disk is listed ahead of the
+ network device, then the network card won't PXE boot unless
+ the first boot sector on the hard disk is blank. If the
+ network device is listed ahead of the hard disk, then it will
+ be necessary to alter the guest config after install to
+ make it boot off the installed disk. While both can be made
+ to work, the first option is easiest to implement.
+ </para>
- <programlisting>
- <![CDATA[
- <os>
- <type arch='x86_64' machine='pc'>hvm</type>
- <boot dev='hd'/>
- <boot dev='network'/>
- </os>
- ]]>
- </programlisting>
+ <para>
+ The guest configuration shown earlier would have the following
+ XML chunk inserted:
+ </para>
- <para>
- NB, this assumes the hard disk boot sector is blank initially,
- so that the first boot attempt falls through to the NIC.
- With the configuration determined, it is now possible
- to provision the guest. This is an easy process, simply
- requiring a persistent guest to be defined, and then
- booted.
- </para>
+ <programlisting language="XML"><xi:include href="extras/Domains-Example-13.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
- <programlisting>
- <![CDATA[
- const char *xml = "<domain>....</domain>";
- virDomainPtr dom;
+ <para>
+ NB, this assumes the hard disk boot sector is blank initially,
+ so that the first boot attempt falls through to the NIC.
+ With the configuration determined, it is now possible
+ to provision the guest. This is an easy process, simply
+ requiring a persistent guest to be defined, and then
+ booted.
+ </para>
- dom = virDomainDefineXML(conn, xml);
- if (!dom) {
- fprintf(stderr, "Unable to define persistent guest configuration");
- return;
- }
+ <example>
+ <title>PXE Boot Provisioning</title>
+ <programlisting language="Python"><xi:include href="extras/Domains-Example-14.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </example>
- if (virDomainCreate(dom) < 0) {
- fprintf(stderr, "Unable to boot guest configuration");
- }
- ]]>
- </programlisting>
+ <para>
+ If it was not possible to guarantee that the boot
+ sector of the hard disk is blank, then provisioning
+ would have been a two step process. First a transient
+ guest would have been booted using network as the
+ primary boot device. Once that completed, then
+ a persistent configuration for the guest would be
+ defined to boot off the hard disk.
+ </para>
+ </section>
- <para>
- If it was not possible to guarantee that the boot
- sector of the hard disk is blank, then provisioning
- would have been a two step process. First a transient
- guest would have been booted using network as the
- primary boot device. Once that completed, then
- a persistent configuration for the guest would be
- defined to boot off the hard disk.
- </para>
- </section>
+ <section id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Provisioning-Kernel">
+ <title>Direct kernel boot provisioning</title>
- <section id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Provisioning-Kernel">
- <title>Direct kernel boot provisioning</title>
+ <para>
+ Paravirtualization technologies emulate a fairly restrictive
+ set of hardware, often making it impossible to use the provisioning
+ options just outlined. For such scenarios it is often possible to
+ boot a new guest domain directly from an kernel and initrd image
+ stored on the host file system. This has one interesting advantage,
+ which is that it is possible to directly set kernel command line
+ boot arguments, making it very easy to do fully automated
+ installation. This advantage can be compelling enough that this
+ technique is used even for fully virtualized guest domains with
+ CD-ROM drive/PXE support.
+ </para>
- <para>
- Paravirtualization technologies emulate a fairly restrictive
- set of hardware, often making it impossible to use the provisioning
- options just outlined. For such scenarios it is often possible to
- boot a new guest domain directly from an kernel and initrd image
- stored on the host file system. This has one interesting advantage,
- which is that it is possible to directly set kernel command line
- boot arguments, making it very easy to do fully automated
- installation. This advantage can be compelling enough that this
- technique is used even for fully virtualized guest domains with
- CD-ROM drive/PXE support.
- </para>
+ <para>
+ The one complication with direct kernel booting is that provisioning
+ becomes a two step process. For the first step, it is necessary to
+ configure the guest XML configuration to point to a kernel/initrd.
+ </para>
- <para>
- The one complication with direct kernel booting is that provisioning
- becomes a two step process. For the first step, it is necessary to
- configure the guest XML configuration to point to a kernel/initrd.
- </para>
+ <programlisting>
+ <![CDATA[
+ <os>
+ <type arch='x86_64' machine='pc'>hvm</type>
+ <kernel>/var/lib/libvirt/boot/f11-x86_64-vmlinuz</kernel>
+ <initrd>/var/lib/libvirt/boot/f11-x86_64-initrd.img</initrd>
+ <cmdline>method=http://download.fedoraproject.org/pub/fedora/linux/releases/11/x86... console=ttyS0 console=tty</cmdline>
+ </os>
+ ]]>
+ </programlisting>
- <programlisting>
- <![CDATA[
- <os>
- <type arch='x86_64' machine='pc'>hvm</type>
- <kernel>/var/lib/libvirt/boot/f11-x86_64-vmlinuz</kernel>
- <initrd>/var/lib/libvirt/boot/f11-x86_64-initrd.img</initrd>
- <cmdline>method=http://download.fedoraproject.org/pub/fedora/linux/releases/11/x86... console=ttyS0 console=tty</cmdline>
- </os>
- ]]>
- </programlisting>
+ <para>
+ Notice how the kernel command line provides the URL of download
+ site containing the distro install tree matching the kernel/initrd.
+ This allows the installer to automatically download all its resources
+ without prompting the user for install URL. It could also be used to
+ provide a kickstart file for completely unattended installation.
+ Finally, this command line also tells the kernel to activate both
+ the first serial port and the VGA card as consoles, with the latter
+ being the default. Having kernel messages duplicated on the serial
+ port in this manner can be a useful debugging avenue. Of course
+ valid command line arguments vary according to the particular kernel
+ being booted. Consult the kernel vendor/distributor's documentation
+ for valid options.
+ </para>
- <para>
- Notice how the kernel command line provides the URL of download
- site containing the distro install tree matching the kernel/initrd.
- This allows the installer to automatically download all its resources
- without prompting the user for install URL. It could also be used to
- provide a kickstart file for completely unattended installation.
- Finally, this command line also tells the kernel to activate both
- the first serial port and the VGA card as consoles, with the latter
- being the default. Having kernel messages duplicated on the serial
- port in this manner can be a useful debugging avenue. Of course
- valid command line arguments vary according to the particular kernel
- being booted. Consult the kernel vendor/distributor's documentation
- for valid options.
- </para>
+ <para>
+ The last XML configuration detail before starting the guest, is to
+ change the 'on_reboot' element action to be 'destroy'. This ensures
+ that when the guest installer finishes and requests a reboot, the
+ guest is instead powered off. This allows the management application
+ to change the configuration to make it boot off, just installed, the
+ hard disk again. The provisioning process can be started now by
+ creating a transient guest with the first XML configuration
+ </para>
- <para>
- The last XML configuration detail before starting the guest, is to
- change the 'on_reboot' element action to be 'destroy'. This ensures
- that when the guest installer finishes and requests a reboot, the
- guest is instead powered off. This allows the management application
- to change the configuration to make it boot off, just installed, the
- hard disk again. The provisioning process can be started now by
- creating a transient guest with the first XML configuration
- </para>
+ <programlisting>
+ <![CDATA[
+ const char *xml = "<domain>....</domain>";
+ virDomainPtr dom;
- <programlisting>
- <![CDATA[
- const char *xml = "<domain>....</domain>";
- virDomainPtr dom;
+ dom = virDomainCreateXML(conn, xml);
+ if (!dom) {
+ fprintf(stderr, "Unable to boot transient guest configuration");
+ return;
+ }
+ ]]>
+ </programlisting>
- dom = virDomainCreateXML(conn, xml);
- if (!dom) {
- fprintf(stderr, "Unable to boot transient guest configuration");
- return;
- }
- ]]>
- </programlisting>
+ <para>
+ Once this guest shuts down, the second phase of the provisioning
+ process can be started. For this phase, the 'OS' element will
+ have the kernel/initrd/cmdline elements removed, and replaced
+ by either a reference to a host side bootloader, or a BIOS
+ boot setup. The former is used for Xen paravirtualized guests,
+ while the latter is used for fully virtualized guests.
+ </para>
- <para>
- Once this guest shuts down, the second phase of the provisioning
- process can be started. For this phase, the 'OS' element will
- have the kernel/initrd/cmdline elements removed, and replaced
- by either a reference to a host side bootloader, or a BIOS
- boot setup. The former is used for Xen paravirtualized guests,
- while the latter is used for fully virtualized guests.
- </para>
+ <para>
+ The phase 2 configuration for a Xen paravirtualized guest
+ would thus look like:
+ </para>
- <para>
- The phase 2 configuration for a Xen paravirtualized guest
- would thus look like:
- </para>
+ <programlisting>
+ <![CDATA[
+ <bootloader>/usr/bin/pygrub</bootloader>
+ <os>
+ <type arch='x86_64' machine='pc'>xen</type>
+ </os>
+ ]]>
+ </programlisting>
- <programlisting>
- <![CDATA[
- <bootloader>/usr/bin/pygrub</bootloader>
- <os>
- <type arch='x86_64' machine='pc'>xen</type>
- </os>
- ]]>
- </programlisting>
+ <para>
+ while a fully-virtualized guest would use:
+ </para>
- <para>
- while a fully-virtualized guest would use:
- </para>
+ <programlisting>
+ <![CDATA[
+ <bootloader>/usr/bin/pygrub</bootloader>
+ <os>
+ <type arch='x86_64' machine='pc'>hvm</type>
+ <boot dev='hd'/>
+ </os>
+ ]]>
+ </programlisting>
- <programlisting>
- <![CDATA[
- <bootloader>/usr/bin/pygrub</bootloader>
- <os>
- <type arch='x86_64' machine='pc'>hvm</type>
- <boot dev='hd'/>
- </os>
- ]]>
- </programlisting>
+ <para>
+ With the second phase configuration determined, the guest can
+ be recreated, this time using a persistent configuration
+ </para>
- <para>
- With the second phase configuration determined, the guest can
- be recreated, this time using a persistent configuration
- </para>
+ <programlisting>
+ <![CDATA[
+ const char *xml = "<domain>....</domain>";
+ virDomainPtr dom;
- <programlisting>
- <![CDATA[
- const char *xml = "<domain>....</domain>";
- virDomainPtr dom;
-
- dom = virDomainCreateXML(conn, xml);
- if (!dom) {
- fprintf(stderr, "Unable to define persistent guest configuration\n");
- return;
- }
-
- if (virDomainCreate(dom) < 0) {
- fprintf(stderr, "Unable to boot persistent guest\n");
- return;
- }
-
- fprintf(stderr, "Guest provisoning complete, OS is running\n");
- ]]>
- </programlisting>
- </section>
+ dom = virDomainCreateXML(conn, xml);
+ if (!dom) {
+ fprintf(stderr, "Unable to define persistent guest configuration\n");
+ return;
+ }
+
+ if (virDomainCreate(dom) < 0) {
+ fprintf(stderr, "Unable to boot persistent guest\n");
+ return;
+ }
+
+ fprintf(stderr, "Guest provisoning complete, OS is running\n");
+ ]]>
+ </programlisting>
+ </section>
</section>
</section>
diff --git a/en-US/extras/Domains-Example-10.xml b/en-US/extras/Domains-Example-10.xml
new file mode 100644
index 0000000..b3a20da
--- /dev/null
+++ b/en-US/extras/Domains-Example-10.xml
@@ -0,0 +1,5 @@
+<os>
+ <type arch='x86_64' machine='pc'>hvm</type>
+ <boot dev='hd'/>
+ <boot dev='cdrom'/>
+</os>
diff --git a/en-US/extras/Domains-Example-11.xml b/en-US/extras/Domains-Example-11.xml
new file mode 100644
index 0000000..bd0f139
--- /dev/null
+++ b/en-US/extras/Domains-Example-11.xml
@@ -0,0 +1,4 @@
+<disk type='file' device='cdrom'>
+ <source file='/var/lib/libvirt/images/rhel5-x86_64-dvd.iso'/>
+ <target dev='hdc' bus='ide'/>
+</disk>
diff --git a/en-US/extras/Domains-Example-12.py b/en-US/extras/Domains-Example-12.py
new file mode 100644
index 0000000..9e9ce00
--- /dev/null
+++ b/en-US/extras/Domains-Example-12.py
@@ -0,0 +1,25 @@
+# Example-12.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.defineXML(xmlconfig, 0)
+if dom == None:
+ print('Failed to define a domain from an XML definition.', file=sys.stderr)
+ exit(1)
+
+if dom.create(dom) < 0:
+ print('Can not boot guest domain.', file=sys.stderr)
+ exit(1)
+
+print('Guest '+dom.name()+' has booted', file=sys.stderr)
+
+conn.close()
+exit(0)
diff --git a/en-US/extras/Domains-Example-13.xml b/en-US/extras/Domains-Example-13.xml
new file mode 100644
index 0000000..1dd3b73
--- /dev/null
+++ b/en-US/extras/Domains-Example-13.xml
@@ -0,0 +1,5 @@
+<os>
+ <type arch='x86_64' machine='pc'>hvm</type>
+ <boot dev='hd'/>
+ <boot dev='network'/>
+</os>
diff --git a/en-US/extras/Domains-Example-14.py b/en-US/extras/Domains-Example-14.py
new file mode 100644
index 0000000..a9a9579
--- /dev/null
+++ b/en-US/extras/Domains-Example-14.py
@@ -0,0 +1,25 @@
+# Example-14.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.defineXML(xmlconfig, 0)
+if dom == None:
+ print('Failed to define a domain from an XML definition.', file=sys.stderr)
+ exit(1)
+
+if dom.create(dom) < 0:
+ print('Can not boot guest domain.', file=sys.stderr)
+ exit(1)
+
+print('Guest '+dom.name()+' has booted', file=sys.stderr)
+
+conn.close()
+exit(0)
diff --git a/en-US/extras/Domains-Example-9.xml b/en-US/extras/Domains-Example-9.xml
new file mode 100644
index 0000000..7191ae4
--- /dev/null
+++ b/en-US/extras/Domains-Example-9.xml
@@ -0,0 +1,25 @@
+<domain type='kvm'>
+ <name>demo</name>
+ <uuid>c7a5fdbd-cdaf-9455-926a-d65c16db1809</uuid>
+ <memory>500000</memory>
+ <vcpu>1</vcpu>
+ .... the <os> block will vary per approach ...
+ <clock offset='utc'/>
+ <on_poweroff>destroy</on_poweroff>
+ <on_reboot>restart</on_reboot>
+ <on_crash>destroy</on_crash>
+ <devices>
+ <emulator>/usr/bin/qemu-kvm</emulator>
+ <disk type='file' device='disk'>
+ <source file='/var/lib/libvirt/images/demo.img'/>
+ <driver name='qemu' type='raw'/>
+ <target dev='hda'/>
+ </disk>
+ <interface type='bridge'>
+ <mac address='52:54:00:d8:65:c9'/>
+ <source bridge='br0'/>
+ </interface>
+ <input type='mouse' bus='ps2'/>
+ <graphics type='vnc' port='-1' listen='127.0.0.1'/>
+ </devices>
+</domain>
8 years, 9 months
[libvirt_application_development_guide_using_python] Updated Gurst Domains chapter. - Updated the section Defining and Booting a Persistent Guest Domain
by David Ashley
commit f8c9886fd8a0f39f9b152acd4b0fbbc131b827c0
Author: W. David Ashley <w.david.ashley(a)gmail.com>
Date: Tue Jun 30 21:16:19 2015 -0500
Updated Gurst Domains chapter.
- Updated the section Defining and Booting a Persistent Guest Domain.
- Added Domains-Example-8.py for the Provisioning section
en-US/Guest_Domains.xml | 46 ++++++++++--------------------------
en-US/extras/Domains-Example-8.py | 25 ++++++++++++++++++++
2 files changed, 38 insertions(+), 33 deletions(-)
---
diff --git a/en-US/Guest_Domains.xml b/en-US/Guest_Domains.xml
index a02237a..dc79b5e 100644
--- a/en-US/Guest_Domains.xml
+++ b/en-US/Guest_Domains.xml
@@ -278,8 +278,8 @@
</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>
+ <title>Provisioning a Transient Guest Domain</title>
+ <programlisting language="Python"><xi:include href="extras/Domains-Example-7.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
</example>
<para>
@@ -298,44 +298,24 @@
</section>
<section id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Provisioning-apis-persistent">
- <title>Defining and booting a persistent guest domain</title>
+ <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.
+ 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>virDomain</literal> object obtained from defining the guest,
+ can then be used to boot it.
</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);
- ]]>
- </programlisting>
+ <example>
+ <title>Defining and Booting a Persistent Guest Domain</title>
+ <programlisting language="Python"><xi:include href="extras/Domains-Example-8.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </example>
</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-8.py b/en-US/extras/Domains-Example-8.py
new file mode 100644
index 0000000..aa2cda0
--- /dev/null
+++ b/en-US/extras/Domains-Example-8.py
@@ -0,0 +1,25 @@
+# Example-8.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.defineXML(xmlconfig, 0)
+if dom == None:
+ print('Failed to define a domain from an XML definition.', file=sys.stderr)
+ exit(1)
+
+if dom.create(dom) < 0:
+ print('Can not boot guest domain.', file=sys.stderr)
+ exit(1)
+
+print('Guest '+dom.name()+' has booted', file=sys.stderr)
+
+conn.close()
+exit(0)
8 years, 9 months