[libvirt_application_development_guide_using_python] Error handling chapter - moved text to examples 1-4 - corrected spelling errors
by David Ashley
commit aa668cae87fb1704bb7362b066e63a64bdb32210
Author: W. David Ashley <w.david.ashley(a)gmail.com>
Date: Tue Aug 4 09:45:53 2015 -0500
Error handling chapter
- moved text to examples 1-4
- corrected spelling errors
en-US/Error_Handling.xml | 223 +------------------------------
en-US/extras/ErrorHandling-Example-1.py | 59 ++++++++
en-US/extras/ErrorHandling-Example-2.py | 93 +++++++++++++
en-US/extras/ErrorHandling-Example-3.py | 61 +++++++++
en-US/extras/ErrorHandling-Example-4.py | 3 +
5 files changed, 223 insertions(+), 216 deletions(-)
---
diff --git a/en-US/Error_Handling.xml b/en-US/Error_Handling.xml
index 4f8d5d8..79259b3 100644
--- a/en-US/Error_Handling.xml
+++ b/en-US/Error_Handling.xml
@@ -16,65 +16,10 @@
that can be subclassed to add additional functionality when raising a libvirt exception.
A partial definition of the <literal>libvirtError</literal> class definition looks like:
</para>
- <programlisting language="Python"><![CDATA[class libvirtError(Exception):
- def __init__(self, defmsg, conn=None, dom=None, net=None, pool=None, vol=None):
-
- # Never call virConnGetLastError().
- # virGetLastError() is now thread local
- err = virGetLastError()
- if err is None:
- msg = defmsg
- else:
- msg = err[2]
-
- Exception.__init__(self, msg)
-
- self.err = err
-
- def get_error_code(self):
- if self.err is None:
- return None
- return self.err[0]
-
- def get_error_domain(self):
- if self.err is None:
- return None
- return self.err[1]
-
- def get_error_message(self):
- if self.err is None:
- return None
- return self.err[2]
-
- def get_error_level(self):
- if self.err is None:
- return None
- return self.err[3]
-
- def get_str1(self):
- if self.err is None:
- return None
- return self.err[4]
-
- def get_str2(self):
- if self.err is None:
- return None
- return self.err[5]
-
- def get_str3(self):
- if self.err is None:
- return None
- return self.err[6]
-
- def get_int1(self):
- if self.err is None:
- return None
- return self.err[7]
-
- def get_int2(self):
- if self.err is None:
- return None
- return self.err[8]]]></programlisting>
+ <example>
+ <title>Libvirt module libvirtError class definition</title>
+ <programlisting language="Python"><xi:include href="extras/ErrorHandling-Example-1.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </example>
<para>
There are a few things to note about this definition. The first is that you can instantiate this class
by using the Python <literal>raise</literal> statement. Actually this is not of much use unless
@@ -88,99 +33,7 @@
Some of the higher numbered entries from this list my not be available in your Python
libvirt module.
</para>
- <programlisting language="Python"><![CDATA[VIR_ERR_OK = 0
-VIR_ERR_INTERNAL_ERROR = 1 # internal error
-VIR_ERR_NO_MEMORY = 2 # memory allocation failure
-VIR_ERR_NO_SUPPORT = 3 # no support for this function
-VIR_ERR_UNKNOWN_HOST = 4 # could not resolve hostname
-VIR_ERR_NO_CONNECT = 5 # can not connect to hypervisor
-VIR_ERR_INVALID_CONN = 6 # invalid connection object
-VIR_ERR_INVALID_DOMAIN = 7 # invalid domain object
-VIR_ERR_INVALID_ARG = 8 # invalid function argument
-VIR_ERR_OPERATION_FAILED = 9 # a command to hypervisor failed
-VIR_ERR_GET_FAILED = 10 # a HTTP GET command to failed
-VIR_ERR_POST_FAILED = 11 # a HTTP POST command to failed
-VIR_ERR_HTTP_ERROR = 12 # unexpected HTTP error code
-VIR_ERR_SEXPR_SERIAL = 13 # failure to serialize an S-Expr
-VIR_ERR_NO_XEN = 14 # could not open Xen hypervisor control
-VIR_ERR_XEN_CALL = 15 # failure doing an hypervisor call
-VIR_ERR_OS_TYPE = 16 # unknown OS type
-VIR_ERR_NO_KERNEL = 17 # missing kernel information
-VIR_ERR_NO_ROOT = 18 # missing root device information
-VIR_ERR_NO_SOURCE = 19 # missing source device information
-VIR_ERR_NO_TARGET = 20 # missing target device information
-VIR_ERR_NO_NAME = 21 # missing domain name information
-VIR_ERR_NO_OS = 22 # missing domain OS information
-VIR_ERR_NO_DEVICE = 23 # missing domain devices information
-VIR_ERR_NO_XENSTORE = 24 # could not open Xen Store control
-VIR_ERR_DRIVER_FULL = 25 # too many drivers registered
-VIR_ERR_CALL_FAILED = 26 # not supported by the drivers (DEPRECATED)
-VIR_ERR_XML_ERROR = 27 # an XML description is not well formed or broken
-VIR_ERR_DOM_EXIST = 28 # the domain already exist
-VIR_ERR_OPERATION_DENIED = 29 # operation forbidden on read-only connections
-VIR_ERR_OPEN_FAILED = 30 # failed to open a conf file
-VIR_ERR_READ_FAILED = 31 # failed to read a conf file
-VIR_ERR_PARSE_FAILED = 32 # failed to parse a conf file
-VIR_ERR_CONF_SYNTAX = 33 # failed to parse the syntax of a conf file
-VIR_ERR_WRITE_FAILED = 34 # failed to write a conf file
-VIR_ERR_XML_DETAIL = 35 # detail of an XML error
-VIR_ERR_INVALID_NETWORK = 36 # invalid network object
-VIR_ERR_NETWORK_EXIST = 37 # the network already exist
-VIR_ERR_SYSTEM_ERROR = 38 # general system call failure
-VIR_ERR_RPC = 39 # some sort of RPC error
-VIR_ERR_GNUTLS_ERROR = 40 # error from a GNUTLS call
-VIR_WAR_NO_NETWORK = 41 # failed to start network
-VIR_ERR_NO_DOMAIN = 42 # domain not found or unexpectedly disappeared
-VIR_ERR_NO_NETWORK = 43 # network not found
-VIR_ERR_INVALID_MAC = 44 # invalid MAC address
-VIR_ERR_AUTH_FAILED = 45 # authentication failed
-VIR_ERR_INVALID_STORAGE_POOL = 46 # invalid storage pool object
-VIR_ERR_INVALID_STORAGE_VOL = 47 # invalid storage vol object
-VIR_WAR_NO_STORAGE = 48 # failed to start storage
-VIR_ERR_NO_STORAGE_POOL = 49 # storage pool not found
-VIR_ERR_NO_STORAGE_VOL = 50 # storage pool not found
-VIR_WAR_NO_NODE = 51 # failed to start node driver
-VIR_ERR_INVALID_NODE_DEVICE = 52 # invalid node device object
-VIR_ERR_NO_NODE_DEVICE = 53 # node device not found
-VIR_ERR_NO_SECURITY_MODEL = 54 # security model not found
-VIR_ERR_OPERATION_INVALID = 55 # operation is not applicable at this time
-VIR_WAR_NO_INTERFACE = 56 # failed to start interface driver
-VIR_ERR_NO_INTERFACE = 57 # interface driver not running
-VIR_ERR_INVALID_INTERFACE = 58 # invalid interface object
-VIR_ERR_MULTIPLE_INTERFACES = 59 # more than one matching interface found
-VIR_WAR_NO_NWFILTER = 60 # failed to start nwfilter driver
-VIR_ERR_INVALID_NWFILTER = 61 # invalid nwfilter object
-VIR_ERR_NO_NWFILTER = 62 # nw filter pool not found
-VIR_ERR_BUILD_FIREWALL = 63 # nw filter pool not found
-VIR_WAR_NO_SECRET = 64 # failed to start secret storage
-VIR_ERR_INVALID_SECRET = 65 # invalid secret
-VIR_ERR_NO_SECRET = 66 # secret not found
-VIR_ERR_CONFIG_UNSUPPORTED = 67 # unsupported configuration construct
-VIR_ERR_OPERATION_TIMEOUT = 68 # timeout occurred during operation
-VIR_ERR_MIGRATE_PERSIST_FAILED = 69 # a migration worked, but making the VM persist on the dest host failed
-VIR_ERR_HOOK_SCRIPT_FAILED = 70 # a synchronous hook script failed
-VIR_ERR_INVALID_DOMAIN_SNAPSHOT = 71 # invalid domain snapshot
-VIR_ERR_NO_DOMAIN_SNAPSHOT = 72 # domain snapshot was not found
-VIR_ERR_INVALID_STREAM = 73 # invalid i/o stream
-VIR_ERR_ARGUMENT_UNSUPPORTED = 74 # an argument was unsupported
-VIR_ERR_STORAGE_PROBE_FAILED = 75 # a storage probe failed
-VIR_ERR_STORAGE_POOL_BUILT = 76
-VIR_ERR_SNAPSHOT_REVERT_RISKY = 77
-VIR_ERR_OPERATION_ABORTED = 78 # the operation was aborted
-VIR_ERR_AUTH_CANCELLED = 79
-VIR_ERR_NO_DOMAIN_METADATA = 80 # no domain metadata was found
-VIR_ERR_MIGRATE_UNSAFE = 81
-VIR_ERR_OVERFLOW = 82 # an overflow situation was detected
-VIR_ERR_BLOCK_COPY_ACTIVE = 83
-VIR_ERR_OPERATION_UNSUPPORTED = 84 # the operation was unsupported
-VIR_ERR_SSH = 85 # an ssh error was detected
-VIR_ERR_AGENT_UNRESPONSIVE = 86 # an agent timeout was detected
-VIR_ERR_RESOURCE_BUSY = 87
-VIR_ERR_ACCESS_DENIED = 88
-VIR_ERR_DBUS_SERVICE = 89
-VIR_ERR_STORAGE_VOL_EXIST = 90
-VIR_ERR_CPU_INCOMPATIBLE = 91
-VIR_ERR_XML_INVALID_SCHEMA = 92]]></programlisting>
+ <programlisting language="Python"><xi:include href="extras/ErrorHandling-Example-2.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
<para>
The method <literal>get_error_domain</literal> is named that for legacy
reasons, but really represents which part of libvirt generated the
@@ -188,67 +41,7 @@ VIR_ERR_XML_INVALID_SCHEMA = 92]]></programlisting>
Some of the higher numbered entries from this list my not be available in your Python
libvirt module. The full list is:
</para>
- <programlisting language="Python"><![CDATA[VIR_FROM_NONE = 0
-VIR_FROM_XEN = 1 # Error at Xen hypervisor layer
-VIR_FROM_XEND = 2 # Error at connection with xend daemon
-VIR_FROM_XENSTORE = 3 # Error at connection with xen store
-VIR_FROM_SEXPR = 4 # Error in the S-Expression code
-VIR_FROM_XML = 5 # Error in the XML code
-VIR_FROM_DOM = 6 # Error when operating on a domain
-VIR_FROM_RPC = 7 # Error in the XML-RPC code
-VIR_FROM_PROXY = 8 # Error in the proxy code
-VIR_FROM_CONF = 9 # Error in the configuration file handling
-VIR_FROM_QEMU = 10 # Error at the QEMU daemon
-VIR_FROM_NET = 11 # Error when operating on a network
-VIR_FROM_TEST = 12 # Error from test driver
-VIR_FROM_REMOTE = 13 # Error from remote driver
-VIR_FROM_OPENVZ = 14 # Error from OpenVZ driver
-VIR_FROM_XENXM = 15 # Error at Xen XM layer
-VIR_FROM_STATS_LINUX = 16 # Error in the Linux Stats code
-VIR_FROM_LXC = 17 # Error from Linux Container driver
-VIR_FROM_STORAGE = 18 # Error from storage driver
-VIR_FROM_NETWORK = 19 # Error from network config
-VIR_FROM_DOMAIN = 20 # Error from domain config
-VIR_FROM_UML = 21 # Error at the UML driver
-VIR_FROM_NODEDEV = 22 # Error from node device monitor
-VIR_FROM_XEN_INOTIFY = 23 # Error from xen inotify layer
-VIR_FROM_SECURITY = 24 # Error from security framework
-VIR_FROM_VBOX = 25 # Error from VirtualBox driver
-VIR_FROM_INTERFACE = 26 # Error when operating on an interface
-VIR_FROM_ONE = 27 # Error from OpenNebula driver
-VIR_FROM_ESX = 28 # Error from ESX driver
-VIR_FROM_PHYP = 29 # Error from IBM power hypervisor
-VIR_FROM_SECRET = 30 # Error from secret storage
-VIR_FROM_CPU = 31 # Error from CPU driver
-VIR_FROM_XENAPI = 32 # Error from XenAPI
-VIR_FROM_NWFILTER = 33 # Error from network filter driver
-VIR_FROM_HOOK = 34 # Error from Synchronous hooks
-VIR_FROM_DOMAIN_SNAPSHOT = 35 # Error from domain snapshot
-VIR_FROM_AUDIT = 36
-VIR_FROM_SYSINFO = 37
-VIR_FROM_STREAMS = 38
-VIR_FROM_VMWARE = 39
-VIR_FROM_EVENT = 40
-VIR_FROM_LIBXL = 41
-VIR_FROM_LOCKING = 42
-VIR_FROM_HYPERV = 43
-VIR_FROM_CAPABILITIES = 44
-VIR_FROM_URI = 45
-VIR_FROM_AUTH = 46
-VIR_FROM_DBUS = 47
-VIR_FROM_PARALLELS = 48
-VIR_FROM_DEVICE = 49
-VIR_FROM_SSH = 50
-VIR_FROM_LOCKSPACE = 51
-VIR_FROM_INITCTL = 52
-VIR_FROM_IDENTITY = 53
-VIR_FROM_CGROUP = 54
-VIR_FROM_ACCESS = 55
-VIR_FROM_SYSTEMD = 56
-VIR_FROM_BHYVE = 57
-VIR_FROM_CRYPTO = 58
-VIR_FROM_FIREWALL = 59
-VIR_FROM_POLKIT = 60]]></programlisting>
+ <programlisting language="Python"><xi:include href="extras/ErrorHandling-Example-3.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
<para>
The method <literal>get_error_message</literal> is a human-readable string
describing the error.
@@ -258,9 +51,7 @@ VIR_FROM_POLKIT = 60]]></programlisting>
error. This is one of the data definition from the Python libvirt module.
The full list of levels is:
</para>
- <programlisting language="Python"><![CDATA[VIR_ERR_NONE = 0
-VIR_ERR_WARNING = 1 # A simple warning
-VIR_ERR_ERROR = 2 # An error]]></programlisting>
+ <programlisting language="Python"><xi:include href="extras/ErrorHandling-Example-4.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
<para>
The method <literal>get_error_str1</literal> gives extra human readable
information.
diff --git a/en-US/extras/ErrorHandling-Example-1.py b/en-US/extras/ErrorHandling-Example-1.py
new file mode 100644
index 0000000..b94d3fd
--- /dev/null
+++ b/en-US/extras/ErrorHandling-Example-1.py
@@ -0,0 +1,59 @@
+class libvirtError(exceptions.Exception)
+ def __init__(self, defmsg, conn=None, dom=None, net=None, pool=None, vol=None):
+
+ # Never call virGetLastError().
+ # virGetLastError() is now thread local
+ err = virGetLastError()
+ if err is None:
+ msg = defmsg
+ else:
+ msg = err[2]
+
+ Exception.__init__(self, msg)
+
+ self.err = err
+
+ def get_error_code(self):
+ if self.err is None:
+ return None
+ return self.err[0]
+
+ def get_error_domain(self):
+ if self.err is None:
+ return None
+ return self.err[1]
+
+ def get_error_message(self):
+ if self.err is None:
+ return None
+ return self.err[2]
+
+ def get_error_level(self):
+ if self.err is None:
+ return None
+ return self.err[3]
+
+ def get_str1(self):
+ if self.err is None:
+ return None
+ return self.err[4]
+
+ def get_str2(self):
+ if self.err is None:
+ return None
+ return self.err[5]
+
+ def get_str3(self):
+ if self.err is None:
+ return None
+ return self.err[6]
+
+ def get_int1(self):
+ if self.err is None:
+ return None
+ return self.err[7]
+
+ def get_int2(self):
+ if self.err is None:
+ return None
+ return self.err[8]
diff --git a/en-US/extras/ErrorHandling-Example-2.py b/en-US/extras/ErrorHandling-Example-2.py
new file mode 100644
index 0000000..4c7886f
--- /dev/null
+++ b/en-US/extras/ErrorHandling-Example-2.py
@@ -0,0 +1,93 @@
+VIR_ERR_OK = 0
+VIR_ERR_INTERNAL_ERROR = 1 # internal error
+VIR_ERR_NO_MEMORY = 2 # memory allocation failure
+VIR_ERR_NO_SUPPORT = 3 # no support for this function
+VIR_ERR_UNKNOWN_HOST = 4 # could not resolve hostname
+VIR_ERR_NO_CONNECT = 5 # can not connect to hypervisor
+VIR_ERR_INVALID_CONN = 6 # invalid connection object
+VIR_ERR_INVALID_DOMAIN = 7 # invalid domain object
+VIR_ERR_INVALID_ARG = 8 # invalid function argument
+VIR_ERR_OPERATION_FAILED = 9 # a command to hypervisor failed
+VIR_ERR_GET_FAILED = 10 # a HTTP GET command to failed
+VIR_ERR_POST_FAILED = 11 # a HTTP POST command to failed
+VIR_ERR_HTTP_ERROR = 12 # unexpected HTTP error code
+VIR_ERR_SEXPR_SERIAL = 13 # failure to serialize an S-Expr
+VIR_ERR_NO_XEN = 14 # could not open Xen hypervisor control
+VIR_ERR_XEN_CALL = 15 # failure doing an hypervisor call
+VIR_ERR_OS_TYPE = 16 # unknown OS type
+VIR_ERR_NO_KERNEL = 17 # missing kernel information
+VIR_ERR_NO_ROOT = 18 # missing root device information
+VIR_ERR_NO_SOURCE = 19 # missing source device information
+VIR_ERR_NO_TARGET = 20 # missing target device information
+VIR_ERR_NO_NAME = 21 # missing domain name information
+VIR_ERR_NO_OS = 22 # missing domain OS information
+VIR_ERR_NO_DEVICE = 23 # missing domain devices information
+VIR_ERR_NO_XENSTORE = 24 # could not open Xen Store control
+VIR_ERR_DRIVER_FULL = 25 # too many drivers registered
+VIR_ERR_CALL_FAILED = 26 # not supported by the drivers (DEPRECATED)
+VIR_ERR_XML_ERROR = 27 # an XML description is not well formed or broken
+VIR_ERR_DOM_EXIST = 28 # the domain already exist
+VIR_ERR_OPERATION_DENIED = 29 # operation forbidden on read-only connections
+VIR_ERR_OPEN_FAILED = 30 # failed to open a conf file
+VIR_ERR_READ_FAILED = 31 # failed to read a conf file
+VIR_ERR_PARSE_FAILED = 32 # failed to parse a conf file
+VIR_ERR_CONF_SYNTAX = 33 # failed to parse the syntax of a conf file
+VIR_ERR_WRITE_FAILED = 34 # failed to write a conf file
+VIR_ERR_XML_DETAIL = 35 # detail of an XML error
+VIR_ERR_INVALID_NETWORK = 36 # invalid network object
+VIR_ERR_NETWORK_EXIST = 37 # the network already exist
+VIR_ERR_SYSTEM_ERROR = 38 # general system call failure
+VIR_ERR_RPC = 39 # some sort of RPC error
+VIR_ERR_GNUTLS_ERROR = 40 # error from a GNUTLS call
+VIR_WAR_NO_NETWORK = 41 # failed to start network
+VIR_ERR_NO_DOMAIN = 42 # domain not found or unexpectedly disappeared
+VIR_ERR_NO_NETWORK = 43 # network not found
+VIR_ERR_INVALID_MAC = 44 # invalid MAC address
+VIR_ERR_AUTH_FAILED = 45 # authentication failed
+VIR_ERR_INVALID_STORAGE_POOL = 46 # invalid storage pool object
+VIR_ERR_INVALID_STORAGE_VOL = 47 # invalid storage vol object
+VIR_WAR_NO_STORAGE = 48 # failed to start storage
+VIR_ERR_NO_STORAGE_POOL = 49 # storage pool not found
+VIR_ERR_NO_STORAGE_VOL = 50 # storage pool not found
+VIR_WAR_NO_NODE = 51 # failed to start node driver
+VIR_ERR_INVALID_NODE_DEVICE = 52 # invalid node device object
+VIR_ERR_NO_NODE_DEVICE = 53 # node device not found
+VIR_ERR_NO_SECURITY_MODEL = 54 # security model not found
+VIR_ERR_OPERATION_INVALID = 55 # operation is not applicable at this time
+VIR_WAR_NO_INTERFACE = 56 # failed to start interface driver
+VIR_ERR_NO_INTERFACE = 57 # interface driver not running
+VIR_ERR_INVALID_INTERFACE = 58 # invalid interface object
+VIR_ERR_MULTIPLE_INTERFACES = 59 # more than one matching interface found
+VIR_WAR_NO_NWFILTER = 60 # failed to start nwfilter driver
+VIR_ERR_INVALID_NWFILTER = 61 # invalid nwfilter object
+VIR_ERR_NO_NWFILTER = 62 # nw filter pool not found
+VIR_ERR_BUILD_FIREWALL = 63 # nw filter pool not found
+VIR_WAR_NO_SECRET = 64 # failed to start secret storage
+VIR_ERR_INVALID_SECRET = 65 # invalid secret
+VIR_ERR_NO_SECRET = 66 # secret not found
+VIR_ERR_CONFIG_UNSUPPORTED = 67 # unsupported configuration construct
+VIR_ERR_OPERATION_TIMEOUT = 68 # timeout occurred during operation
+VIR_ERR_MIGRATE_PERSIST_FAILED = 69 # a migration worked, but making the VM persist on the dest host failed
+VIR_ERR_HOOK_SCRIPT_FAILED = 70 # a synchronous hook script failed
+VIR_ERR_INVALID_DOMAIN_SNAPSHOT = 71 # invalid domain snapshot
+VIR_ERR_NO_DOMAIN_SNAPSHOT = 72 # domain snapshot was not found
+VIR_ERR_INVALID_STREAM = 73 # invalid i/o stream
+VIR_ERR_ARGUMENT_UNSUPPORTED = 74 # an argument was unsupported
+VIR_ERR_STORAGE_PROBE_FAILED = 75 # a storage probe failed
+VIR_ERR_STORAGE_POOL_BUILT = 76
+VIR_ERR_SNAPSHOT_REVERT_RISKY = 77
+VIR_ERR_OPERATION_ABORTED = 78 # the operation was aborted
+VIR_ERR_AUTH_CANCELLED = 79
+VIR_ERR_NO_DOMAIN_METADATA = 80 # no domain metadata was found
+VIR_ERR_MIGRATE_UNSAFE = 81
+VIR_ERR_OVERFLOW = 82 # an overflow situation was detected
+VIR_ERR_BLOCK_COPY_ACTIVE = 83
+VIR_ERR_OPERATION_UNSUPPORTED = 84 # the operation was unsupported
+VIR_ERR_SSH = 85 # an ssh error was detected
+VIR_ERR_AGENT_UNRESPONSIVE = 86 # an agent timeout was detected
+VIR_ERR_RESOURCE_BUSY = 87
+VIR_ERR_ACCESS_DENIED = 88
+VIR_ERR_DBUS_SERVICE = 89
+VIR_ERR_STORAGE_VOL_EXIST = 90
+VIR_ERR_CPU_INCOMPATIBLE = 91
+VIR_ERR_XML_INVALID_SCHEMA = 92
diff --git a/en-US/extras/ErrorHandling-Example-3.py b/en-US/extras/ErrorHandling-Example-3.py
new file mode 100644
index 0000000..55ed4bc
--- /dev/null
+++ b/en-US/extras/ErrorHandling-Example-3.py
@@ -0,0 +1,61 @@
+VIR_FROM_NONE = 0
+VIR_FROM_XEN = 1 # Error at Xen hypervisor layer
+VIR_FROM_XEND = 2 # Error at connection with xend daemon
+VIR_FROM_XENSTORE = 3 # Error at connection with xen store
+VIR_FROM_SEXPR = 4 # Error in the S-Expression code
+VIR_FROM_XML = 5 # Error in the XML code
+VIR_FROM_DOM = 6 # Error when operating on a domain
+VIR_FROM_RPC = 7 # Error in the XML-RPC code
+VIR_FROM_PROXY = 8 # Error in the proxy code
+VIR_FROM_CONF = 9 # Error in the configuration file handling
+VIR_FROM_QEMU = 10 # Error at the QEMU daemon
+VIR_FROM_NET = 11 # Error when operating on a network
+VIR_FROM_TEST = 12 # Error from test driver
+VIR_FROM_REMOTE = 13 # Error from remote driver
+VIR_FROM_OPENVZ = 14 # Error from OpenVZ driver
+VIR_FROM_XENXM = 15 # Error at Xen XM layer
+VIR_FROM_STATS_LINUX = 16 # Error in the Linux Stats code
+VIR_FROM_LXC = 17 # Error from Linux Container driver
+VIR_FROM_STORAGE = 18 # Error from storage driver
+VIR_FROM_NETWORK = 19 # Error from network config
+VIR_FROM_DOMAIN = 20 # Error from domain config
+VIR_FROM_UML = 21 # Error at the UML driver
+VIR_FROM_NODEDEV = 22 # Error from node device monitor
+VIR_FROM_XEN_INOTIFY = 23 # Error from xen inotify layer
+VIR_FROM_SECURITY = 24 # Error from security framework
+VIR_FROM_VBOX = 25 # Error from VirtualBox driver
+VIR_FROM_INTERFACE = 26 # Error when operating on an interface
+VIR_FROM_ONE = 27 # Error from OpenNebula driver
+VIR_FROM_ESX = 28 # Error from ESX driver
+VIR_FROM_PHYP = 29 # Error from IBM power hypervisor
+VIR_FROM_SECRET = 30 # Error from secret storage
+VIR_FROM_CPU = 31 # Error from CPU driver
+VIR_FROM_XENAPI = 32 # Error from XenAPI
+VIR_FROM_NWFILTER = 33 # Error from network filter driver
+VIR_FROM_HOOK = 34 # Error from Synchronous hooks
+VIR_FROM_DOMAIN_SNAPSHOT = 35 # Error from domain snapshot
+VIR_FROM_AUDIT = 36
+VIR_FROM_SYSINFO = 37
+VIR_FROM_STREAMS = 38
+VIR_FROM_VMWARE = 39
+VIR_FROM_EVENT = 40
+VIR_FROM_LIBXL = 41
+VIR_FROM_LOCKING = 42
+VIR_FROM_HYPERV = 43
+VIR_FROM_CAPABILITIES = 44
+VIR_FROM_URI = 45
+VIR_FROM_AUTH = 46
+VIR_FROM_DBUS = 47
+VIR_FROM_PARALLELS = 48
+VIR_FROM_DEVICE = 49
+VIR_FROM_SSH = 50
+VIR_FROM_LOCKSPACE = 51
+VIR_FROM_INITCTL = 52
+VIR_FROM_IDENTITY = 53
+VIR_FROM_CGROUP = 54
+VIR_FROM_ACCESS = 55
+VIR_FROM_SYSTEMD = 56
+VIR_FROM_BHYVE = 57
+VIR_FROM_CRYPTO = 58
+VIR_FROM_FIREWALL = 59
+VIR_FROM_POLKIT = 60
diff --git a/en-US/extras/ErrorHandling-Example-4.py b/en-US/extras/ErrorHandling-Example-4.py
new file mode 100644
index 0000000..71ca6cd
--- /dev/null
+++ b/en-US/extras/ErrorHandling-Example-4.py
@@ -0,0 +1,3 @@
+VIR_ERR_NONE = 0
+VIR_ERR_WARNING = 1 # A simple warning
+VIR_ERR_ERROR = 2 # An error
8 years, 9 months
[libvirt_application_development_guide_using_python] Storage chapter - fixed spelling errors - this should finish the Storage chapter
by David Ashley
commit 4e968203c9bc5efadf60e38d12b3f728c2be22db
Author: W. David Ashley <w.david.ashley(a)gmail.com>
Date: Mon Aug 3 12:50:23 2015 -0500
Storage chapter
- fixed spelling errors
- this should finish the Storage chapter
en-US/Storage_Pools.xml | 14 +++++++++-----
1 files changed, 9 insertions(+), 5 deletions(-)
---
diff --git a/en-US/Storage_Pools.xml b/en-US/Storage_Pools.xml
index b9e5e90..705e2c0 100644
--- a/en-US/Storage_Pools.xml
+++ b/en-US/Storage_Pools.xml
@@ -119,7 +119,7 @@
<para>
The <literal>isPersistent</literal> method indicates whether or not a storage pool needs to be activated
using <literal>create</literal> method. A value of 1 indicates that the storage pool is persistent
- and will remain on the file system after it is realeased.
+ and will remain on the file system after it is released.
</para>
<para>
The following example shows how to get the XML description of a storage pool.
@@ -165,7 +165,7 @@
<section id="libvirt_application_development_guide_using_python-Storage_Pools-Pool_Config">
<title>Pool configuration</title>
<para>
- There are a number of methods which can congigure aspects of a storage pool. The main method
+ There are a number of methods which can configure aspects of a storage pool. The main method
is the <literal>setAutostart</literal> method.
</para>
<example>
@@ -179,7 +179,7 @@
<para>
Storage volumes are the basic unit of storage which house a guest domain's storage requirements.
All the necessary partitions used to house a guest domain are encapsulated by the storage volume.
- Storage volumnes are in turn contained in storage pools. A storage pool can conatain as many
+ Storage volumes are in turn contained in storage pools. A storage pool can contain as many
storage pools as the underlying disk partition will hold.
</para>
</section>
@@ -232,7 +232,7 @@
<para>
It should be noted that cloning can take a very long time to accomplish, depending on the size
of the storage volume being cloned. This is because the clone process copies the data from the
- source vloume to the new target volume.
+ source volume to the new target volume.
</para>
<example>
<title>Clone an existing storage volume</title>
@@ -243,8 +243,12 @@
<section id="libvirt_application_development_guide_using_python-Storage_Pools-Config_Vol">
<title>Configuring volumes</title>
<para>
- TBD
+ The following is an XML description for a storage volume.
</para>
+ <example>
+ <title>XML description for a storage volume</title>
+ <programlisting language="XML"><xi:include href="extras/StoragePools-Example-11.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </example>
</section>
</chapter>
8 years, 9 months
[libvirt_application_development_guide_using_python] Storage chapter - added example 11 - added supporting text for example 11
by David Ashley
commit f01d3a2daf080334ab87e0261fc331e26fa92800
Author: W. David Ashley <w.david.ashley(a)gmail.com>
Date: Mon Aug 3 12:46:44 2015 -0500
Storage chapter
- added example 11
- added supporting text for example 11
en-US/extras/StoragePools-Example-11.xml | 14 ++++++++++++++
1 files changed, 14 insertions(+), 0 deletions(-)
---
diff --git a/en-US/extras/StoragePools-Example-11.xml b/en-US/extras/StoragePools-Example-11.xml
new file mode 100644
index 0000000..dfefe12
--- /dev/null
+++ b/en-US/extras/StoragePools-Example-11.xml
@@ -0,0 +1,14 @@
+<volume>
+ <name>sparse.img</name>
+ <allocation>0</allocation>
+ <capacity unit="G">2</capacity>
+ <target>
+ <path>/var/lib/virt/images/sparse.img</path>
+ <permissions>
+ <owner>107</owner>
+ <group>107</group>
+ <mode>0744</mode>
+ <label>virt_image_t</label>
+ </permissions>
+ </target>
+</volume>
8 years, 9 months
[libvirt_application_development_guide_using_python] Storage chapter - added example 10 - added support text for example 10
by David Ashley
commit 9bc02e266c3e74f9af8a84cea689d694eb273765
Author: W. David Ashley <w.david.ashley(a)gmail.com>
Date: Mon Aug 3 12:05:49 2015 -0500
Storage chapter
- added example 10
- added support text for example 10
en-US/Storage_Pools.xml | 13 +++++-
en-US/extras/StoragePools-Example-10.py | 74 +++++++++++++++++++++++++++++++
en-US/extras/StoragePools-Example-9.py | 3 +-
3 files changed, 87 insertions(+), 3 deletions(-)
---
diff --git a/en-US/Storage_Pools.xml b/en-US/Storage_Pools.xml
index 98f17ee..b9e5e90 100644
--- a/en-US/Storage_Pools.xml
+++ b/en-US/Storage_Pools.xml
@@ -225,8 +225,19 @@
<section id="libvirt_application_development_guide_using_python-Storage_Pools-Cloning">
<title>Cloning volumes</title>
<para>
- TBD
+ Cloning a storage volume is similar to creating a new storage volume, except that an existing
+ storage volume is used for most of the attributes. Only the name and permissions in the XML
+ parameter are used for the new volume, everything else is inherited from the existing volume.
+ </para>
+ <para>
+ It should be noted that cloning can take a very long time to accomplish, depending on the size
+ of the storage volume being cloned. This is because the clone process copies the data from the
+ source vloume to the new target volume.
</para>
+ <example>
+ <title>Clone an existing storage volume</title>
+ <programlisting language="Python"><xi:include href="extras/StoragePools-Example-10.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </example>
</section>
<section id="libvirt_application_development_guide_using_python-Storage_Pools-Config_Vol">
diff --git a/en-US/extras/StoragePools-Example-10.py b/en-US/extras/StoragePools-Example-10.py
new file mode 100644
index 0000000..5570c9c
--- /dev/null
+++ b/en-US/extras/StoragePools-Example-10.py
@@ -0,0 +1,74 @@
+# Example-.py
+from __future__ import print_function
+import sys
+import libvirt
+
+stgvol_xml = """
+<volume>
+ <name>sparse.img</name>
+ <allocation>0</allocation>
+ <capacity unit="G">2</capacity>
+ <target>
+ <path>/var/lib/virt/images/sparse.img</path>
+ <permissions>
+ <owner>107</owner>
+ <group>107</group>
+ <mode>0744</mode>
+ <label>virt_image_t</label>
+ </permissions>
+ </target>
+</volume>"""
+stgvol_xml2 = """
+<volume>
+ <name>sparse2.img</name>
+ <allocation>0</allocation>
+ <capacity unit="G">2</capacity>
+ <target>
+ <path>/var/lib/virt/images/sparse.img</path>
+ <permissions>
+ <owner>107</owner>
+ <group>107</group>
+ <mode>0744</mode>
+ <label>virt_image_t</label>
+ </permissions>
+ </target>
+</volume>"""
+pool = 'default'
+
+conn = libvirt.open('qemu:///system')
+if conn == None:
+ print('Failed to open connection to qemu:///system', file=sys.stderr)
+ exit(1)
+
+pool = conn.storagePoolLookupByName(pool)
+if pool == None:
+ print('Failed to locate any StoragePool objects.', file=sys.stderr)
+ exit(1)
+
+# create a new storage volume
+stgvol = pool.createXML(stgvol_xml, 0)
+if stgvol == None:
+ print('Failed to create a StorageVol object.', file=sys.stderr)
+ exit(1)
+
+# now clone the existing storage volume
+print('This could take some time...')
+stgvol2 = pool.createXMLFrom(stgvol_xml2, stgvol, 0)
+if stgvol2 == None:
+ print('Failed to clone a StorageVol object.', file=sys.stderr)
+ exit(1)
+
+# remove the cloned storage volume
+# physically remove the storage volume from the underlying disk media
+stgvol2.wipe(0)
+# logically remove the storage volume from the storage pool
+stgvol2.delete(0)
+
+# remove the storage volume
+# physically remove the storage volume from the underlying disk media
+stgvol.wipe(0)
+# logically remove the storage volume from the storage pool
+stgvol.delete(0)
+
+conn.close()
+exit(0)
diff --git a/en-US/extras/StoragePools-Example-9.py b/en-US/extras/StoragePools-Example-9.py
index 790c748..c57cd21 100644
--- a/en-US/extras/StoragePools-Example-9.py
+++ b/en-US/extras/StoragePools-Example-9.py
@@ -7,7 +7,7 @@ stgvol_xml = """
<volume>
<name>sparse.img</name>
<allocation>0</allocation>
- <capacity unit="T">1</capacity>
+ <capacity unit="G">2</capacity>
<target>
<path>/var/lib/virt/images/sparse.img</path>
<permissions>
@@ -30,7 +30,6 @@ if pool == None:
print('Failed to locate any StoragePool objects.', file=sys.stderr)
exit(1)
-# create the storage volume
stgvol = pool.createXML(stgvol_xml, 0)
if stgvol == None:
print('Failed to create a StorageVol objects.', file=sys.stderr)
8 years, 9 months
[libvirt_application_development_guide_using_python] Storage chapter - added example 9 - added supporting text for example 9
by David Ashley
commit c0cb4a68ce6d364e1399a7bd228512f7cd4aab3f
Author: W. David Ashley <w.david.ashley(a)gmail.com>
Date: Mon Aug 3 10:59:08 2015 -0500
Storage chapter
- added example 9
- added supporting text for example 9
en-US/Storage_Pools.xml | 8 +++++-
en-US/extras/StoragePools-Example-9.py | 46 ++++++++++++++++++++++++++++++++
2 files changed, 53 insertions(+), 1 deletions(-)
---
diff --git a/en-US/Storage_Pools.xml b/en-US/Storage_Pools.xml
index 9457526..98f17ee 100644
--- a/en-US/Storage_Pools.xml
+++ b/en-US/Storage_Pools.xml
@@ -212,8 +212,14 @@
<section id="libvirt_application_development_guide_using_python-Storage_Pools-Create_Remove">
<title>Creating and deleting volumes</title>
<para>
- TBD
+ Storage volumes are created using the storage pool <literal>createXML</literal> method. The type
+ and attributes of the storage volume are specified in the XML passed to the
+ <literal>createXML</literal> method.
</para>
+ <example>
+ <title>Create a storage volume</title>
+ <programlisting language="Python"><xi:include href="extras/StoragePools-Example-9.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </example>
</section>
<section id="libvirt_application_development_guide_using_python-Storage_Pools-Cloning">
diff --git a/en-US/extras/StoragePools-Example-9.py b/en-US/extras/StoragePools-Example-9.py
new file mode 100644
index 0000000..790c748
--- /dev/null
+++ b/en-US/extras/StoragePools-Example-9.py
@@ -0,0 +1,46 @@
+# Example-.py
+from __future__ import print_function
+import sys
+import libvirt
+
+stgvol_xml = """
+<volume>
+ <name>sparse.img</name>
+ <allocation>0</allocation>
+ <capacity unit="T">1</capacity>
+ <target>
+ <path>/var/lib/virt/images/sparse.img</path>
+ <permissions>
+ <owner>107</owner>
+ <group>107</group>
+ <mode>0744</mode>
+ <label>virt_image_t</label>
+ </permissions>
+ </target>
+</volume>"""
+pool = 'default'
+
+conn = libvirt.open('qemu:///system')
+if conn == None:
+ print('Failed to open connection to qemu:///system', file=sys.stderr)
+ exit(1)
+
+pool = conn.storagePoolLookupByName(pool)
+if pool == None:
+ print('Failed to locate any StoragePool objects.', file=sys.stderr)
+ exit(1)
+
+# create the storage volume
+stgvol = pool.createXML(stgvol_xml, 0)
+if stgvol == None:
+ print('Failed to create a StorageVol objects.', file=sys.stderr)
+ exit(1)
+
+# remove the storage volume
+# physically remove the storage volume from the underlying disk media
+stgvol.wipe(0)
+# logically remove the storage volume from the storage pool
+stgvol.delete(0)
+
+conn.close()
+exit(0)
8 years, 9 months
[libvirt_application_development_guide_using_python] Storage chapter - added example 8 - added support text for example 8
by David Ashley
commit c2dc12c01ad8fdbc111008b8da340ef5184ea435
Author: W. David Ashley <w.david.ashley(a)gmail.com>
Date: Sun Aug 2 19:58:33 2015 -0500
Storage chapter
- added example 8
- added support text for example 8
en-US/Storage_Pools.xml | 10 ++++++++--
en-US/extras/StoragePools-Example-8.py | 28 ++++++++++++++++++++++++++++
2 files changed, 36 insertions(+), 2 deletions(-)
---
diff --git a/en-US/Storage_Pools.xml b/en-US/Storage_Pools.xml
index df8c21b..9457526 100644
--- a/en-US/Storage_Pools.xml
+++ b/en-US/Storage_Pools.xml
@@ -166,7 +166,7 @@
<title>Pool configuration</title>
<para>
There are a number of methods which can congigure aspects of a storage pool. The main method
- is the </para>literal>setAutostart</section> method.
+ is the <literal>setAutostart</literal> method.
</para>
<example>
<title>Demonstrate the setAutostart method</title>
@@ -199,8 +199,14 @@
<section id="libvirt_application_development_guide_using_python-Storage_Pools-Vol_Info">
<title>Volume information</title>
<para>
- TBD
+ Information about a storage volume is obtained by using the <literal>info</literal> method. The
+ following program shows how to list the information about each storage volume in the
+ "default" storage pool.
</para>
+ <example>
+ <title>List storage volume information</title>
+ <programlisting language="Python"><xi:include href="extras/StoragePools-Example-8.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </example>
</section>
<section id="libvirt_application_development_guide_using_python-Storage_Pools-Create_Remove">
diff --git a/en-US/extras/StoragePools-Example-8.py b/en-US/extras/StoragePools-Example-8.py
new file mode 100644
index 0000000..cac85a4
--- /dev/null
+++ b/en-US/extras/StoragePools-Example-8.py
@@ -0,0 +1,28 @@
+# Example-8.py
+from __future__ import print_function
+import sys
+import libvirt
+
+conn = libvirt.open('qemu:///system')
+if conn == None:
+ print('Failed to open connection to qemu:///system', file=sys.stderr)
+ exit(1)
+
+pool = conn.storagePoolLookupByName('default')
+if pool == None:
+ print('Failed to locate any StoragePool objects.', file=sys.stderr)
+ exit(1)
+
+stgvols = pool.listVolumes()
+
+print('Pool: '+pool.name())
+for stgvolname in stgvols:
+ print(' Volume: '+stgvolname)
+ stgvol = pool.storageVolLookupByName(stgvolname)
+ info = stgvol.info()
+ print(' Type: '+str(info[0]))
+ print(' Capacity: '+str(info[1]))
+ print(' Allocation: '+str(info[2]))
+
+conn.close()
+exit(0)
8 years, 9 months
[libvirt_application_development_guide_using_python] Storage chapter - fixed location of some text.
by David Ashley
commit 0d11860b257d320ff96425b348f0152ff0d565bd
Author: W. David Ashley <w.david.ashley(a)gmail.com>
Date: Sun Aug 2 18:33:09 2015 -0500
Storage chapter
- fixed location of some text.
en-US/Storage_Pools.xml | 11 ++++-------
1 files changed, 4 insertions(+), 7 deletions(-)
---
diff --git a/en-US/Storage_Pools.xml b/en-US/Storage_Pools.xml
index 1a9b0f1..df8c21b 100644
--- a/en-US/Storage_Pools.xml
+++ b/en-US/Storage_Pools.xml
@@ -182,6 +182,10 @@
Storage volumnes are in turn contained in storage pools. A storage pool can conatain as many
storage pools as the underlying disk partition will hold.
</para>
+ </section>
+
+ <section id="libvirt_application_development_guide_using_python-Storage_Pools-Listing">
+ <title>Listing volumes</title>
<para>
The following example program demonstrates how to list all the storage volumes contained by the
"default" storage pool.
@@ -192,13 +196,6 @@
</example>
</section>
- <section id="libvirt_application_development_guide_using_python-Storage_Pools-Listing">
- <title>Listing volumes</title>
- <para>
- TBD
- </para>
- </section>
-
<section id="libvirt_application_development_guide_using_python-Storage_Pools-Vol_Info">
<title>Volume information</title>
<para>
8 years, 9 months
[libvirt_application_development_guide_using_python] Storage chapter - Added examples 6 and 7 - Added verbage to support example 6 and 7
by David Ashley
commit 0aadbd778486183ba059d26253716cf1524d5b6f
Author: W. David Ashley <w.david.ashley(a)gmail.com>
Date: Sun Aug 2 18:30:52 2015 -0500
Storage chapter
- Added examples 6 and 7
- Added verbage to support example 6 and 7
en-US/Storage_Pools.xml | 20 ++++++++++++++++++--
en-US/extras/StoragePools-Example-2.py | 6 ++++++
en-US/extras/StoragePools-Example-6.py | 26 ++++++++++++++++++++++++++
en-US/extras/StoragePools-Example-7.py | 25 +++++++++++++++++++++++++
4 files changed, 75 insertions(+), 2 deletions(-)
---
diff --git a/en-US/Storage_Pools.xml b/en-US/Storage_Pools.xml
index 1a343ff..1a9b0f1 100644
--- a/en-US/Storage_Pools.xml
+++ b/en-US/Storage_Pools.xml
@@ -165,15 +165,31 @@
<section id="libvirt_application_development_guide_using_python-Storage_Pools-Pool_Config">
<title>Pool configuration</title>
<para>
- TBD
+ There are a number of methods which can congigure aspects of a storage pool. The main method
+ is the </para>literal>setAutostart</section> method.
</para>
+ <example>
+ <title>Demonstrate the setAutostart method</title>
+ <programlisting language="Python"><xi:include href="extras/StoragePools-Example-6.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </example>
</section>
<section id="libvirt_application_development_guide_using_python-Storage_Pools-Volume">
<title>Volume overview</title>
<para>
- TBD
+ Storage volumes are the basic unit of storage which house a guest domain's storage requirements.
+ All the necessary partitions used to house a guest domain are encapsulated by the storage volume.
+ Storage volumnes are in turn contained in storage pools. A storage pool can conatain as many
+ storage pools as the underlying disk partition will hold.
</para>
+ <para>
+ The following example program demonstrates how to list all the storage volumes contained by the
+ "default" storage pool.
+ </para>
+ <example>
+ <title>Demonstrate listing the storage volumes</title>
+ <programlisting language="Python"><xi:include href="extras/StoragePools-Example-7.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </example>
</section>
<section id="libvirt_application_development_guide_using_python-Storage_Pools-Listing">
diff --git a/en-US/extras/StoragePools-Example-2.py b/en-US/extras/StoragePools-Example-2.py
index fd1fe58..58e16bc 100644
--- a/en-US/extras/StoragePools-Example-2.py
+++ b/en-US/extras/StoragePools-Example-2.py
@@ -13,12 +13,18 @@ if pool == None:
print('Failed to locate any StoragePool objects.', file=sys.stderr)
exit(1)
+info = pool.info()
+
print('Pool: '+pool.name())
print(' UUID: '+pool.UUIDString())
print(' Autostart: '+str(pool.autostart()))
print(' Is active: '+str(pool.isActive()))
print(' Is persistent: '+str(pool.isPersistent()))
print(' Num volumes: '+str(pool.numOfVolumes()))
+print(' Pool state: '+str(info[0]))
+print(' Capacity: '+str(info[1]))
+print(' Allocation: '+str(info[2]))
+print(' Available: '+str(info[3]))
conn.close()
exit(0)
diff --git a/en-US/extras/StoragePools-Example-6.py b/en-US/extras/StoragePools-Example-6.py
new file mode 100644
index 0000000..8627d05
--- /dev/null
+++ b/en-US/extras/StoragePools-Example-6.py
@@ -0,0 +1,26 @@
+# Example-6.py
+from __future__ import print_function
+import sys
+import libvirt
+
+poolName = 'default'
+
+conn = libvirt.open('qemu:///system')
+if conn == None:
+ print('Failed to open connection to qemu:///system', file=sys.stderr)
+ exit(1)
+
+sp = conn.storagePoolLookupByName(poolName)
+if sp == None:
+ print('Failed to find storage pool '+poolName, file=sys.stderr)
+ exit(1)
+
+print('Current autostart seting: '+str(sp.autostart()))
+if sp.autostart() == True:
+ sp.setAutostart(0)
+else:
+ sp.setAutostart(1)
+print('Current autostart seting: '+str(sp.autostart()))
+
+conn.close()
+exit(0)
diff --git a/en-US/extras/StoragePools-Example-7.py b/en-US/extras/StoragePools-Example-7.py
new file mode 100644
index 0000000..952345b
--- /dev/null
+++ b/en-US/extras/StoragePools-Example-7.py
@@ -0,0 +1,25 @@
+# Example-7.py
+from __future__ import print_function
+import sys
+import libvirt
+from xml.dom import minidom
+
+poolName = 'default'
+
+conn = libvirt.open('qemu:///system')
+if conn == None:
+ print('Failed to open connection to qemu:///system', file=sys.stderr)
+ exit(1)
+
+sp = conn.storagePoolLookupByName(poolName)
+if sp == None:
+ print('Failed to find storage pool '+poolName, file=sys.stderr)
+ exit(1)
+
+stgvols = sp.listVolumes()
+print('Storage pool: '+poolName)
+for stgvol in stgvols :
+ print(' Storage vol: '+stgvol)
+
+conn.close()
+exit(0)
8 years, 9 months
[libvirt_application_development_guide_using_python] Storage chapter - added additional overview text.
by David Ashley
commit 8eaab84156c39302e271cb093ab92a07f07b46fd
Author: W. David Ashley <w.david.ashley(a)gmail.com>
Date: Sun Aug 2 17:39:55 2015 -0500
Storage chapter
- added additional overview text.
en-US/Storage_Pools.xml | 71 +++++++++++++++++++++++++++++++++++++++++++---
1 files changed, 66 insertions(+), 5 deletions(-)
---
diff --git a/en-US/Storage_Pools.xml b/en-US/Storage_Pools.xml
index 2ad1305..1a343ff 100644
--- a/en-US/Storage_Pools.xml
+++ b/en-US/Storage_Pools.xml
@@ -6,12 +6,73 @@
<chapter id="libvirt_application_development_guide_using_python-Storage_Pools">
<title>Storage Pools</title>
<para>
- Storage pools allow a system administrator to divide a system's storage into logical locations
- in order to store all the guest domain disk images as defined by the administrator. A system can
- have a single storage pool or as many as deemed necessary by the storage administrator, all in
- diverse locations. The storage administrator is responsible for devising the storage scheme
- to be used and how the storage pools are to be used.
+ Libvirt provides storage management on the physical host through storage pools and volumes.
</para>
+ <para>
+ A storage pool is a quantity of storage set aside by an administrator, often a dedicated storage
+ administrator, for use by virtual machines. Storage pools are divided into storage volumes either by
+ the storage administrator or the system administrator, and the volumes are assigned to VMs as block
+ devices.
+ </para>
+ <para>
+ For example, the storage administrator responsible for an NFS server creates a share to store virtual
+ machines' data. The system administrator defines a pool on the virtualization host with the details of
+ the share (e.g. nfs.example.com:/path/to/share should be mounted on /vm_data). When the pool is started,
+ libvirt mounts the share on the specified directory, just as if the system administrator logged in and
+ executed 'mount nfs.example.com:/path/to/share /vmdata'. If the pool is configured to autostart, libvirt
+ ensures that the NFS share is mounted on the directory specified when libvirt is started.
+ </para>
+ <para>
+ Once the pool is started, the files in the NFS share are reported as volumes, and the storage volumes'
+ paths may be queried using the libvirt APIs. The volumes' paths can then be copied into the section of
+ a VM's XML definition describing the source storage for the VM's block devices. In the case of NFS,
+ an application using the libvirt methods can create and delete volumes in the pool (files in the NFS share)
+ up to the limit of the size of the pool (the storage capacity of the share). Not all pool types support
+ creating and deleting volumes. Stopping the pool (somewhat unfortunately referred to by virsh and the
+ API as "pool-destroy") undoes the start operation, in this case, unmounting the NFS share. The data on
+ the share is not modified by the destroy operation, despite the name. See man virsh for more details.
+ </para>
+ <para>
+ A second example is an iSCSI pool. A storage administrator provisions an iSCSI target to present a set
+ of LUNs to the host running the VMs. When libvirt is configured to manage that iSCSI target as a pool,
+ libvirt will ensure that the host logs into the iSCSI target and libvirt can then report the available
+ LUNs as storage volumes. The volumes' paths can be queried and used in VM's XML definitions as in the
+ NFS example. In this case, the LUNs are defined on the iSCSI server, and libvirt cannot create and
+ delete volumes.
+ </para>
+ <para>
+ Storage pools and volumes are not required for the proper operation of VMs. Pools and volumes provide
+ a way for libvirt to ensure that a particular piece of storage will be available for a VM, but some
+ administrators will prefer to manage their own storage and VMs will operate properly without any pools
+ or volumes defined. On systems that do not use pools, system administrators must ensure the availability
+ of the VMs' storage using whatever tools they prefer, for example, adding the NFS share to the host's
+ fstab so that the share is mounted at boot time.
+ </para>
+ <para>
+ If at this point the value of pools and volumes over traditional system administration tools is unclear,
+ note that one of the features of libvirt is its remote protocol, so it's possible to manage all aspects
+ of a virtual machine's lifecycle as well as the configuration of the resources required by the VM. These
+ operations can be performed on a remote host entirely within the libvirt API. In other words, a
+ management application using libvirt can enable a user to perform all the required tasks for configuring
+ the host for a VM: allocating resources, running the VM, shutting it down and deallocating the resources, without requiring shell access or any other control channel.
+ </para>
+ <para>
+ Libvirt supports the following storage pool types:
+ </para>
+ <itemizedlist>
+ <listitem><para>Directory backend</para></listitem>
+ <listitem><para>Local filesystem backend</para></listitem>
+ <listitem><para>Network filesystem backend</para></listitem>
+ <listitem><para>Logical backend</para></listitem>
+ <listitem><para>Disk backend</para></listitem>
+ <listitem><para>iSCSI backend</para></listitem>
+ <listitem><para>SCSI backend</para></listitem>
+ <listitem><para>Multipath backend</para></listitem>
+ <listitem><para>RBD (RADOS Block Device) backend</para></listitem>
+ <listitem><para>Sheepdog backend</para></listitem>
+ <listitem><para>Gluster backend</para></listitem>
+ <listitem><para>ZFS backend</para></listitem>
+ </itemizedlist>
<section id="libvirt_application_development_guide_using_python-Storage_Pools-Overview">
<title>Overview</title>
8 years, 9 months
[libvirt_application_development_guide_using_python] Storage chapter - added example 5 - added storage pool sources verbage
by David Ashley
commit 8693f86ce9bc2b31d4cd0115858737d03de6ce36
Author: W. David Ashley <w.david.ashley(a)gmail.com>
Date: Fri Jul 31 13:42:17 2015 -0500
Storage chapter
- added example 5
- added storage pool sources verbage
en-US/Storage_Pools.xml | 12 +++++++--
en-US/extras/StoragePools-Example-5.py | 42 ++++++++++++++++++++++++++++++++
2 files changed, 51 insertions(+), 3 deletions(-)
---
diff --git a/en-US/Storage_Pools.xml b/en-US/Storage_Pools.xml
index 38466c1..2ad1305 100644
--- a/en-US/Storage_Pools.xml
+++ b/en-US/Storage_Pools.xml
@@ -52,11 +52,11 @@
started if the <literal>autostart</literal> is not set.
</para>
<para>
- The <literal>isActive</literal> indicates whether or not the user must activate the storage
+ The <literal>isActive</literal> method indicates whether or not the user must activate the storage
pool in some way. The <literal>create</literal> method can activate a storage pool.
</para>
<para>
- The <literal>isPersistent</literal> indicates whether or not a storage pool needs to be activated
+ The <literal>isPersistent</literal> method indicates whether or not a storage pool needs to be activated
using <literal>create</literal> method. A value of 1 indicates that the storage pool is persistent
and will remain on the file system after it is realeased.
</para>
@@ -86,13 +86,19 @@
volumes in place because if they exist on a remote file system or disk then that file system
may become unavailable to the guest domain since there will be no mechanism to reactivate the
remote file system or disk by the libvirt storage system at a future time.
+ </para>
</section>
<section id="libvirt_application_development_guide_using_python-Storage_Pools-Discover_Sources">
<title>Discovering pool sources</title>
<para>
- TBD
+ The sources for a storage pool's sources can be discovered by examining the pool's XML
+ description. An example program follows that prints out a pools source description attributes.
</para>
+ <example>
+ <title>Discover a storage pool's sources</title>
+ <programlisting language="Python"><xi:include href="extras/StoragePools-Example-5.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </example>
</section>
<section id="libvirt_application_development_guide_using_python-Storage_Pools-Pool_Config">
diff --git a/en-US/extras/StoragePools-Example-5.py b/en-US/extras/StoragePools-Example-5.py
new file mode 100644
index 0000000..8d453af
--- /dev/null
+++ b/en-US/extras/StoragePools-Example-5.py
@@ -0,0 +1,42 @@
+# Example-5.py
+from __future__ import print_function
+import sys
+import libvirt
+from xml.dom import minidom
+
+poolName = 'default'
+
+conn = libvirt.open('qemu:///system')
+if conn == None:
+ print('Failed to open connection to qemu:///system', file=sys.stderr)
+ exit(1)
+
+sp = conn.storagePoolLookupByName(poolName)
+if sp == None:
+ print('Failed to find storage pool '+poolName, file=sys.stderr)
+ exit(1)
+
+raw_xml = sp.XMLDesc(0)
+xml = minidom.parseString(raw_xml)
+name = xml.getElementsByTagName('name')
+print('pool name: '+poolName)
+spTypes = xml.getElementsByTagName('source')
+for spType in spTypes:
+ attr = spType.getAttribute('name')
+ if attr != None:
+ print(' name = '+attr)
+ attr = spType.getAttribute('path')
+ if attr != None:
+ print(' path = '+attr)
+ attr = spType.getAttribute('dir')
+ if attr != None:
+ print(' dir = '+attr)
+ attr = spType.getAttribute('type')
+ if attr != None:
+ print(' type = '+attr)
+ attr = spType.getAttribute('username')
+ if attr != None:
+ print(' username = '+attr)
+
+conn.close()
+exit(0)
8 years, 9 months