[libvirt_application_development_guide_using_python] Domains chapter - corrected example 32
by David Ashley
commit 998c20c74b99edd8689ae81f6d9f731f36bc6439
Author: W. David Ashley <w.david.ashley(a)gmail.com>
Date: Fri Jul 10 10:04:31 2015 -0500
Domains chapter
- corrected example 32
en-US/extras/Domains-Example-32.py | 22 +++++++++++-----------
1 files changed, 11 insertions(+), 11 deletions(-)
---
diff --git a/en-US/extras/Domains-Example-32.py b/en-US/extras/Domains-Example-32.py
index a02abfd..223d351 100644
--- a/en-US/extras/Domains-Example-32.py
+++ b/en-US/extras/Domains-Example-32.py
@@ -2,6 +2,7 @@
from __future__ import print_function
import sys
import libvirt
+from xml.etree import ElementTree
domName = 'Fedora22-x86_64-1'
@@ -10,23 +11,22 @@ if conn == None:
print('Failed to open connection to qemu:///system', file=sys.stderr)
exit(1)
-dom = conn.lookupByID(6)
+dom = conn.lookupByID(5)
if dom == None:
print('Failed to find the domain '+domName, file=sys.stderr)
exit(1)
tree = ElementTree.fromstring(dom.XMLDesc())
iface = tree.find('devices/interface/target').get('dev')
-rx_bytes, rx_packets, rx_err, rx_drop, tx_bytes, tx_packets, tx_err,
- tx_drop = dom.interfaceStats(iface)
-print('read bytes: '+rx_bytes)
-print('read packets: 'rx_packets)
-print('read errors: '+rx_err)
-print('read drops: '+rx_drop)
-print('write bytes: '+tx_bytes)
-print('write packets: 'rt_packets)
-print('write errors: '+tx_err)
-print('write drops: '+tx_drop)
+stats = dom.interfaceStats(iface)
+print('read bytes: '+str(stats[0]))
+print('read packets: '+str(stats[1]))
+print('read errors: '+str(stats[2]))
+print('read drops: '+str(stats[3]))
+print('write bytes: '+str(stats[4]))
+print('write packets: '+str(stats[5]))
+print('write errors: '+str(stats[6]))
+print('write drops: '+str(stats[7]))
conn.close()
exit(0)
8 years, 9 months
[libvirt_application_development_guide_using_python] Domain chapter - nodified example 35 to better explain the returned value from memoryStats method
by David Ashley
commit 92b07c910356a859d812ee808e7d99b475b1ebb2
Author: W. David Ashley <w.david.ashley(a)gmail.com>
Date: Fri Jul 10 09:46:39 2015 -0500
Domain chapter
- nodified example 35 to better explain the returned value from memoryStats method
- modified the text to also explain the results returned from memoryStats method
en-US/Guest_Domains.xml | 5 ++---
en-US/extras/Domains-Example-35.py | 6 +++---
2 files changed, 5 insertions(+), 6 deletions(-)
---
diff --git a/en-US/Guest_Domains.xml b/en-US/Guest_Domains.xml
index 14f2e3f..c420958 100644
--- a/en-US/Guest_Domains.xml
+++ b/en-US/Guest_Domains.xml
@@ -942,10 +942,9 @@
<programlisting language="Python"><xi:include href="extras/Domains-Example-35.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
</example>
<para>
- To find the percentage of memory used by the domain invoke the <literal>maxMemory</literal>
- method an then perform the following calculation.
+ Note that the <literal>memoryStats</literal> returns a dictionary object. This object will
+ contain a variable number of entries depending on the hypervisor and guest domain capabilities.
</para>
- <programlisting language="Python">percentage = dom.memoryStats().value() / dom.maxMemory()</programlisting>
</section>
diff --git a/en-US/extras/Domains-Example-35.py b/en-US/extras/Domains-Example-35.py
index f5d3252..123f33b 100644
--- a/en-US/extras/Domains-Example-35.py
+++ b/en-US/extras/Domains-Example-35.py
@@ -16,9 +16,9 @@ if dom == None:
exit(1)
stats = dom.memoryStats()
-print('memory used: '+str(stats['actual'])+' (actual)')
-print(' '+str(stats['swap_in'])+' (swap_in)')
-print(' '+str(stats['rss'])+' (rss)')
+print('memory used:')
+for name in stats:
+ print(' '+str(stats[name])+' ('+name+')')
conn.close()
exit(0)
8 years, 9 months
[libvirt_application_development_guide_using_python] Domains chapter - corrected example 35 (did not work before)
by David Ashley
commit 1773a676c93b9c0e05485d584974abe34e1b25f3
Author: W. David Ashley <w.david.ashley(a)gmail.com>
Date: Fri Jul 10 09:29:38 2015 -0500
Domains chapter
- corrected example 35 (did not work before)
en-US/extras/Domains-Example-35.py | 7 +++++--
1 files changed, 5 insertions(+), 2 deletions(-)
---
diff --git a/en-US/extras/Domains-Example-35.py b/en-US/extras/Domains-Example-35.py
index 5ad3e80..f5d3252 100644
--- a/en-US/extras/Domains-Example-35.py
+++ b/en-US/extras/Domains-Example-35.py
@@ -10,12 +10,15 @@ if conn == None:
print('Failed to open connection to qemu:///system', file=sys.stderr)
exit(1)
-dom = conn.lookupByID(6)
+dom = conn.lookupByID(5)
if dom == None:
print('Failed to find the domain '+domName, file=sys.stderr)
exit(1)
-print('"memory used: '+dom.memoryStats().value()
+stats = dom.memoryStats()
+print('memory used: '+str(stats['actual'])+' (actual)')
+print(' '+str(stats['swap_in'])+' (swap_in)')
+print(' '+str(stats['rss'])+' (rss)')
conn.close()
exit(0)
8 years, 9 months
[libvirt_application_development_guide_using_python] Domains chapter - finished the performance section - added examples 30-35
by David Ashley
commit 839edfa1d69160678779e770374301acc489ed7f
Author: W. David Ashley <w.david.ashley(a)gmail.com>
Date: Thu Jul 9 10:51:07 2015 -0500
Domains chapter
- finished the performance section
- added examples 30-35
en-US/Guest_Domains.xml | 79 +++++++++++++++++++++++++++++++----
en-US/extras/Domains-Example-30.py | 2 +-
en-US/extras/Domains-Example-31.py | 26 ++++++++++++
en-US/extras/Domains-Example-32.py | 32 ++++++++++++++
en-US/extras/Domains-Example-33.py | 23 ++++++++++
en-US/extras/Domains-Example-34.py | 24 +++++++++++
en-US/extras/Domains-Example-35.py | 21 +++++++++
7 files changed, 197 insertions(+), 10 deletions(-)
---
diff --git a/en-US/Guest_Domains.xml b/en-US/Guest_Domains.xml
index 259dd3d..14f2e3f 100644
--- a/en-US/Guest_Domains.xml
+++ b/en-US/Guest_Domains.xml
@@ -883,11 +883,23 @@
block devices, and network interfaces.
</para>
- <section id="libvirt_application_development_guide_using_python-Guest_Domains-Monitoring-Domain">
- <title>Domain Performance</title>
+ <section id="libvirt_application_development_guide_using_python-Guest_Domains-Monitoring-Domain_Block">
+ <title>Domain Block Device Performance</title>
<para>
- TBD
+ Disk usage statistics are provided by the
+ <literal>blockStats</literal> method:
+ </para>
+ <example>
+ <title>Get the disk block I/O statistics</title>
+ <programlisting language="Python"><xi:include href="extras/Domains-Example-31.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </example>
+ <para>
+ The returned tuple contains the number of read
+ (write) requests issued, and the actual number of bytes
+ transferred. A block device is specified by the image
+ file path or the device bus name set by the devices/disk/target[@dev]
+ element in the domain XML.
</para>
</section>
@@ -896,20 +908,69 @@
<title>vCPU Performance</title>
<para>
- TBD
+ To obtain the individual VCPU statistics:
+ </para>
+ <example>
+ <title>Get the individual CPU statistics</title>
+ <programlisting language="Python"><xi:include href="extras/Domains-Example-33.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </example>
+ <para>
+ This way, each CPU reports its usage for the domain (in
+ nanoseconds). If a host has four CPUs, there will be
+ four entries in the cpu_stats array.
+ </para>
+ <para>
+ <literal>getCPUStats(True)</literal> aggregates the statistics for all
+ CPUs on the host:
</para>
+ <example>
+ <title>Get the aggregate CPU statistics</title>
+ <programlisting language="Python"><xi:include href="extras/Domains-Example-34.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </example>
</section>
- <section id="libvirt_application_development_guide_using_python-Guest_Domains-Monitoring-IO_stats">
- <title>I/O Statistics</title>
+ <section id="libvirt_application_development_guide_using_python-Guest_Domains-Monitoring-Memory">
+ <title>Memory Statistics</title>
- <para>
- TBD
- </para>
+ <para>
+ To obtain the amount of memory currently used by the domain you can use the
+ <literal>memoryStats</literal> method.
+ </para>
+ <example>
+ <title>Get the memory statistics</title>
+ <programlisting language="Python"><xi:include href="extras/Domains-Example-35.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </example>
+ <para>
+ To find the percentage of memory used by the domain invoke the <literal>maxMemory</literal>
+ method an then perform the following calculation.
+ </para>
+ <programlisting language="Python">percentage = dom.memoryStats().value() / dom.maxMemory()</programlisting>
</section>
+ <section id="libvirt_application_development_guide_using_python-Guest_Domains-Monitoring-IO_stats">
+ <title>I/O Statistics</title>
+
+ <para>
+ To get the network statistics, you'll need the name
+ of the host interface that the domain is connected to
+ (usually vnetX). To find it, retrieve the domain XML
+ description (libvirt modifies it at the runtime). Then,
+ look for devices/interface/target[@dev] element(s):
+ </para>
+ <example>
+ <title>Get the network I/O statistics</title>
+ <programlisting language="Python"><xi:include href="extras/Domains-Example-32.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </example>
+ <para>
+ The <literal>interfaceStats</literal> method returns the number
+ of bytes (packets) received (transmitted), and the
+ number of reception/transmission errors.
+ </para>
+
+ </section>
+
</section>
<section id="libvirt_application_development_guide_using_python-Guest_Domains-Device_Config">
diff --git a/en-US/extras/Domains-Example-30.py b/en-US/extras/Domains-Example-30.py
index 0af77cd..28c8c06 100644
--- a/en-US/extras/Domains-Example-30.py
+++ b/en-US/extras/Domains-Example-30.py
@@ -1,4 +1,4 @@
-# Example-29.py
+# Example-30.py
from __future__ import print_function
import sys
import libvirt
diff --git a/en-US/extras/Domains-Example-31.py b/en-US/extras/Domains-Example-31.py
new file mode 100644
index 0000000..96ac2e5
--- /dev/null
+++ b/en-US/extras/Domains-Example-31.py
@@ -0,0 +1,26 @@
+# Example-31.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)
+
+rd_req, rd_bytes, wr_req, wr_bytes, err = dom.blockStats('/path/to/linux-0.2.img')
+print('Read requests issued: '+rd_req)
+print('Bytes read: '+rd_bytes)
+print('Write requests issued: '+wr_req)
+print('Bytes written: '+wr_bytes)
+print('Number of errors: '+err)
+
+conn.close()
+exit(0)
diff --git a/en-US/extras/Domains-Example-32.py b/en-US/extras/Domains-Example-32.py
new file mode 100644
index 0000000..a02abfd
--- /dev/null
+++ b/en-US/extras/Domains-Example-32.py
@@ -0,0 +1,32 @@
+# Example-32.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)
+
+tree = ElementTree.fromstring(dom.XMLDesc())
+iface = tree.find('devices/interface/target').get('dev')
+rx_bytes, rx_packets, rx_err, rx_drop, tx_bytes, tx_packets, tx_err,
+ tx_drop = dom.interfaceStats(iface)
+print('read bytes: '+rx_bytes)
+print('read packets: 'rx_packets)
+print('read errors: '+rx_err)
+print('read drops: '+rx_drop)
+print('write bytes: '+tx_bytes)
+print('write packets: 'rt_packets)
+print('write errors: '+tx_err)
+print('write drops: '+tx_drop)
+
+conn.close()
+exit(0)
diff --git a/en-US/extras/Domains-Example-33.py b/en-US/extras/Domains-Example-33.py
new file mode 100644
index 0000000..271cd7f
--- /dev/null
+++ b/en-US/extras/Domains-Example-33.py
@@ -0,0 +1,23 @@
+# Example-33.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)
+
+cpu_stats = dom.getCPUStats(False)
+for (i, cpu) in enumerate(cpu_stats):
+ print('CPU '+i+' Time: '+cpu['cpu_time'] / 1000000000.)
+
+conn.close()
+exit(0)
diff --git a/en-US/extras/Domains-Example-34.py b/en-US/extras/Domains-Example-34.py
new file mode 100644
index 0000000..2fa4315
--- /dev/null
+++ b/en-US/extras/Domains-Example-34.py
@@ -0,0 +1,24 @@
+# Example-34.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)
+
+stats = dom.getCPUStats(True)
+print('cpu_time: '+stats[0])
+print('system time: '+stats[1])
+print('user time: '+stats[2])
+
+conn.close()
+exit(0)
diff --git a/en-US/extras/Domains-Example-35.py b/en-US/extras/Domains-Example-35.py
new file mode 100644
index 0000000..5ad3e80
--- /dev/null
+++ b/en-US/extras/Domains-Example-35.py
@@ -0,0 +1,21 @@
+# Example-35.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)
+
+print('"memory used: '+dom.memoryStats().value()
+
+conn.close()
+exit(0)
8 years, 9 months
[libvirt_application_development_guide_using_python] Domains chapter - removed some duplicate and non essential sections
by David Ashley
commit 4f27316f92f4ff9d85fce63fa4118614347015af
Author: W. David Ashley <w.david.ashley(a)gmail.com>
Date: Thu Jul 9 09:04:02 2015 -0500
Domains chapter
- removed some duplicate and non essential sections
en-US/Guest_Domains.xml | 45 ---------------------------------------------
1 files changed, 0 insertions(+), 45 deletions(-)
---
diff --git a/en-US/Guest_Domains.xml b/en-US/Guest_Domains.xml
index 822b91c..259dd3d 100644
--- a/en-US/Guest_Domains.xml
+++ b/en-US/Guest_Domains.xml
@@ -873,33 +873,6 @@
</example>
</section>
- <section id="libvirt_application_development_guide_using_python-Guest_Domains-Domain_Config-Lifecycle">
- <title>Lifecycle controls</title>
-
- <para>
- TBD
- </para>
-
- </section>
-
- <section id="libvirt_application_development_guide_using_python-Guest_Domains-Domain_Config-Clock">
- <title>Clock Sync</title>
-
- <para>
- TBD
- </para>
-
- </section>
-
- <section id="libvirt_application_development_guide_using_python-Guest_Domains-Domain_Config-Features">
- <title>Features</title>
-
- <para>
- TBD
- </para>
-
- </section>
-
</section>
<section id="libvirt_application_development_guide_using_python-Guest_Domains-Monitoring">
@@ -1305,24 +1278,6 @@
</section>
- <section id="libvirt_application_development_guide_using_python-Guest_Domains-Guest_Domains-Security">
- <title>Security Model</title>
-
- <para>
- TBD
- </para>
-
- </section>
-
- <section id="libvirt_application_development_guide_using_python-Guest_Domains-Event_Not">
- <title>Event Notifications</title>
-
- <para>
- TBD
- </para>
-
- </section>
-
<section id="libvirt_application_development_guide_using_python-Guest_Domains-Tuning">
<title>Tuning</title>
8 years, 9 months
[libvirt_application_development_guide_using_python] Domains Chapter - started indexing this chapter - some minor edits on method names
by David Ashley
commit 80c7b2c4c5482c32047982b49ef2f5ee61c43bc2
Author: W. David Ashley <w.david.ashley(a)gmail.com>
Date: Wed Jul 8 13:55:21 2015 -0500
Domains Chapter
- started indexing this chapter
- some minor edits on method names
en-US/Guest_Domains.xml | 104 +++++++++++++++++++++++++++++++++++++++++-----
1 files changed, 92 insertions(+), 12 deletions(-)
---
diff --git a/en-US/Guest_Domains.xml b/en-US/Guest_Domains.xml
index 5e7130a..822b91c 100644
--- a/en-US/Guest_Domains.xml
+++ b/en-US/Guest_Domains.xml
@@ -5,6 +5,8 @@
]>
<chapter id="libvirt_application_development_guide_using_python-Guest_Domains">
<title>Guest Domains</title>
+ <indexterm><primary>Guest domains</primary></indexterm>
+ <indexterm><primary>Domains</primary></indexterm>
<section id="libvirt_application_development_guide_using_python-Guest_Domains-Domain_Overview">
<title>Domain Overview</title>
@@ -64,6 +66,15 @@
</para>
<para>
+ <indexterm><primary>lookupByName, Domains</primary></indexterm>
+ <indexterm><primary>Domains</primary>
+ <secondary>lookupByName</secondary></indexterm>
+ <indexterm><primary>lookupByID, Domains</primary></indexterm>
+ <indexterm><primary>Domains</primary>
+ <secondary>lookupByID</secondary></indexterm>
+ <indexterm><primary>lookupByUUID, Domains</primary></indexterm>
+ <indexterm><primary>Domains</primary>
+ <secondary>lookupByUUID</secondary></indexterm>
Once an application has a unique identifier for a domain, it will
often want to obtain the corresponding <literal>virDomain</literal>
object. There are three, imaginatively named, methods to do lookup
@@ -99,6 +110,9 @@
<section id="libvirt_application_development_guide_using_python-Guest_Domains-Listing_Domains">
<title>Listing Domains</title>
+ <indexterm><primary>listing Domains</primary></indexterm>
+ <indexterm><primary>Domains</primary>
+ <secondary>listing</secondary></indexterm>
<para>
The libvirt classes expose two lists of domains, the first
@@ -112,6 +126,9 @@
</para>
<para>
+ <indexterm><primary>listDomainsID</primary></indexterm>
+ <indexterm><primary>Domains</primary>
+ <secondary>listDomainsID</secondary></indexterm>
The method for listing active domains, returns a list of domain
IDs. Every running domain has a positive integer ID, uniquely
identifying it amongst all running domains on the host. The
@@ -129,6 +146,9 @@
<para>
+ <indexterm><primary>listDefinedDomains</primary></indexterm>
+ <indexterm><primary>Domains</primary>
+ <secondary>listDefinedDmamins</secondary></indexterm>
In addition to the running domains, there may be some persistent
inactive domain configurations stored on the host. Since an inactive
domain does not have any ID identifier, the listing of inactive
@@ -143,6 +163,9 @@
</example>
<para>
+ <indexterm><primary>lisAllDomains</primary></indexterm>
+ <indexterm><primary>Domains</primary>
+ <secondary>listAllDmamins</secondary></indexterm>
The methods for listing domains do not directly return the
<literal>virDomain</literal> objects, since this may
incur undue performance penalty for applications which wish
@@ -162,6 +185,9 @@
<section id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle_Control">
<title>Lifecycle Control</title>
+ <indexterm><primary>Lifecycle, Domains</primary></indexterm>
+ <indexterm><primary>Domains</primary>
+ <secondary>Lifecycle</secondary></indexterm>
<para>
Libvirt can control the entire lifecycle of guest domains. Guest domains can transition through
@@ -222,6 +248,9 @@
<section id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Provisioning_and_Starting">
<title>Provisioning and Starting</title>
+ <indexterm><primary>Provisioning and Starting, Domains</primary></indexterm>
+ <indexterm><primary>Domains</primary>
+ <secondary>Provisioning and starting</secondary></indexterm>
<para>
Provisioning refers to the task of creating new guest domains,
@@ -238,6 +267,12 @@
<title>Methods For Provisioning</title>
<para>
+ <indexterm><primary>createXML</primary></indexterm>
+ <indexterm><primary>Domains</primary>
+ <secondary>createXML</secondary></indexterm>
+ <indexterm><primary>defineXML</primary></indexterm>
+ <indexterm><primary>Domains</primary>
+ <secondary>defineXML</secondary></indexterm>
There are up to three methods involved in provisioning guests.
The <literal>createXML</literal> method will create
and immediately boot a new transient guest domain. When this
@@ -319,6 +354,9 @@
<section id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Provisioning-Provisioning_Techniques">
<title>New Guest Domain Provisioning Techniques</title>
+ <indexterm><primary>New guest domain provisioning</primary></indexterm>
+ <indexterm><primary>Guest domain provisioning, New</primary></indexterm>
+ <indexterm><primary>Domain provisioning, New guest</primary></indexterm>
<para>
This section will first illustrate two configurations that
@@ -344,6 +382,8 @@
<section id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Provisioning-ISO">
<title>CDROM/ISO image provisioning</title>
+ <indexterm><primary>CDROM/ISO image provisioning</primary></indexterm>
+ <indexterm><primary>ISO/CDROM image provisioning</primary></indexterm>
<para>
All full virtualization technologies have support for emulating
@@ -409,6 +449,7 @@
<section id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Provisioning-PXE">
<title>PXE Boot Provisioning</title>
+ <indexterm><primary>PXE boot provisioning</primary></indexterm>
<para>
Some newer full virtualization technologies provide a BIOS that
@@ -466,6 +507,7 @@
<section id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Provisioning-Kernel">
<title>Direct Kernel Boot Provisioning</title>
+ <indexterm><primary>Kernel boot provisioning</primary></indexterm>
<para>
Paravirtualization technologies emulate a fairly restrictive
@@ -559,6 +601,8 @@
<section id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Stopping">
<title>Stopping</title>
+ <indexterm><primary>Stopping a domain</primary></indexterm>
+ <indexterm><primary>Domain, stopping a</primary></indexterm>
<para>
Stopping refers to the process of halting a running guest. A guest can be stopped by two methods:
shutdown and destroy.
@@ -578,14 +622,30 @@
<section id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Save">
<title>Suspend / Resume and Save / Restore</title>
+ <indexterm><primary>Suspend a domain</primary></indexterm>
+ <indexterm><primary>Resume a domain</primary></indexterm>
+ <indexterm><primary>Save a domain</primary></indexterm>
+ <indexterm><primary>Restore a domain</primary></indexterm>
<para>
+ <indexterm><primary>suspend</primary></indexterm>
+ <indexterm><primary>Domains</primary>
+ <secondary>suspend</secondary></indexterm>
+ <indexterm><primary>resume</primary></indexterm>
+ <indexterm><primary>Domains</primary>
+ <secondary>resume</secondary></indexterm>
the <literal>suspend</literal> and <literal>resume</literal> methods refer to the process of taking a running guest and
temporarily saving its memory state. At a later time, it is possible to resume the guest
to its original running state, contiuining execution where it left off. Suspend does not
save a persistent image of the guest's memory. For this, <literal>save</literal> is used.
</para>
<para>
+ <indexterm><primary>save</primary></indexterm>
+ <indexterm><primary>Domains</primary>
+ <secondary>save</secondary></indexterm>
+ <indexterm><primary>restore</primary></indexterm>
+ <indexterm><primary>Domains</primary>
+ <secondary>restore</secondary></indexterm>
The <literal>save</literal> and <literal>restore</literal> methods refer to the process of taking a running guest
and saving its memory state to a file. At some time later, it
is possible to restore the guest to its original running state,
@@ -645,8 +705,15 @@
<section id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Migration">
<title>Migration</title>
+ <indexterm><primary>Migration, domain</primary></indexterm>
<para>
+ <indexterm><primary>migrate</primary></indexterm>
+ <indexterm><primary>Domains</primary>
+ <secondary>migrate</secondary></indexterm>
+ <indexterm><primary>migrateToURI</primary></indexterm>
+ <indexterm><primary>Domains</primary>
+ <secondary>migrateToURI</secondary></indexterm>
Migration is the process of taking the image of a guest domain and moving it somewhere,
typically from a hypervisor on one node to a hypervisor on another node. There are two
methods for migration. The <literal>migrate</literal> method takes an established
@@ -717,8 +784,12 @@
<section id="libvirt_application_development_guide_using_python-Guest_Domains-Lifecycle-Autostart">
<title>Autostart</title>
+ <indexterm><primary>Autostart</primary></indexterm>
<para>
+ <indexterm><primary>setAutostart</primary></indexterm>
+ <indexterm><primary>Domains</primary>
+ <secondary>setAutostart</secondary></indexterm>
A guest domain can be configured to autostart on a particular hypervisor, either by the
hypervisor itself or libvirt. In combination with managed save, this allows the operating
system on a guest domain to withstand host reboots without ever considering itself to have
@@ -736,6 +807,8 @@
<section id="libvirt_application_development_guide_using_python-Guest_Domains-Domain_Config">
<title>Domain Configuration</title>
+ <indexterm><primary>Domain configuration</primary></indexterm>
+ <indexterm><primary>Configuration, domain</primary></indexterm>
<para>
Domains are defined in libvirt using XML. Everything related only to the domain, such as
@@ -929,6 +1002,7 @@
<section id="libvirt_application_development_guide_using_python-Guest_Domains-Device_Config-PCI_Pass">
<title>PCI device passthrough</title>
+ <indexterm><primary>PCI device passthrough</primary></indexterm>
<para>
The PCI device passthrough capability allows a physical PCI device from
@@ -1071,12 +1145,16 @@
<section id="libvirt_application_development_guide_using_python-Guest_Domains-Live_Config-Block_Jobs">
<title>Block Device Jobs</title>
+ <indexterm><primary>Block device jobs</primary></indexterm>
<para>
+ <indexterm><primary>blockPull</primary></indexterm>
+ <indexterm><primary>Domains</primary>
+ <secondary>blockPull</secondary></indexterm>
Libvirt provides a generic Block Job API that can be used to initiate
and manage operations on disks that belong to a domain. Jobs are
started by calling the function associated with the desired operation
- (eg. <literal>virDomainBlockPull</literal>). Once started, all block
+ (eg. <literal>blockPull</literal>). Once started, all block
jobs are managed in the same manner. They can be aborted, throttled,
and queried. Upon completion, an asynchronous event is issued to
indicate the final status.
@@ -1088,9 +1166,9 @@
<orderedlist>
<listitem>
<para>
- <literal>virDomainBlockPull()</literal> starts a block pull
+ <literal>blockPull()</literal> starts a block pull
operation for the specified disk. This operation is valid only for
- specially configured disks. BlockPull will populate a disk image
+ specially configured disks. <literal>blockPull</literal> will populate a disk image
with data from its backing image. Once all data from its backing
image has been pulled, the disk no longer depends on a backing
image.
@@ -1099,30 +1177,32 @@
</orderedlist>
<para>
+ <indexterm><primary>blockJobInfo</primary></indexterm>
+ <indexterm><primary>Domains</primary>
+ <secondary>blockJobInfo</secondary></indexterm>
A disk can be queried for active block jobs by using
- <literal>virDomainGetBlockJobInfo()</literal>. If found, job
+ <literal>blockJobInfo</literal>. If found, job
information is reported in a structure that contains: the job type,
bandwidth throttling setting, and progress information.
</para>
<para>
+ <indexterm><primary>blockJobAbort</primary></indexterm>
+ <indexterm><primary>Domains</primary>
+ <secondary>blockJobAbort</secondary></indexterm>
<literal>virDomainBlockJobAbort()</literal> can be used to cancel the
active block job on the specified disk.
</para>
<para>
- Use <literal>virDomainBlockJobSetSpeed()</literal> to limit the amount
+ <indexterm><primary>blockJobSetSpeed</primary></indexterm>
+ <indexterm><primary>Domains</primary>
+ <secondary>blockJobSetSpeed</secondary></indexterm>
+ Use <literal>blockJobSetSpeed()</literal> to limit the amount
of bandwidth that a block job may consume. Bandwidth is specified in
units of MB/sec.
</para>
- <para>
- When a block job operation completes, the final status is reported using
- an asynchronous event. To receive this event, register a
- <literal>virConnectDomainEventBlockJobCallback</literal> function which
- will receive the disk, event type, and status as parameters.
- </para>
-
<programlisting>
<![CDATA[/* example blockpull-example.c */
/* compile with: gcc -g -Wall blockpull-example.c -o blockpull-example -lvirt */
8 years, 9 months
[libvirt_application_development_guide_using_python] General - removed Event Loop Integration from the Connections Chapter and created a new chapter for
by David Ashley
commit 335fae968928110755ec02422b6463e5676fec93
Author: W. David Ashley <w.david.ashley(a)gmail.com>
Date: Wed Jul 8 10:54:35 2015 -0500
General
- removed Event Loop Integration from the Connections Chapter and created a new chapter for it
- removed Debugging section from the Connections chapter and created a new chapter for it
- removed Security Model section from the Connections chapter and created a new chapter for it
- added the index
en-US/Connections.xml | 137 --------------------
en-US/Debugging.xml | 122 +++++++++++++++++
en-US/Event_Loop_Integration.xml | 15 ++
..._Application_Development_Guide_Using_Python.xml | 4 +
en-US/Security_Model.xml | 15 ++
5 files changed, 156 insertions(+), 137 deletions(-)
---
diff --git a/en-US/Connections.xml b/en-US/Connections.xml
index f46cfcb..b08c64c 100644
--- a/en-US/Connections.xml
+++ b/en-US/Connections.xml
@@ -1195,141 +1195,4 @@ command -p port [-l username] hostname netcat -U socket
</section>
- <section id="libvirt_application_development_guide_using_python-Connections-Event_Loop">
- <title>Event loop integration</title>
- <indexterm><primary>Event loop integration</primary></indexterm>
- <para>
- Unlike the libvirt C interface, the Python libvirt module does not provide a
- mechanism for event loop integration. This is a known problem and may be addressed
- in a future version of the libvirt module.
- </para>
- </section>
-
- <section id="libvirt_application_development_guide_using_python-Connections-Security">
- <title>Security model</title>
- <indexterm><primary>Security model</primary></indexterm>
- <para>
- Unlike the libvirt C interface, the Python libvirt module does not provide a
- mechanism for accessing the security model. This is a known problem and may be addressed
- in a future version of the libvirt module.
- </para>
- </section>
-
- <section id="libvirt_application_development_guide_using_python-Connections-Debug">
- <title>Debugging / logging</title>
- <indexterm><primary>Debugging</primary></indexterm>
- <indexterm><primary>Logging</primary></indexterm>
- <para>
- Libvirt includes logging facilities to facilitate the tracing of library
- execution. These logs will frequently be requested when trying to
- obtain support for libvirt, so familiarity with them is essential.
- </para>
- <para>
- The logging facilities in libvirt are based on 3 key concepts:
- </para>
- <orderedlist>
- <listitem>
- <para>
- Log messages - generated at runtime by the libvirt code, they include
- a timestamp, a priority level (DEBUG = 1, INFO = 2, WARNING = 3, ERROR = 4),
- a category, function name and line number indicating where the
- message originated from, and a formatted message.
- </para>
- </listitem>
- <listitem>
- <para>
- Log filters - patterns and priorities which control whether or
- not a particular message is displayed. The format for a filter is:
- </para>
- <para><screen>x:name</screen></para>
- <para>
- where "x" is the minimal priority level where the match should apply, and
- "name" is a string to match against. The priority levels are:
- </para>
- <itemizedlist>
- <listitem><para>1 (or debug) - log all messages</para></listitem>
- <listitem><para>2 (or info) - log all non-debugging information</para></listitem>
- <listitem><para>3 (or warn) - log only warnings and errors - this is the default</para></listitem>
- <listitem><para>4 (or error) - log only errors</para></listitem>
- </itemizedlist>
- <para>
- For instance, to log all debug messages to the qemu driver, the
- following filter can be used:
- </para>
- <para><screen>1:qemu</screen></para>
- <para>
- Multiple filters can be specified together by space separating them;
- the following example logs all debug messages from qemu, and logs
- all error messages from the remote driver:
- </para>
- <para><screen>1:qemu 4:remote</screen></para>
- </listitem>
- <listitem>
- <para>
- Log outputs - where to send the message once it has passed
- through filters. The format for a log output is one of the forms:
- </para>
- <para>
-<screen>x:stderr - log to stderr
-x:syslog:name - log to syslog with a prefix of "name"
-x:file:file_path - log to a file specified by "file_path"</screen>
- </para>
- <para>
- where "x" is the minimal priority level. For instance, to log all
- warnings and errors to syslog with a prefix of "libvirtd", the
- following output can be used:
- </para>
- <para><screen>3:syslog:libvirtd</screen></para>
- <para>
- Multiple outputs can be specified by space separating them; the
- following example logs all error and warning messages to syslog, and
- logs all debug, information, warning, and error messages to
- <filename>/tmp/libvirt.log</filename>:
- </para>
- <para><screen>3:syslog:libvirtd 1:file:/tmp/libvirt.log</screen></para>
- </listitem>
- </orderedlist>
-
- <section>
- <title>Environment Variables</title>
- <para>
- The desired log priority level, filters, and outputs are specified to
- the libvirt library through the use of environment variables:
- </para>
- <orderedlist>
- <listitem>
- <para>
- <literal>LIBVIRT_DEBUG</literal> specifies the minimum priority level messages that
- will be logged. This can be thought of as a "global" priority level;
- if a particular log message does not match a specific filter in
- <literal>LIBVIRT_LOG_FILTERS</literal>, it will be compared to this global priority and
- logged as appropriate.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>LIBVIRT_LOG_FILTERS</literal> specifies the filters to apply.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>LIBVIRT_LOG_OUTPUTS</literal> specifies the outputs to send the message to.
- </para>
- </listitem>
- </orderedlist>
- <example>
- <title>Running virsh with environment variables</title>
- <para>
- To see more detailed information about what is going on with virsh,
- we may run it like the following:
- </para>
-<screen><command>LIBVIRT_DEBUG=error LIBVIRT_LOG_FILTERS="1:remote" virsh list</command></screen>
- <para>
- This example will only print error messages from virsh, <emphasis>except</emphasis> that
- the remote driver will print all debug, information, warning, and
- error messages.
- </para>
- </example>
- </section>
- </section>
</chapter>
diff --git a/en-US/Debugging.xml b/en-US/Debugging.xml
new file mode 100644
index 0000000..e118249
--- /dev/null
+++ b/en-US/Debugging.xml
@@ -0,0 +1,122 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "Libvirt_Application_Development_Guide_Using_Python.ent">
+%BOOK_ENTITIES;
+]>
+<chapter id="libvirt_application_development_guide_using_python-Debug">
+ <title>Debugging / Logging</title>
+ <indexterm><primary>Debugging</primary></indexterm>
+ <indexterm><primary>Logging</primary></indexterm>
+ <para>
+ Libvirt includes logging facilities to facilitate the tracing of library
+ execution. These logs will frequently be requested when trying to
+ obtain support for libvirt, so familiarity with them is essential.
+ </para>
+ <para>
+ The logging facilities in libvirt are based on 3 key concepts:
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ Log messages - generated at runtime by the libvirt code, they include
+ a timestamp, a priority level (DEBUG = 1, INFO = 2, WARNING = 3, ERROR = 4),
+ a category, function name and line number indicating where the
+ message originated from, and a formatted message.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Log filters - patterns and priorities which control whether or
+ not a particular message is displayed. The format for a filter is:
+ </para>
+ <para><screen>x:name</screen></para>
+ <para>
+ where "x" is the minimal priority level where the match should apply, and
+ "name" is a string to match against. The priority levels are:
+ </para>
+ <itemizedlist>
+ <listitem><para>1 (or debug) - log all messages</para></listitem>
+ <listitem><para>2 (or info) - log all non-debugging information</para></listitem>
+ <listitem><para>3 (or warn) - log only warnings and errors - this is the default</para></listitem>
+ <listitem><para>4 (or error) - log only errors</para></listitem>
+ </itemizedlist>
+ <para>
+ For instance, to log all debug messages to the qemu driver, the
+ following filter can be used:
+ </para>
+ <para><screen>1:qemu</screen></para>
+ <para>
+ Multiple filters can be specified together by space separating them;
+ the following example logs all debug messages from qemu, and logs
+ all error messages from the remote driver:
+ </para>
+ <para><screen>1:qemu 4:remote</screen></para>
+ </listitem>
+ <listitem>
+ <para>
+ Log outputs - where to send the message once it has passed
+ through filters. The format for a log output is one of the forms:
+ </para>
+ <para>
+<screen>x:stderr - log to stderr
+x:syslog:name - log to syslog with a prefix of "name"
+x:file:file_path - log to a file specified by "file_path"</screen>
+ </para>
+ <para>
+ where "x" is the minimal priority level. For instance, to log all
+ warnings and errors to syslog with a prefix of "libvirtd", the
+ following output can be used:
+ </para>
+ <para><screen>3:syslog:libvirtd</screen></para>
+ <para>
+ Multiple outputs can be specified by space separating them; the
+ following example logs all error and warning messages to syslog, and
+ logs all debug, information, warning, and error messages to
+ <filename>/tmp/libvirt.log</filename>:
+ </para>
+ <para><screen>3:syslog:libvirtd 1:file:/tmp/libvirt.log</screen></para>
+ </listitem>
+ </orderedlist>
+
+ <section>
+ <title>Environment Variables</title>
+ <para>
+ The desired log priority level, filters, and outputs are specified to
+ the libvirt library through the use of environment variables:
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ <literal>LIBVIRT_DEBUG</literal> specifies the minimum priority level messages that
+ will be logged. This can be thought of as a "global" priority level;
+ if a particular log message does not match a specific filter in
+ <literal>LIBVIRT_LOG_FILTERS</literal>, it will be compared to this global priority and
+ logged as appropriate.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>LIBVIRT_LOG_FILTERS</literal> specifies the filters to apply.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>LIBVIRT_LOG_OUTPUTS</literal> specifies the outputs to send the message to.
+ </para>
+ </listitem>
+ </orderedlist>
+ <example>
+ <title>Running virsh with environment variables</title>
+ <para>
+ To see more detailed information about what is going on with virsh,
+ we may run it like the following:
+ </para>
+<screen><command>LIBVIRT_DEBUG=error LIBVIRT_LOG_FILTERS="1:remote" virsh list</command></screen>
+ <para>
+ This example will only print error messages from virsh, <emphasis>except</emphasis> that
+ the remote driver will print all debug, information, warning, and
+ error messages.
+ </para>
+ </example>
+ </section>
+</chapter>
diff --git a/en-US/Event_Loop_Integration.xml b/en-US/Event_Loop_Integration.xml
new file mode 100644
index 0000000..22977f8
--- /dev/null
+++ b/en-US/Event_Loop_Integration.xml
@@ -0,0 +1,15 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "Libvirt_Application_Development_Guide_Using_Python.ent">
+%BOOK_ENTITIES;
+]>
+<chapter id="libvirt_application_development_guide_using_python-Event_Loop">
+ <title>Event Loop Integration</title>
+ <indexterm><primary>Event loop integration</primary></indexterm>
+ <para>
+ Unlike the libvirt C interface, the Python libvirt module does not provide a
+ mechanism for event loop integration. This is a known problem and may be addressed
+ in a future version of the libvirt module.
+ </para>
+
+</chapter>
diff --git a/en-US/Libvirt_Application_Development_Guide_Using_Python.xml b/en-US/Libvirt_Application_Development_Guide_Using_Python.xml
index 39d4cbb..efe3256 100644
--- a/en-US/Libvirt_Application_Development_Guide_Using_Python.xml
+++ b/en-US/Libvirt_Application_Development_Guide_Using_Python.xml
@@ -16,5 +16,9 @@
<xi:include href="Host_Devices.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Error_Handling.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Event_Handling.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Event_Loop_Integration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Security_Model.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Debugging.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <index></index>
</book>
diff --git a/en-US/Security_Model.xml b/en-US/Security_Model.xml
new file mode 100644
index 0000000..b5d2da7
--- /dev/null
+++ b/en-US/Security_Model.xml
@@ -0,0 +1,15 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "Libvirt_Application_Development_Guide_Using_Python.ent">
+%BOOK_ENTITIES;
+]>
+
+<chapter id="libvirt_application_development_guide_using_python-Security">
+ <title>Security Model</title>
+ <indexterm><primary>Security model</primary></indexterm>
+ <para>
+ Unlike the libvirt C interface, the Python libvirt module does not provide a
+ mechanism for accessing the security model. This is a known problem and may be addressed
+ in a future version of the libvirt module.
+ </para>
+</chapter>
8 years, 9 months
[libvirt_application_development_guide_using_python] Connections chapter - added index entries to the chapter
by David Ashley
commit 1a741e49058fdbe46f0646d413184fba1ba72930
Author: W. David Ashley <w.david.ashley(a)gmail.com>
Date: Wed Jul 8 10:35:45 2015 -0500
Connections chapter
- added index entries to the chapter
en-US/Connections.xml | 76 ++++++++++++++++++++++++++++++++++++++++++++----
1 files changed, 69 insertions(+), 7 deletions(-)
---
diff --git a/en-US/Connections.xml b/en-US/Connections.xml
index e6ab7e8..f46cfcb 100644
--- a/en-US/Connections.xml
+++ b/en-US/Connections.xml
@@ -5,6 +5,7 @@
]>
<chapter id="libvirt_application_development_guide_using_python-Connections">
<title>Connections</title>
+ <indexterm><primary>Connections</primary></indexterm>
<para>
In libvirt, a connection is the underpinning of every action and
object in the system. Every entity that wants to interact with
@@ -48,6 +49,9 @@ conn = libvirt.openReadOnly(name)</programlisting>
<section>
<title>open</title>
+ <indexterm><primary>open, Connection</primary></indexterm>
+ <indexterm><primary>Connections</primary>
+ <secondary>open</secondary></indexterm>
<para>
The <literal>open</literal> function will attempt to open a
connection for full read-write access. It does not have any scope for
@@ -69,6 +73,9 @@ conn = libvirt.openReadOnly(name)</programlisting>
<section>
<title>openReadOnly</title>
+ <indexterm><primary>openReadOnly, Connection</primary></indexterm>
+ <indexterm><primary>Connections</primary>
+ <secondary>openReadOnly</secondary></indexterm>
<para>
The <literal>openReadOnly</literal> function will attempt to open a connection
for read-only access. Such a connection has a restricted set of method
@@ -91,6 +98,9 @@ conn = libvirt.openReadOnly(name)</programlisting>
<section>
<title>openAuth</title>
+ <indexterm><primary>openAuth, Connection</primary></indexterm>
+ <indexterm><primary>Connections</primary>
+ <secondary>openAuth</secondary></indexterm>
<para>
The <literal>openAuth</literal> function is the most flexible, and effectively
obsoletes the previous two cunctions. It takes an extra parameter providing
@@ -139,6 +149,9 @@ auth_tcp = "sasl"</screen>
<section>
<title>close</title>
+ <indexterm><primary>close, Connection</primary></indexterm>
+ <indexterm><primary>Connections</primary>
+ <secondary>close</secondary></indexterm>
<para>
A connection must be released by calling the <literal>close</literal> method
of the <literal>virConnection</literal> class when no
@@ -160,6 +173,9 @@ auth_tcp = "sasl"</screen>
<section id="libvirt_application_development_guide_using_python-Connections-URI_Formats">
<title>URI formats</title>
+ <indexterm><primary>URI format, Connection</primary></indexterm>
+ <indexterm><primary>Connections</primary>
+ <secondary>URI format</secondary></indexterm>
<para>
Libvirt uses Uniform Resource Identifiers (URIs) to identify hypervisor connections.
Both local and remote hypervisors are addressed by libvirt using URIs.
@@ -184,6 +200,9 @@ driver+unix:///session</screen>
</para>
<table id='supporteddrivers' frame='all'>
<title>Supported Drivers</title>
+ <indexterm><primary>Supported drivers, Connection</primary></indexterm>
+ <indexterm><primary>Connections</primary>
+ <secondary>Supported drivers</secondary></indexterm>
<tgroup cols='2' align='left' colsep='1' rowsep='1'>
<colspec colname='c1' />
<colspec colname='c2' />
@@ -308,6 +327,9 @@ driver+unix:///session</screen>
<section id="libvirt_application_development_guide_using_python-Connections-Remote_URIs">
<title>Remote URIs</title>
+ <indexterm><primary>Remote URIs, Connection</primary></indexterm>
+ <indexterm><primary>Connections</primary>
+ <secondary>Remote URIs</secondary></indexterm>
<para>
Remote URIs have the general form ("[...]" meaning an optional part):
@@ -593,6 +615,9 @@ command -p port [-l username] hostname netcat -U socket
<section id="libvirt_application_development_guide_using_python-Connections-Capability_Info">
<title>Capability information</title>
+ <indexterm><primary>Capability information, Connection</primary></indexterm>
+ <indexterm><primary>Connections</primary>
+ <secondary>Capability information</secondary></indexterm>
<para>
The <literal>getCapabilities</literal> method call can be used to obtain
information about the capabilities of the virtualization host. If
@@ -602,8 +627,8 @@ command -p port [-l username] hostname netcat -U socket
The following
code demonstrates the use of the <literal>getCapabilities</literal> method:
</para>
- <example id="Example-ConnectGetCapabilities">
- <title>Using virConnectGetCapabilities</title>
+ <example id="Example-getCapabilities">
+ <title>Using getCapabilities</title>
<programlisting language="Python"><xi:include href="extras/Connections-Example-8.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
</example>
<para>
@@ -870,6 +895,9 @@ command -p port [-l username] hostname netcat -U socket
<section id="libvirt_application_development_guide_using_python-Connections-Host_Info">
<title>Host information</title>
+ <indexterm><primary>Host information, Connection</primary></indexterm>
+ <indexterm><primary>Connections</primary>
+ <secondary>Host information</secondary></indexterm>
<para>
There are various Python <literal>virConnection</literal> methods that can be used to get
information about the virtualization host, including the hostname, maximum support guest
@@ -878,6 +906,9 @@ command -p port [-l username] hostname netcat -U socket
<section>
<title>getHostname</title>
+ <indexterm><primary>getHost, Connection</primary></indexterm>
+ <indexterm><primary>Connections</primary>
+ <secondary>getHost</secondary></indexterm>
<para>
The <command>getHostname</command> method can be used to obtain the hostname
of the virtualization host as returned by gethostname(2). It takes a
@@ -894,9 +925,12 @@ command -p port [-l username] hostname netcat -U socket
</section>
<section>
- <title>virConnectGetMaxVcpus</title>
+ <title>getMaxVcpus</title>
+ <indexterm><primary>getMaxVcpus, Connection</primary></indexterm>
+ <indexterm><primary>Connections</primary>
+ <secondary>getMaxVcpus</secondary></indexterm>
<para>
- The <command>virConnectGetMaxVcpus</command> API call can be used to obtain the maximum
+ The <command>getMaxVcpus</command> method can be used to obtain the maximum
number of virtual CPUs per-guest the underlying virtualization
technology supports. It takes a
virtualization "type" as input (which can be <literal>None</literal>), and if successful,
@@ -912,13 +946,16 @@ command -p port [-l username] hostname netcat -U socket
<section>
<title>getInfo</title>
+ <indexterm><primary>getInfo, Connection</primary></indexterm>
+ <indexterm><primary>Connections</primary>
+ <secondary>getInfo</secondary></indexterm>
<para>
The <command>getInfo</command> method can be used to obtain various information
about the virtualization host. The method returns a Python <literal>list</literal> if
successful and <literal>None</literal> if and error occurred. The Python <literal>list</literal>
contains the following members:
</para>
- <table id='virNodeInfo-structure-mem' frame='all'>
+ <table id='virNodeInfo-class-mem' frame='all'>
<title>virNodeInfo structure members</title>
<tgroup cols='2' align='left' colsep='1' rowsep='1'>
<colspec colname='c1' />
@@ -1016,14 +1053,17 @@ command -p port [-l username] hostname netcat -U socket
<para>
The following code demonstrates the use of <command>virNodeGetInfo</command>:
</para>
- <example id="Example-NodeGetInfo">
- <title>Using virNodeGetInfo</title>
+ <example id="Example-getInfo">
+ <title>Using getInfo</title>
<programlisting language="Python"><xi:include href="extras/Connections-Example-12.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
</example>
</section>
<section>
<title>getCellsFreeMemory</title>
+ <indexterm><primary>getCellsFreeMemory, Connection</primary></indexterm>
+ <indexterm><primary>Connections</primary>
+ <secondary>getCellsFreeMemory</secondary></indexterm>
<para>
The <command>getCellsFreeMemory</command> method can be used to obtain the
amount of free memory (in kilobytes) in some or all of the NUMA
@@ -1042,6 +1082,9 @@ command -p port [-l username] hostname netcat -U socket
<section>
<title>getType</title>
+ <indexterm><primary>getType, Connection</primary></indexterm>
+ <indexterm><primary>Connections</primary>
+ <secondary>getType</secondary></indexterm>
<para>
The <command>getType</command> method can be used to obtain the type of
virtualization in use on this connection.
@@ -1058,6 +1101,9 @@ command -p port [-l username] hostname netcat -U socket
<section>
<title>getVersion</title>
+ <indexterm><primary>getVersion, Connection</primary></indexterm>
+ <indexterm><primary>Connections</primary>
+ <secondary>getVersion</secondary></indexterm>
<para>
The <command>getVersion</command> method can be used to obtain the version of
the host virtualization software in use. If successful it returns a Python string
@@ -1072,6 +1118,9 @@ command -p port [-l username] hostname netcat -U socket
<section>
<title>getLibVersion</title>
+ <indexterm><primary>getLibVersion, Connection</primary></indexterm>
+ <indexterm><primary>Connections</primary>
+ <secondary>getLibVersion</secondary></indexterm>
<para>
The <command>getLibVersion</command> method can be used to obtain the version of
the libvirt software in use on the host.
@@ -1087,6 +1136,9 @@ command -p port [-l username] hostname netcat -U socket
<section>
<title>getURI</title>
+ <indexterm><primary>getURI, Connection</primary></indexterm>
+ <indexterm><primary>Connections</primary>
+ <secondary>getURI</secondary></indexterm>
<para>
The <command>getURI</command> method can be used to obtain the URI for the
current connection. While this is typically the same string that
@@ -1104,6 +1156,9 @@ command -p port [-l username] hostname netcat -U socket
<section>
<title>isEncrypted</title>
+ <indexterm><primary>isEncrypted, Connection</primary></indexterm>
+ <indexterm><primary>Connections</primary>
+ <secondary>isEncrypted</secondary></indexterm>
<para>
The <command>isEncrypted</command> method can be used to find out if a given
connection is encrypted.
@@ -1119,6 +1174,9 @@ command -p port [-l username] hostname netcat -U socket
<section>
<title>isSecure</title>
+ <indexterm><primary>isSecure, Connection</primary></indexterm>
+ <indexterm><primary>Connections</primary>
+ <secondary>isSecure</secondary></indexterm>
<para>
The <command>isSecure</command> method can be used to find out if a given
connection is encrypted. A connection will be classified secure if
@@ -1139,6 +1197,7 @@ command -p port [-l username] hostname netcat -U socket
<section id="libvirt_application_development_guide_using_python-Connections-Event_Loop">
<title>Event loop integration</title>
+ <indexterm><primary>Event loop integration</primary></indexterm>
<para>
Unlike the libvirt C interface, the Python libvirt module does not provide a
mechanism for event loop integration. This is a known problem and may be addressed
@@ -1148,6 +1207,7 @@ command -p port [-l username] hostname netcat -U socket
<section id="libvirt_application_development_guide_using_python-Connections-Security">
<title>Security model</title>
+ <indexterm><primary>Security model</primary></indexterm>
<para>
Unlike the libvirt C interface, the Python libvirt module does not provide a
mechanism for accessing the security model. This is a known problem and may be addressed
@@ -1157,6 +1217,8 @@ command -p port [-l username] hostname netcat -U socket
<section id="libvirt_application_development_guide_using_python-Connections-Debug">
<title>Debugging / logging</title>
+ <indexterm><primary>Debugging</primary></indexterm>
+ <indexterm><primary>Logging</primary></indexterm>
<para>
Libvirt includes logging facilities to facilitate the tracing of library
execution. These logs will frequently be requested when trying to
8 years, 9 months
[libvirt_application_development_guide_using_python] Domains Chapter General - finished the indentation corrections for the whole chapter
by David Ashley
commit bd24262286af1363d998dea05e4b31cf126c81aa
Author: W. David Ashley <w.david.ashley(a)gmail.com>
Date: Wed Jul 8 10:08:51 2015 -0500
Domains Chapter
General
- finished the indentation corrections for the whole chapter
en-US/Guest_Domains.xml | 779 +++++++++++++++++++++++------------------------
1 files changed, 384 insertions(+), 395 deletions(-)
---
diff --git a/en-US/Guest_Domains.xml b/en-US/Guest_Domains.xml
index 8464d53..5e7130a 100644
--- a/en-US/Guest_Domains.xml
+++ b/en-US/Guest_Domains.xml
@@ -761,7 +761,7 @@
</section>
<section id="libvirt_application_development_guide_using_python-Guest_Domains-Domain_Config-Memory_CPU">
- <title>Memory / CPU resources</title>
+ <title>Memory / CPU Resources</title>
<para>
CPU and memory resources can be set at the time the domain is created or dynamically
@@ -800,485 +800,474 @@
</example>
</section>
- <section id="libvirt_application_development_guide_using_python-Guest_Domains-Domain_Config-Lifecycle">
- <title>Lifecycle controls</title>
+ <section id="libvirt_application_development_guide_using_python-Guest_Domains-Domain_Config-Lifecycle">
+ <title>Lifecycle controls</title>
- <para>
- TBD
-
- </para>
-
- </section>
-
- <section id="libvirt_application_development_guide_using_python-Guest_Domains-Domain_Config-Clock">
- <title>Clock sync</title>
+ <para>
+ TBD
+ </para>
- <para>
- TBD
+ </section>
- </para>
+ <section id="libvirt_application_development_guide_using_python-Guest_Domains-Domain_Config-Clock">
+ <title>Clock Sync</title>
- </section>
+ <para>
+ TBD
+ </para>
- <section id="libvirt_application_development_guide_using_python-Guest_Domains-Domain_Config-Features">
- <title>Features</title>
+ </section>
- <para>
- TBD
+ <section id="libvirt_application_development_guide_using_python-Guest_Domains-Domain_Config-Features">
+ <title>Features</title>
- </para>
+ <para>
+ TBD
+ </para>
- </section>
+ </section>
</section>
<section id="libvirt_application_development_guide_using_python-Guest_Domains-Monitoring">
- <title>Monitoring performance</title>
-
- <para>
- Statistical metrics are available for monitoring the utilization rates of domains, vCPUs, memory, block devices, and network interfaces.
- </para>
-
- <section id="libvirt_application_development_guide_using_python-Guest_Domains-Monitoring-Domain">
- <title>Domain performance</title>
+ <title>Monitoring Performance</title>
<para>
- TBD
-
- </para>
-
- </section>
-
- <section id="libvirt_application_development_guide_using_python-Guest_Domains-Monitoring-vCPU">
- <title>vCPU performance</title>
-
- <para>
- TBD
-
+ Statistical metrics are available for monitoring the utilization rates of domains, vCPUs, memory,
+ block devices, and network interfaces.
</para>
- </section>
-
- <section id="libvirt_application_development_guide_using_python-Guest_Domains-Monitoring-IO_stats">
- <title>I/O statistics</title>
-
- <para>
- TBD
+ <section id="libvirt_application_development_guide_using_python-Guest_Domains-Monitoring-Domain">
+ <title>Domain Performance</title>
- </para>
-
- </section>
-
- </section>
-
- <section id="libvirt_application_development_guide_using_python-Guest_Domains-Device_Config">
- <title>Device configuration</title>
-
- <para>
- TBD
-
- </para>
-
- <section id="libvirt_application_development_guide_using_python-Guest_Domains-Device_Config-Emulator">
- <title>Emulator</title>
-
- <para>
- TBD
- </para>
-
- </section>
-
- <section id="libvirt_application_development_guide_using_python-Guest_Domains-Device_Config-Disks">
- <title>Disks</title>
-
- <para>
- TBD
-
- </para>
-
- </section>
-
- <section id="libvirt_application_development_guide_using_python-Guest_Domains-Device_Config-Networking">
- <title>Networking</title>
-
- <para>
- TBD
- </para>
-
- </section>
-
- <section id="libvirt_application_development_guide_using_python-Guest_Domains-Device_Config-Filesystems">
- <title>Filesystems</title>
+ <para>
+ TBD
+ </para>
- <para>
- TBD
- </para>
+ </section>
- </section>
+ <section id="libvirt_application_development_guide_using_python-Guest_Domains-Monitoring-vCPU">
+ <title>vCPU Performance</title>
- <section id="libvirt_application_development_guide_using_python-Guest_Domains-Device_Config-Mice">
- <title>Mice & tablets</title>
+ <para>
+ TBD
+ </para>
- <para>
- TBD
- </para>
+ </section>
- </section>
+ <section id="libvirt_application_development_guide_using_python-Guest_Domains-Monitoring-IO_stats">
+ <title>I/O Statistics</title>
- <section id="libvirt_application_development_guide_using_python-Guest_Domains-Device_Config-USB_Pass">
- <title>USB device passthrough</title>
+ <para>
+ TBD
+ </para>
- <para>
- TBD
- </para>
+ </section>
</section>
- <section id="libvirt_application_development_guide_using_python-Guest_Domains-Device_Config-PCI_Pass">
- <title>PCI device passthrough</title>
-
- <para>
- The PCI device passthrough capability allows a physical PCI device from
- the host machine to be assigned directly to a guest machine.The guest
- OS drivers can use the device hardware directly without relying on any
- driver capabilities from the host OS.
- </para>
-
- <para>
- Some caveats apply when using PCI device passthrough. When a PCI device is
- directly assigned to a guest, migration will not be possible, without
- first hot-unplugging the device from the guest. In addition
- libvirt does not guarantee that direct device assignment is secure, leaving
- security policy decisions to the underlying virtualization technology. Secure
- PCI device passthrough typically requires special hardware capabilities, such
- the VT-d feature for Intel chipset, or IOMMU for AMD chipsets.
- </para>
-
- <para>
- There are two modes in which a PCI device can be attached, "managed" or
- "unmanaged" mode, although at time of writing only KVM supports "managed"
- mode attachment. In managed mode, the configured device will be automatically
- detached from the host OS drivers when the guest is started, and then
- re-attached when the guest shuts down. In unmanaged mode, the device
- must be explicit detached ahead of booting the guest. The guest will
- refuse to start if the device is still attached to the host OS. The
- libvirt 'Node Device' APIs provide a means to detach/reattach PCI devices
- from/to host drivers. Alternatively the host OS may be configured to
- blacklist the PCI devices used for guest, so that they never get attached
- to host OS drivers.
- </para>
-
- <para>
- In both modes, the virtualization technology will always perform a reset
- on the device before starting a guest, and after the guest shuts down.
- This is critical to ensure isolation between host and guest OS. There
- are a variety of ways in which a PCI device can be reset. Some reset
- techniques are limited in scope to a single device/function, while
- others may affect multiple devices at once. In the latter case, it will
- be necessary to co-assign all affect devices to the same guest,
- otherwise a reset will be impossible to do safely. The node device
- APIs can be used to determine whether a device needs to be co-assigned,
- by manually detaching the device and then attempting to perform the
- reset operation. If this succeeds, then it will be possible to assign
- the device to a guest on its own. If it fails, then it will be necessary
- to co-assign the device will others on the same PCI bus. The section
- documenting node device APIs covers this topic in detail, but as a
- quick demonstration the following code checks whether a PCI device
- (represented by a virNodeDevicePtr object instance) can be reset and
- is thus assignable to a guest
- </para>
- <programlisting>
- <![CDATA[
- virNodeDevicePtr dev = ....get virNodeDevicePtr for the PCI device...
-
- if (virNodeDeviceDettach(dev) < 0) {
- fprintf(stderr, "Device cannot be dettached from the host OS drivers\n");
- return;
- }
+ <section id="libvirt_application_development_guide_using_python-Guest_Domains-Device_Config">
+ <title>Device configuration</title>
+
+ <para>
+ TBD
+ </para>
+
+ <section id="libvirt_application_development_guide_using_python-Guest_Domains-Device_Config-Emulator">
+ <title>Emulator</title>
+
+ <para>
+ TBD
+ </para>
+
+ </section>
+
+ <section id="libvirt_application_development_guide_using_python-Guest_Domains-Device_Config-Disks">
+ <title>Disks</title>
+
+ <para>
+ TBD
+ </para>
+
+ </section>
+
+ <section id="libvirt_application_development_guide_using_python-Guest_Domains-Device_Config-Networking">
+ <title>Networking</title>
+
+ <para>
+ TBD
+ </para>
+
+ </section>
+
+ <section id="libvirt_application_development_guide_using_python-Guest_Domains-Device_Config-Filesystems">
+ <title>Filesystems</title>
+
+ <para>
+ TBD
+ </para>
+
+ </section>
+
+ <section id="libvirt_application_development_guide_using_python-Guest_Domains-Device_Config-Mice">
+ <title>Mice & Tablets</title>
+
+ <para>
+ TBD
+ </para>
+
+ </section>
+
+ <section id="libvirt_application_development_guide_using_python-Guest_Domains-Device_Config-USB_Pass">
+ <title>USB Device Passthrough</title>
+
+ <para>
+ TBD
+ </para>
+
+ </section>
+
+ <section id="libvirt_application_development_guide_using_python-Guest_Domains-Device_Config-PCI_Pass">
+ <title>PCI device passthrough</title>
+
+ <para>
+ The PCI device passthrough capability allows a physical PCI device from
+ the host machine to be assigned directly to a guest machine.The guest
+ OS drivers can use the device hardware directly without relying on any
+ driver capabilities from the host OS.
+ </para>
+
+ <para>
+ Some caveats apply when using PCI device passthrough. When a PCI device is
+ directly assigned to a guest, migration will not be possible, without
+ first hot-unplugging the device from the guest. In addition
+ libvirt does not guarantee that direct device assignment is secure, leaving
+ security policy decisions to the underlying virtualization technology. Secure
+ PCI device passthrough typically requires special hardware capabilities, such
+ the VT-d feature for Intel chipset, or IOMMU for AMD chipsets.
+ </para>
+
+ <para>
+ There are two modes in which a PCI device can be attached, "managed" or
+ "unmanaged" mode, although at time of writing only KVM supports "managed"
+ mode attachment. In managed mode, the configured device will be automatically
+ detached from the host OS drivers when the guest is started, and then
+ re-attached when the guest shuts down. In unmanaged mode, the device
+ must be explicit detached ahead of booting the guest. The guest will
+ refuse to start if the device is still attached to the host OS. The
+ libvirt 'Node Device' APIs provide a means to detach/reattach PCI devices
+ from/to host drivers. Alternatively the host OS may be configured to
+ blacklist the PCI devices used for guest, so that they never get attached
+ to host OS drivers.
+ </para>
+
+ <para>
+ In both modes, the virtualization technology will always perform a reset
+ on the device before starting a guest, and after the guest shuts down.
+ This is critical to ensure isolation between host and guest OS. There
+ are a variety of ways in which a PCI device can be reset. Some reset
+ techniques are limited in scope to a single device/function, while
+ others may affect multiple devices at once. In the latter case, it will
+ be necessary to co-assign all affect devices to the same guest,
+ otherwise a reset will be impossible to do safely. The node device
+ APIs can be used to determine whether a device needs to be co-assigned,
+ by manually detaching the device and then attempting to perform the
+ reset operation. If this succeeds, then it will be possible to assign
+ the device to a guest on its own. If it fails, then it will be necessary
+ to co-assign the device will others on the same PCI bus. The section
+ documenting node device APIs covers this topic in detail, but as a
+ quick demonstration the following code checks whether a PCI device
+ (represented by a virNodeDevicePtr object instance) can be reset and
+ is thus assignable to a guest
+ </para>
+ <programlisting>
+ <![CDATA[
+ virNodeDevicePtr dev = ....get virNodeDevicePtr for the PCI device...
+
+ if (virNodeDeviceDettach(dev) < 0) {
+ fprintf(stderr, "Device cannot be dettached from the host OS drivers\n");
+ return;
+ }
+
+ if (virNodeDeviceReset(dev) < 0) {
+ fprintf(stderr, "Device cannot be safely reset without affecting other devices\n");
+ return;
+ }
+
+ fprintf(stderr, "Device is suitable for passthrough to a guest\n");
+ ]]>
+ </programlisting>
+
+ <para>
+ A PCI device is attached to a guest using the 'hostdevice' element.
+ The 'mode' attribute should always be set to 'subsystem', and the
+ 'type' attribute to 'pci'. The 'managed' attribute can be either
+ 'yes' or 'no' as required by the application. Within the 'hostdevice'
+ element there is a 'source' element and within that a further 'address'
+ element is used to specify the PCI device to be attached. The address
+ element expects attributes for 'domain', 'bus', 'slot' and 'function'.
+ This is easiest to see with a short example
+ </para>
+
+ <programlisting>
+ <![CDATA[
+ <hostdev mode='subsystem' type='pci' managed='yes'>
+ <source>
+ <address domain='0x0000'
+ bus='0x06'
+ slot='0x12'
+ function='0x5'/>
+ </source>
+ </hostdev>
+ ]]>
+ </programlisting>
+
+ </section>
- if (virNodeDeviceReset(dev) < 0) {
- fprintf(stderr, "Device cannot be safely reset without affecting other devices\n");
- return;
- }
+ </section>
- fprintf(stderr, "Device is suitable for passthrough to a guest\n");
- ]]>
- </programlisting>
+ <section id="libvirt_application_development_guide_using_python-Guest_Domains-Live_Config">
+ <title>Live Configuration Change</title>
<para>
- A PCI device is attached to a guest using the 'hostdevice' element.
- The 'mode' attribute should always be set to 'subsystem', and the
- 'type' attribute to 'pci'. The 'managed' attribute can be either
- 'yes' or 'no' as required by the application. Within the 'hostdevice'
- element there is a 'source' element and within that a further 'address'
- element is used to specify the PCI device to be attached. The address
- element expects attributes for 'domain', 'bus', 'slot' and 'function'.
- This is easiest to see with a short example
+ TBD
</para>
- <programlisting>
- <![CDATA[
- <hostdev mode='subsystem' type='pci' managed='yes'>
- <source>
- <address domain='0x0000'
- bus='0x06'
- slot='0x12'
- function='0x5'/>
- </source>
- </hostdev>
- ]]>
- </programlisting>
-
- </section>
-
- </section>
+ <section id="libvirt_application_development_guide_using_python-Guest_Domains-Live_Config-Memory">
+ <title>Memory Ballooning</title>
- <section id="libvirt_application_development_guide_using_python-Guest_Domains-Live_Config">
- <title>Live configuration change</title>
+ <para>
+ TBD
+ </para>
- <para>
- TBD
- </para>
+ </section>
- <section id="libvirt_application_development_guide_using_python-Guest_Domains-Live_Config-Memory">
- <title>Memory ballooning</title>
+ <section id="libvirt_application_development_guide_using_python-Guest_Domains-Live_Config-CPU">
+ <title>CPU hotplug</title>
- <para>
- TBD
- </para>
+ <para>
+ TBD
+ </para>
- </section>
+ </section>
- <section id="libvirt_application_development_guide_using_python-Guest_Domains-Live_Config-CPU">
- <title>CPU hotplug</title>
+ <section id="libvirt_application_development_guide_using_python-Guest_Domains-Live_Config-Device_Plug">
+ <title>Device hotplug / unplug</title>
- <para>
- TBD
- </para>
+ <para>
+ TBD
+ </para>
- </section>
+ </section>
- <section id="libvirt_application_development_guide_using_python-Guest_Domains-Live_Config-Device_Plug">
- <title>Device hotplug / unplug</title>
+ <section id="libvirt_application_development_guide_using_python-Guest_Domains-Live_Config-Device_Media">
+ <title>Device media change</title>
- <para>
- TBD
- </para>
+ <para>
+ TBD
+ </para>
- </section>
+ </section>
- <section id="libvirt_application_development_guide_using_python-Guest_Domains-Live_Config-Device_Media">
- <title>Device media change</title>
+ <section id="libvirt_application_development_guide_using_python-Guest_Domains-Live_Config-Block_Jobs">
+ <title>Block Device Jobs</title>
- <para>
- TBD
- </para>
+ <para>
+ Libvirt provides a generic Block Job API that can be used to initiate
+ and manage operations on disks that belong to a domain. Jobs are
+ started by calling the function associated with the desired operation
+ (eg. <literal>virDomainBlockPull</literal>). Once started, all block
+ jobs are managed in the same manner. They can be aborted, throttled,
+ and queried. Upon completion, an asynchronous event is issued to
+ indicate the final status.
+ </para>
- </section>
+ <para>
+ The following block jobs can be started:
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ <literal>virDomainBlockPull()</literal> starts a block pull
+ operation for the specified disk. This operation is valid only for
+ specially configured disks. BlockPull will populate a disk image
+ with data from its backing image. Once all data from its backing
+ image has been pulled, the disk no longer depends on a backing
+ image.
+ </para>
+ </listitem>
+ </orderedlist>
- <section id="libvirt_application_development_guide_using_python-Guest_Domains-Live_Config-Block_Jobs">
- <title>Block Device Jobs</title>
+ <para>
+ A disk can be queried for active block jobs by using
+ <literal>virDomainGetBlockJobInfo()</literal>. If found, job
+ information is reported in a structure that contains: the job type,
+ bandwidth throttling setting, and progress information.
+ </para>
- <para>
- Libvirt provides a generic Block Job API that can be used to initiate
- and manage operations on disks that belong to a domain. Jobs are
- started by calling the function associated with the desired operation
- (eg. <literal>virDomainBlockPull</literal>). Once started, all block
- jobs are managed in the same manner. They can be aborted, throttled,
- and queried. Upon completion, an asynchronous event is issued to
- indicate the final status.
- </para>
+ <para>
+ <literal>virDomainBlockJobAbort()</literal> can be used to cancel the
+ active block job on the specified disk.
+ </para>
- <para>
- The following block jobs can be started:
- </para>
- <orderedlist>
- <listitem>
<para>
- <literal>virDomainBlockPull()</literal> starts a block pull
- operation for the specified disk. This operation is valid only for
- specially configured disks. BlockPull will populate a disk image
- with data from its backing image. Once all data from its backing
- image has been pulled, the disk no longer depends on a backing
- image.
+ Use <literal>virDomainBlockJobSetSpeed()</literal> to limit the amount
+ of bandwidth that a block job may consume. Bandwidth is specified in
+ units of MB/sec.
</para>
- </listitem>
- </orderedlist>
- <para>
- A disk can be queried for active block jobs by using
- <literal>virDomainGetBlockJobInfo()</literal>. If found, job
- information is reported in a structure that contains: the job type,
- bandwidth throttling setting, and progress information.
- </para>
+ <para>
+ When a block job operation completes, the final status is reported using
+ an asynchronous event. To receive this event, register a
+ <literal>virConnectDomainEventBlockJobCallback</literal> function which
+ will receive the disk, event type, and status as parameters.
+ </para>
- <para>
- <literal>virDomainBlockJobAbort()</literal> can be used to cancel the
- active block job on the specified disk.
- </para>
+ <programlisting>
+ <![CDATA[/* example blockpull-example.c */
+ /* compile with: gcc -g -Wall blockpull-example.c -o blockpull-example -lvirt */
+ #include <stdio.h>
+ #include <stdlib.h>
+ #include <unistd.h>
+ #include <libvirt/libvirt.h>
+
+ int do_cmd(const char *cmdline)
+ {
+ int status = system(cmdline);
+ if (status < 0)
+ return -1;
+ else
+ return WEXITSTATUS(status);
+ }
- <para>
- Use <literal>virDomainBlockJobSetSpeed()</literal> to limit the amount
- of bandwidth that a block job may consume. Bandwidth is specified in
- units of MB/sec.
- </para>
+ virDomainPtr make_domain(virConnectPtr conn)
+ {
+ virDomainPtr dom;
+ char domxml[] = \
+ "<domain type='kvm'> \
+ <name>example</name> \
+ <memory>131072</memory> \
+ <vcpu>1</vcpu> \
+ <os> \
+ <type arch='x86_64' machine='pc-0.13'>hvm</type> \
+ </os> \
+ <devices> \
+ <disk type='file' device='disk'> \
+ <driver name='qemu' type='qed'/> \
+ <source file='/var/lib/libvirt/images/example.qed' /> \
+ <target dev='vda' bus='virtio'/> \
+ </disk> \
+ </devices> \
+ </domain>";
+
+ do_cmd("qemu-img create -f raw /var/lib/libvirt/images/backing.qed 100M");
+ do_cmd("qemu-img create -f qed -b /var/lib/libvirt/images/backing.qed \
+ /var/lib/libvirt/images/example.qed");
+
+ dom = virDomainCreateXML(conn, domxml, 0);
+ return dom;
+ }
- <para>
- When a block job operation completes, the final status is reported using
- an asynchronous event. To receive this event, register a
- <literal>virConnectDomainEventBlockJobCallback</literal> function which
- will receive the disk, event type, and status as parameters.
- </para>
+ int main(int argc, char *argv[])
+ {
+ virConnectPtr conn;
+ virDomainPtr dom = NULL;
+ char disk[] = "/var/lib/libvirt/images/example.qed";
- <programlisting>
- <![CDATA[/* example blockpull-example.c */
- /* compile with: gcc -g -Wall blockpull-example.c -o blockpull-example -lvirt */
- #include <stdio.h>
- #include <stdlib.h>
- #include <unistd.h>
- #include <libvirt/libvirt.h>
-
- int do_cmd(const char *cmdline)
- {
- int status = system(cmdline);
- if (status < 0)
- return -1;
- else
- return WEXITSTATUS(status);
- }
-
- virDomainPtr make_domain(virConnectPtr conn)
- {
- virDomainPtr dom;
- char domxml[] = \
- "<domain type='kvm'> \
- <name>example</name> \
- <memory>131072</memory> \
- <vcpu>1</vcpu> \
- <os> \
- <type arch='x86_64' machine='pc-0.13'>hvm</type> \
- </os> \
- <devices> \
- <disk type='file' device='disk'> \
- <driver name='qemu' type='qed'/> \
- <source file='/var/lib/libvirt/images/example.qed' /> \
- <target dev='vda' bus='virtio'/> \
- </disk> \
- </devices> \
- </domain>";
-
- do_cmd("qemu-img create -f raw /var/lib/libvirt/images/backing.qed 100M");
- do_cmd("qemu-img create -f qed -b /var/lib/libvirt/images/backing.qed \
- /var/lib/libvirt/images/example.qed");
-
- dom = virDomainCreateXML(conn, domxml, 0);
- return dom;
- }
-
- int main(int argc, char *argv[])
- {
- virConnectPtr conn;
- virDomainPtr dom = NULL;
- char disk[] = "/var/lib/libvirt/images/example.qed";
-
- conn = virConnectOpen("qemu:///system");
- if (conn == NULL) {
- fprintf(stderr, "Failed to open connection to qemu:///system\n");
- goto error;
- }
+ conn = virConnectOpen("qemu:///system");
+ if (conn == NULL) {
+ fprintf(stderr, "Failed to open connection to qemu:///system\n");
+ goto error;
+ }
- dom = make_domain(conn);
- if (dom == NULL) {
- fprintf(stderr, "Failed to create domain\n");
- goto error;
- }
+ dom = make_domain(conn);
+ if (dom == NULL) {
+ fprintf(stderr, "Failed to create domain\n");
+ goto error;
+ }
- if ((virDomainBlockPull(dom, disk, 0, 0)) < 0) {
- fprintf(stderr, "Failed to start block pull");
- goto error;
- }
+ if ((virDomainBlockPull(dom, disk, 0, 0)) < 0) {
+ fprintf(stderr, "Failed to start block pull");
+ goto error;
+ }
- while (1) {
- virDomainBlockJobInfo info;
- int ret = virDomainGetBlockJobInfo(dom, disk, &info, 0);
-
- if (ret == 1) {
- printf("BlockPull progress: %0.0f %%\n",
- (float)(100 * info.cur / info.end));
- } else if (ret == 0) {
- printf("BlockPull complete\n");
- break;
- } else {
- fprintf(stderr, "Failed to query block jobs\n");
- break;
+ while (1) {
+ virDomainBlockJobInfo info;
+ int ret = virDomainGetBlockJobInfo(dom, disk, &info, 0);
+
+ if (ret == 1) {
+ printf("BlockPull progress: %0.0f %%\n",
+ (float)(100 * info.cur / info.end));
+ } else if (ret == 0) {
+ printf("BlockPull complete\n");
+ break;
+ } else {
+ fprintf(stderr, "Failed to query block jobs\n");
+ break;
+ }
+ usleep(100000);
}
- usleep(100000);
- }
- error:
- unlink("/var/lib/libvirt/images/backing.qed");
- unlink("/var/lib/libvirt/images/example.qed");
- if (dom != NULL) {
- virDomainDestroy(dom);
- virDomainFree(dom);
- }
- if (conn != NULL)
- virConnectClose(conn);
- return 0;
- }]]>
- </programlisting>
+ error:
+ unlink("/var/lib/libvirt/images/backing.qed");
+ unlink("/var/lib/libvirt/images/example.qed");
+ if (dom != NULL) {
+ virDomainDestroy(dom);
+ virDomainFree(dom);
+ }
+ if (conn != NULL)
+ virConnectClose(conn);
+ return 0;
+ }]]>
+ </programlisting>
- </section>
+ </section>
</section>
<section id="libvirt_application_development_guide_using_python-Guest_Domains-Guest_Domains-Security">
- <title>Security model</title>
+ <title>Security Model</title>
- <para>
- TBD
- </para>
+ <para>
+ TBD
+ </para>
</section>
<section id="libvirt_application_development_guide_using_python-Guest_Domains-Event_Not">
- <title>Event notifications</title>
+ <title>Event Notifications</title>
- <para>
- TBD
-
- </para>
+ <para>
+ TBD
+ </para>
</section>
<section id="libvirt_application_development_guide_using_python-Guest_Domains-Tuning">
- <title>Tuning</title>
-
- <para>
- TBD
-
- </para>
-
- <section id="libvirt_application_development_guide_using_python-Guest_Domains-Tuning-Schedular">
- <title>Scheduler parameters</title>
+ <title>Tuning</title>
<para>
- TBD
-
+ TBD
</para>
- </section>
+ <section id="libvirt_application_development_guide_using_python-Guest_Domains-Tuning-Schedular">
+ <title>Scheduler Parameters</title>
- <section id="libvirt_application_development_guide_using_python-Guest_Domains-Tuning-NUMA">
- <title>NUMA placement</title>
+ <para>
+ TBD
+ </para>
- <para>
- TBD
+ </section>
- </para>
+ <section id="libvirt_application_development_guide_using_python-Guest_Domains-Tuning-NUMA">
+ <title>NUMA Placement</title>
- </section>
+ <para>
+ TBD
+ </para>
- </section>
+ </section>
+
+ </section>
</chapter>
8 years, 9 months
[libvirt_application_development_guide_using_python] Domains Chapter Memory / CPU resources - added complete content - added examples 27-30
by David Ashley
commit 25c2bd67b6731c5f568f8338cef854cb090aa001
Author: W. David Ashley <w.david.ashley(a)gmail.com>
Date: Sun Jul 5 18:07:21 2015 -0500
Domains Chapter
Memory / CPU resources
- added complete content
- added examples 27-30
en-US/Guest_Domains.xml | 46 ++++++++++++++++++++++++++++------
en-US/extras/Domains-Example-27.xml | 5 ++++
en-US/extras/Domains-Example-28.xml | 7 +++++
en-US/extras/Domains-Example-29.py | 21 ++++++++++++++++
en-US/extras/Domains-Example-30.py | 21 ++++++++++++++++
5 files changed, 92 insertions(+), 8 deletions(-)
---
diff --git a/en-US/Guest_Domains.xml b/en-US/Guest_Domains.xml
index ce78e1e..8464d53 100644
--- a/en-US/Guest_Domains.xml
+++ b/en-US/Guest_Domains.xml
@@ -760,15 +760,45 @@
</section>
- <section id="libvirt_application_development_guide_using_python-Guest_Domains-Domain_Config-Memory_CPU">
- <title>Memory / CPU resources</title>
+ <section id="libvirt_application_development_guide_using_python-Guest_Domains-Domain_Config-Memory_CPU">
+ <title>Memory / CPU resources</title>
- <para>
- TBD. Maps to the basic resources section.
-
- </para>
-
- </section>
+ <para>
+ CPU and memory resources can be set at the time the domain is created or dynamically
+ while the domain is either active or inactive.
+ </para>
+ <para>
+ CPU resources are set at domain creation using tags in the XML definition of the domain.
+ The hypervisor defines a limit on the number of virtual CPUs that may not be exceeded
+ either at domain creation or at a later time. This maximum can be dependent on a number of
+ resource and hypervisor limits. An example of the CPU XML specification follows.
+ </para>
+ <programlisting language="XML"><xi:include href="extras/Domains-Example-27.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ <para>
+ Memory resources are also set at domain creation using tags in the XML definition of the domain.
+ Both the maximum and the current allocation of memory to the domain should be set.
+ An example of the Memory XML specification follows.
+ </para>
+ <programlisting language="XML"><xi:include href="extras/Domains-Example-28.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ <para>
+ After the domain has been created the number of virtual CPUs can be increased via the
+ <literal>setVcpus</literal> or the <literal>setVcpusFlags</literal> methods. The
+ number CPUs may not exceed the hypervisor maximum discussed above.
+ </para>
+ <example>
+ <title>Set the number of maximum virtual cpus for a domain</title>
+ <programlisting language="Python"><xi:include href="extras/Domains-Example-29.py" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ </example>
+ <para>
+ Also after the domain has been created the amount of memory can be changes via the
+ <literal>setMemory</literal> or the <literal>setMemoryFlags</literal> methods. The
+ amount of memory should be expressed in kilobytes.
+ </para>
+ <example>
+ <title>Set the amount of memory for a domain</title>
+ <programlisting language="Python"><xi:include href="extras/Domains-Example-30.py" 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-Lifecycle">
<title>Lifecycle controls</title>
diff --git a/en-US/extras/Domains-Example-27.xml b/en-US/extras/Domains-Example-27.xml
new file mode 100644
index 0000000..3e617d9
--- /dev/null
+++ b/en-US/extras/Domains-Example-27.xml
@@ -0,0 +1,5 @@
+<domain>
+ ...
+ <vcpu placement='static' cpuset="1-4,^3,6" current="1">2</vcpu>
+ ...
+</domain>
diff --git a/en-US/extras/Domains-Example-28.xml b/en-US/extras/Domains-Example-28.xml
new file mode 100644
index 0000000..0af025c
--- /dev/null
+++ b/en-US/extras/Domains-Example-28.xml
@@ -0,0 +1,7 @@
+<domain>
+ ...
+ <maxMemory slots='16' unit='KiB'>1524288</maxMemory>
+ <memory unit='KiB'>524288</memory>
+ <currentMemory unit='KiB'>524288</currentMemory>
+ ...
+</domain>
diff --git a/en-US/extras/Domains-Example-29.py b/en-US/extras/Domains-Example-29.py
new file mode 100644
index 0000000..51e19d1
--- /dev/null
+++ b/en-US/extras/Domains-Example-29.py
@@ -0,0 +1,21 @@
+# Example-29.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.setVcpus(2)
+
+conn.close()
+exit(0)
diff --git a/en-US/extras/Domains-Example-30.py b/en-US/extras/Domains-Example-30.py
new file mode 100644
index 0000000..0af77cd
--- /dev/null
+++ b/en-US/extras/Domains-Example-30.py
@@ -0,0 +1,21 @@
+# Example-29.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.setMemory(4096) # 4 GigaBytes
+
+conn.close()
+exit(0)
8 years, 9 months