* doc/*: augment and try to complete the doc in its current state

Daniel
author: Daniel Veillard <veillard@redhat.com> 2006-01-23 13:24:07 +0000
committer: Daniel Veillard <veillard@redhat.com> 2006-01-23 13:24:07 +0000
commit: d0a71d23da4010677c57a6a1467bfa4d711f4ca6 (patch)
tree: 734a58efbf14330fcf4ed5ce83a24dbb39a16e24
parent: Updated and fixed a broken link, Daniel (diff)
download: libvirt-d0a71d23da4010677c57a6a1467bfa4d711f4ca6.tar.gz
libvirt-d0a71d23da4010677c57a6a1467bfa4d711f4ca6.tar.bz2
libvirt-d0a71d23da4010677c57a6a1467bfa4d711f4ca6.zip
8 files changed, 94 insertions, 45 deletions
diff --git a/ChangeLog b/ChangeLog
index a331566e6..4a8d87ad0 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+Mon Jan 23 14:23:16 CET 2006 Daniel Veillard <veillard@redhat.com>
+
+	* doc/*: augment and try to complete the doc in its current state
+
 Sun Jan 22 17:26:20 CET 2006 Daniel Veillard <veillard@redhat.com>
 
 	* doc/*: started to augment and update the documentation
diff --git a/docs/FAQ.html b/docs/FAQ.html
index 1c4a8fee4..381ce3678 100644
--- a/docs/FAQ.html
+++ b/docs/FAQ.html
@@ -34,11 +34,13 @@
     <p><code>make rpm</code></p>
   </li>
   <li><em>Failure to use the API for non-root users</em>
-    <p>Large parts of the API are only accessible as root, however the read
-    only access to the xenstore data doesnot have to be forbidden to user, at
-    least for monitoring purposes. If "virsh info" fails to run as an user,
-    change the mode of the xenstore read-only socket with:</p>
+    <p>Large parts of the API may only be accessible with root priviledges,
+    however the read only access to the xenstore data doesnot have to be
+    forbidden to user, at least for monitoring purposes. If "virsh info"
+    fails to run as an user, change the mode of the xenstore read-only socket
+    with:</p>
     <p><code>chmod 666 /var/run/xenstored/socket_ro</code></p>
+    <p>and also make sure that the Xen Daemon is running correctly</p>
   </li>
 </ol><h3><a name="Compilatio" id="Compilatio">Compilation</a></h3><ol><li><em>What is the process to compile libvir ?</em>
     <p>As most UNIX libraries libvir follows the "standard":</p>
diff --git a/docs/architecture.html b/docs/architecture.html
index 28ea60a37..516638993 100644
--- a/docs/architecture.html
+++ b/docs/architecture.html
@@ -1,21 +1,25 @@
 <?xml version="1.0" encoding="ISO-8859-1"?>
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /><link rel="stylesheet" type="text/css" href="libvir.css" /><title>libvir architecture</title></head><body><div id="container"><div id="intro"><div id="adjustments"></div><div id="pageHeader"></div><div id="content2"><h1 class="style1">libvir architecture</h1><p>In a Xen environment, programs using libvir have to execute in "Domain 0",
-which is the primary Linux OS loaded on the machine. That OS kernel provides
-most if not all of the actual drivers used by the set of domains. It also
-runs the Xen Store, a database of informations shared by the hypervisor, the
-kernels, the drivers and the xen daemon. Xend, the xen daemon, also runs in
-Domain0 and supervise the control and execution of the sets of domains. The
-hypervisor, drivers, kernels and daemons communicate though a shared system
-bus implemented in the hypervisor. The figure below tries to provide a view
-of this environment:</p><img src="architecture.gif" alt="The Xen architecture" /><p>The library can be initialized in 2 ways depending on the level of
+<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /><link rel="stylesheet" type="text/css" href="libvir.css" /><title>libvir architecture</title></head><body><div id="container"><div id="intro"><div id="adjustments"></div><div id="pageHeader"></div><div id="content2"><h1 class="style1">libvir architecture</h1><p>When running in a Xen environment, programs using libvir have to execute
+in "Domain 0", which is the primary Linux OS loaded on the machine. That OS
+kernel provides most if not all of the actual drivers used by the set of
+domains. It also runs the Xen Store, a database of informations shared by the
+hypervisor, the kernels, the drivers and the xen daemon. Xend. The xen daemon
+supervise the control and execution of the sets of domains. The hypervisor,
+drivers, kernels and daemons communicate though a shared system bus
+implemented in the hypervisor. The figure below tries to provide a view of
+this environment:</p><img src="architecture.gif" alt="The Xen architecture" /><p>The library can be initialized in 2 ways depending on the level of
 priviledge of the embedding program. If it runs with root access,
 virConnectOpen() can be used, it will use three different ways to connect to
 the Xen infrastructure:</p><ul><li>a connection to the Xen Daemon though an HTTP RPC layer</li>
   <li>a read/write connection to the Xen Store</li>
   <li>use Xen Hypervisor calls</li>
-</ul><p> If it runs without root access virConnectOpenReadOnly() should be used,
-it will try to open the read-only socket
+</ul><p>The library will usually interract with the Xen daemon for any operation
+changing the state of the system, but for performance and accuracy reasons
+may talk directly to the hypervisor when gathering state informations at
+least when possible (i.e. when the running program using libvir has root
+priviledge access). </p><p> If it runs without root access virConnectOpenReadOnly() should be used to
+connect to initialize the library. It will try to open the read-only socket
 <code>/var/run/xenstored/socket_ro</code> to connect to the Xen Store and
 also try to use the RPC to the Xen daemon. In this case use of hypervisor
 calls and write to the Xen Store will not be possible, restraining the amount
diff --git a/docs/bugs.html b/docs/bugs.html
index a366d1451..8a93d5834 100644
--- a/docs/bugs.html
+++ b/docs/bugs.html
@@ -6,5 +6,5 @@ archive</a>. Please subscribe to this list before posting by visiting the <a hre
 page and follow the instructions. Patches with explanations and provided as
 attachments are really appreciated and will be discussed on the mailing list.
 If possible generate the patches by using cvs diff -u in a CVS checkout.</p><p>We expect to use <a href="https://bugzilla.redhat.com/">Red Hat
-Bugzilla</a> to track bugs for libvir, though there isn't yet a libvir
-software module.</p></div></div><div class="linkList2"><div class="llinks2"><h3 class="links2"><span>main menu</span></h3><ul><li><a href="index.html">Home</a></li><li><a href="news.html">Releases</a></li><li><a href="intro.html">Introduction</a></li><li><a href="architecture.html">libvir architecture</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a style="font-weight:bold" href="html/index.html">API Menu</a></li><li><a href="ChangeLog.html">Recent Changes</a></li></ul></div><div class="llinks2"><h3 class="links2"><span>related links</span></h3><ul><li><a href="https://www.redhat.com/archives/libvir-list/">Mail archive</a></li><li><a href="http://www.cl.cam.ac.uk/Research/SRG/netos/xen/index.html">Xen project</a></li><li><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="12" value="Search..." /><input name="submit" type="submit" value="Go" /></form></li><li><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-90x34.gif" alt="Made with Libxml2 Logo" /></a></li></ul></div></div><div id="bottom"><p class="p1"></p></div></div></body></html>
+Bugzilla</a> to track bugs for libvir, though there isn't a libvir software
+module defined yet, in the meantime use the mailing-list, thanks !.</p></div></div><div class="linkList2"><div class="llinks2"><h3 class="links2"><span>main menu</span></h3><ul><li><a href="index.html">Home</a></li><li><a href="news.html">Releases</a></li><li><a href="intro.html">Introduction</a></li><li><a href="architecture.html">libvir architecture</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a style="font-weight:bold" href="html/index.html">API Menu</a></li><li><a href="ChangeLog.html">Recent Changes</a></li></ul></div><div class="llinks2"><h3 class="links2"><span>related links</span></h3><ul><li><a href="https://www.redhat.com/archives/libvir-list/">Mail archive</a></li><li><a href="http://www.cl.cam.ac.uk/Research/SRG/netos/xen/index.html">Xen project</a></li><li><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="12" value="Search..." /><input name="submit" type="submit" value="Go" /></form></li><li><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-90x34.gif" alt="Made with Libxml2 Logo" /></a></li></ul></div></div><div id="bottom"><p class="p1"></p></div></div></body></html>
diff --git a/docs/intro.html b/docs/intro.html
index aa5e4539f..7c246cb9e 100644
--- a/docs/intro.html
+++ b/docs/intro.html
@@ -2,15 +2,14 @@
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /><link rel="stylesheet" type="text/css" href="libvir.css" /><title>Introduction</title></head><body><div id="container"><div id="intro"><div id="adjustments"></div><div id="pageHeader"></div><div id="content2"><h1 class="style1">Introduction</h1><p>Libvir is a C toolkit to interract with the virtualization capabilities of
 recent versions of Linux (and other OSes), but ibvir won't try to provide all
-possible interfaces for interacting with the virtualization features of a set
-of Linux (or other OS) system.</p><p>To avoid ambiguity about the terms used here here are the definitions for
+possible interfaces for interacting with the virtualization features.</p><p>To avoid ambiguity about the terms used here here are the definitions for
 soem of the specific terms used in libvir documentation:</p><ul><li>a <strong>node</strong> is a single physical machine</li>
   <li>an <strong>hypervisor</strong> is a layer of software allowing to
     virtualize a node in a set of virtual machines with possibly different
     configurations than the node itself</li>
   <li>a <strong>domain</strong> is an instance of an operating system running
     on a virtualized machine</li>
-</ul><p>Now we can define the goal of libvir: to provide the lowest possible
+</ul><p style="text-align: center"><img alt="Hypervisor and domains running on a node" src="node.gif" /></p><p>Now we can define the goal of libvir: to provide the lowest possible
 generic and stable layer to manage domains on a node.</p><p>This implies the following:</p><ul><li>the API should not be targetted to a single virtualization environment
     though Xen is the current default, which also means that some very
     specific capabilities which are not generic enough may not be provided as
@@ -26,4 +25,6 @@ generic and stable layer to manage domains on a node.</p><p>This implies the fol
 </ul><p>So libvir should be a building block for higher level management tools or
 for applications focusing on virtualization on a single node (the only
 exception being domain migration between node capabilities which may need to
-be added at the libvir level)</p><p> </p><p></p></div></div><div class="linkList2"><div class="llinks2"><h3 class="links2"><span>main menu</span></h3><ul><li><a href="index.html">Home</a></li><li><a href="news.html">Releases</a></li><li><a href="intro.html">Introduction</a></li><li><a href="architecture.html">libvir architecture</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a style="font-weight:bold" href="html/index.html">API Menu</a></li><li><a href="ChangeLog.html">Recent Changes</a></li></ul></div><div class="llinks2"><h3 class="links2"><span>related links</span></h3><ul><li><a href="https://www.redhat.com/archives/libvir-list/">Mail archive</a></li><li><a href="http://www.cl.cam.ac.uk/Research/SRG/netos/xen/index.html">Xen project</a></li><li><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="12" value="Search..." /><input name="submit" type="submit" value="Go" /></form></li><li><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-90x34.gif" alt="Made with Libxml2 Logo" /></a></li></ul></div></div><div id="bottom"><p class="p1"></p></div></div></body></html>
+be added at the libvir level). Where possible libvir should be extendable to
+be able to provide the same API for remote nodes, however this is not the
+case at the moment, the code currently handle only local node access.</p></div></div><div class="linkList2"><div class="llinks2"><h3 class="links2"><span>main menu</span></h3><ul><li><a href="index.html">Home</a></li><li><a href="news.html">Releases</a></li><li><a href="intro.html">Introduction</a></li><li><a href="architecture.html">libvir architecture</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a style="font-weight:bold" href="html/index.html">API Menu</a></li><li><a href="ChangeLog.html">Recent Changes</a></li></ul></div><div class="llinks2"><h3 class="links2"><span>related links</span></h3><ul><li><a href="https://www.redhat.com/archives/libvir-list/">Mail archive</a></li><li><a href="http://www.cl.cam.ac.uk/Research/SRG/netos/xen/index.html">Xen project</a></li><li><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="12" value="Search..." /><input name="submit" type="submit" value="Go" /></form></li><li><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-90x34.gif" alt="Made with Libxml2 Logo" /></a></li></ul></div></div><div id="bottom"><p class="p1"></p></div></div></body></html>
diff --git a/docs/libvir.html b/docs/libvir.html
index cdf2e6f82..fe69da8e0 100644
--- a/docs/libvir.html
+++ b/docs/libvir.html
@@ -44,8 +44,7 @@ and check the <a href="ChangeLog.html">ChangeLog</a> to gauge progresses.</p>
 
 <p>Libvir is a C toolkit to interract with the virtualization capabilities of
 recent versions of Linux (and other OSes), but ibvir won't try to provide all
-possible interfaces for interacting with the virtualization features of a set
-of Linux (or other OS) system.</p>
+possible interfaces for interacting with the virtualization features.</p>
 
 <p>To avoid ambiguity about the terms used here here are the definitions for
 soem of the specific terms used in libvir documentation:</p>
@@ -58,6 +57,9 @@ soem of the specific terms used in libvir documentation:</p>
     on a virtualized machine</li>
 </ul>
 
+<p style="text-align: center"><img
+alt="Hypervisor and domains running on a node" src="node.gif"></p>
+
 <p>Now we can define the goal of libvir: to provide the lowest possible
 generic and stable layer to manage domains on a node.</p>
 
@@ -80,23 +82,21 @@ generic and stable layer to manage domains on a node.</p>
 <p>So libvir should be a building block for higher level management tools or
 for applications focusing on virtualization on a single node (the only
 exception being domain migration between node capabilities which may need to
-be added at the libvir level)</p>
-
-<p> </p>
-
-<p></p>
+be added at the libvir level). Where possible libvir should be extendable to
+be able to provide the same API for remote nodes, however this is not the
+case at the moment, the code currently handle only local node access.</p>
 
 <h2><a name="architecture">libvir architecture</a></h2>
 
-<p>In a Xen environment, programs using libvir have to execute in "Domain 0",
-which is the primary Linux OS loaded on the machine. That OS kernel provides
-most if not all of the actual drivers used by the set of domains. It also
-runs the Xen Store, a database of informations shared by the hypervisor, the
-kernels, the drivers and the xen daemon. Xend, the xen daemon, also runs in
-Domain0 and supervise the control and execution of the sets of domains. The
-hypervisor, drivers, kernels and daemons communicate though a shared system
-bus implemented in the hypervisor. The figure below tries to provide a view
-of this environment:</p>
+<p>When running in a Xen environment, programs using libvir have to execute
+in "Domain 0", which is the primary Linux OS loaded on the machine. That OS
+kernel provides most if not all of the actual drivers used by the set of
+domains. It also runs the Xen Store, a database of informations shared by the
+hypervisor, the kernels, the drivers and the xen daemon. Xend. The xen daemon
+supervise the control and execution of the sets of domains. The hypervisor,
+drivers, kernels and daemons communicate though a shared system bus
+implemented in the hypervisor. The figure below tries to provide a view of
+this environment:</p>
 <img src="architecture.gif" alt="The Xen architecture">
 
 <p>The library can be initialized in 2 ways depending on the level of
@@ -109,8 +109,14 @@ the Xen infrastructure:</p>
   <li>use Xen Hypervisor calls</li>
 </ul>
 
-<p> If it runs without root access virConnectOpenReadOnly() should be used,
-it will try to open the read-only socket
+<p>The library will usually interract with the Xen daemon for any operation
+changing the state of the system, but for performance and accuracy reasons
+may talk directly to the hypervisor when gathering state informations at
+least when possible (i.e. when the running program using libvir has root
+priviledge access). </p>
+
+<p> If it runs without root access virConnectOpenReadOnly() should be used to
+connect to initialize the library. It will try to open the read-only socket
 <code>/var/run/xenstored/socket_ro</code> to connect to the Xen Store and
 also try to use the RPC to the Xen daemon. In this case use of hypervisor
 calls and write to the Xen Store will not be possible, restraining the amount
@@ -188,11 +194,13 @@ available except commiting to the base.</p>
     <p><code>make rpm</code></p>
   </li>
   <li><em>Failure to use the API for non-root users</em>
-    <p>Large parts of the API are only accessible as root, however the read
-    only access to the xenstore data doesnot have to be forbidden to user, at
-    least for monitoring purposes. If "virsh info" fails to run as an user,
-    change the mode of the xenstore read-only socket with:</p>
+    <p>Large parts of the API may only be accessible with root priviledges,
+    however the read only access to the xenstore data doesnot have to be
+    forbidden to user, at least for monitoring purposes. If "virsh info"
+    fails to run as an user, change the mode of the xenstore read-only socket
+    with:</p>
     <p><code>chmod 666 /var/run/xenstored/socket_ro</code></p>
+    <p>and also make sure that the Xen Daemon is running correctly</p>
   </li>
 </ol>
 
@@ -244,7 +252,7 @@ attachments are really appreciated and will be discussed on the mailing list.
 If possible generate the patches by using cvs diff -u in a CVS checkout.</p>
 
 <p>We expect to use <a href="https://bugzilla.redhat.com/">Red Hat
-Bugzilla</a> to track bugs for libvir, though there isn't yet a libvir
-software module.</p>
+Bugzilla</a> to track bugs for libvir, though there isn't a libvir software
+module defined yet, in the meantime use the mailing-list, thanks !.</p>
 </body>
 </html>
diff --git a/docs/node.fig b/docs/node.fig
new file mode 100644
index 000000000..4618a658d
--- /dev/null
+++ b/docs/node.fig
@@ -0,0 +1,30 @@
+#FIG 3.2
+Landscape
+Center
+Inches
+Letter  
+100.00
+Single
+-2
+1200 2
+6 1275 1800 2550 2250
+2 4 0 1 0 7 50 -1 -1 0.000 0 0 7 0 0 5
+	 2550 2250 2550 1800 1275 1800 1275 2250 2550 2250
+4 0 0 50 -1 0 20 0.0000 4 195 930 1500 2100 Domain\001
+-6
+6 1275 2325 2550 2775
+2 4 0 1 0 7 50 -1 -1 0.000 0 0 7 0 0 5
+	 2550 2775 2550 2325 1275 2325 1275 2775 2550 2775
+4 0 0 50 -1 0 20 0.0000 4 195 930 1500 2625 Domain\001
+-6
+6 1275 2850 2550 3300
+2 4 0 1 0 7 50 -1 -1 0.000 0 0 7 0 0 5
+	 2550 3300 2550 2850 1275 2850 1275 3300 2550 3300
+4 0 0 50 -1 0 20 0.0000 4 195 930 1500 3150 Domain\001
+-6
+2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
+	 975 1500 3375 1500 3375 4125 975 4125 975 1500
+2 4 0 1 0 7 50 -1 -1 0.000 0 0 7 0 0 5
+	 3225 3975 3225 3450 1125 3450 1125 3975 3225 3975
+4 0 0 50 -1 0 20 0.0000 4 255 1260 1500 3825 Hypervisor\001
+4 0 0 50 -1 0 20 0.0000 4 195 600 2700 2850 Node\001
diff --git a/docs/node.gif b/docs/node.gif
new file mode 100644
index 000000000..16a5fe9a3
--- /dev/null
+++ b/docs/node.gif
author	Daniel Veillard <veillard@redhat.com>	2006-01-23 13:24:07 +0000
committer	Daniel Veillard <veillard@redhat.com>	2006-01-23 13:24:07 +0000
commit	d0a71d23da4010677c57a6a1467bfa4d711f4ca6 (patch)
tree	734a58efbf14330fcf4ed5ce83a24dbb39a16e24
parent	Updated and fixed a broken link, Daniel (diff)
download	libvirt-d0a71d23da4010677c57a6a1467bfa4d711f4ca6.tar.gz libvirt-d0a71d23da4010677c57a6a1467bfa4d711f4ca6.tar.bz2 libvirt-d0a71d23da4010677c57a6a1467bfa4d711f4ca6.zip