From d0a71d23da4010677c57a6a1467bfa4d711f4ca6 Mon Sep 17 00:00:00 2001 From: Daniel Veillard Date: Mon, 23 Jan 2006 13:24:07 +0000 Subject: [PATCH] * doc/*: augment and try to complete the doc in its current state Daniel --- ChangeLog | 4 +++ docs/FAQ.html | 10 +++++--- docs/architecture.html | 26 +++++++++++-------- docs/bugs.html | 4 +-- docs/intro.html | 9 ++++--- docs/libvir.html | 56 +++++++++++++++++++++++------------------ docs/node.fig | 30 ++++++++++++++++++++++ docs/node.gif | Bin 0 -> 1397 bytes 8 files changed, 94 insertions(+), 45 deletions(-) create mode 100644 docs/node.fig create mode 100644 docs/node.gif 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 + + * doc/*: augment and try to complete the doc in its current state + Sun Jan 22 17:26:20 CET 2006 Daniel Veillard * 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 @@

make rpm

  • Failure to use the API for non-root users -

    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:

    +

    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:

    chmod 666 /var/run/xenstored/socket_ro

    +

    and also make sure that the Xen Daemon is running correctly

    • Compilation

    1. What is the process to compile libvir ?

      As most UNIX libraries libvir follows the "standard":

      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 @@ -libvir architecture

      libvir architecture

      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:

      The Xen architecture

      The library can be initialized in 2 ways depending on the level of +libvir architecture

      libvir architecture

      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:

      The Xen architecture

      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:

      • a connection to the Xen Daemon though an HTTP RPC layer
      • a read/write connection to the Xen Store
      • use Xen Hypervisor calls
        • -

      If it runs without root access virConnectOpenReadOnly() should be used, -it will try to open the read-only socket +

      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).

      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 /var/run/xenstored/socket_ro 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. Please subscribe to this list before posting by visiting the

      We expect to use Red Hat -Bugzilla to track bugs for libvir, though there isn't yet a libvir -software module.

      main menu

      related links

      +Bugzilla to track bugs for libvir, though there isn't a libvir software +module defined yet, in the meantime use the mailing-list, thanks !.

      main menu

      related links

      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 @@ Introduction

      Introduction

      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.

      To avoid ambiguity about the terms used here here are the definitions for +possible interfaces for interacting with the virtualization features.

      To avoid ambiguity about the terms used here here are the definitions for soem of the specific terms used in libvir documentation:

      • a node is a single physical machine
      • an hypervisor is a layer of software allowing to virtualize a node in a set of virtual machines with possibly different configurations than the node itself
      • a domain is an instance of an operating system running on a virtualized machine
        • -

      Now we can define the goal of libvir: to provide the lowest possible +

      Hypervisor and domains running on a node

      Now we can define the goal of libvir: to provide the lowest possible generic and stable layer to manage domains on a node.

      This implies the following:

      • 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.

        This implies the fol

      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)

      main menu

      related links

      +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.

      main menu

      related links

      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 ChangeLog to gauge progresses.

      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.

      +possible interfaces for interacting with the virtualization features.

      To avoid ambiguity about the terms used here here are the definitions for soem of the specific terms used in libvir documentation:

      @@ -58,6 +57,9 @@ soem of the specific terms used in libvir documentation:

      on a virtualized machine
      2. +

      +

      Now we can define the goal of libvir: to provide the lowest possible generic and stable layer to manage domains on a node.

      @@ -80,23 +82,21 @@ generic and stable layer to manage domains on a node.

      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)

      - -

      - -

      +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.

      libvir architecture

      -

      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:

      +

      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:

      The Xen architecture

      The library can be initialized in 2 ways depending on the level of @@ -109,8 +109,14 @@ the Xen infrastructure:

    2. use Xen Hypervisor calls
      3. -

      If it runs without root access virConnectOpenReadOnly() should be used, -it will try to open the read-only socket +

      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).

      + +

      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 /var/run/xenstored/socket_ro 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.

      make rpm

    3. Failure to use the API for non-root users -

      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:

      +

      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:

      chmod 666 /var/run/xenstored/socket_ro

      +

      and also make sure that the Xen Daemon is running correctly

    @@ -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.

    We expect to use Red Hat -Bugzilla to track bugs for libvir, though there isn't yet a libvir -software module.

    +Bugzilla to track bugs for libvir, though there isn't a libvir software +module defined yet, in the meantime use the mailing-list, thanks !.

    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 0000000000000000000000000000000000000000..16a5fe9a3157944769354918aff7f28d3faaf073 GIT binary patch literal 1397 zcmV-*1&aDdNk%w1VWI%B0Du4h0002)>*gW(1OWg50RSuj0001@0I>i70{)DTsmtvT zqnxxhfV1Ab`wxcVNS5a51%So2?hD7zy2|#A=P<4J{{Q0vhr}X9XiO@V$ffhCYeJ{g zmb8k^Ib8&Vj^E(&`ipMQSMd7&Oyw7N2Pjy$M|g*#xTvVc zw}4@oP*e6eDG6z2c|eJIDYj|Q>4`9!6^ck&3Yt1$s@i%Q8}Z8UaaL=~n!B|(nvoRg zy34`~X$o9PY+Dupu*-^4{?`Ys&^ zn7?w;f`#*A(W8>K4l#$7+!wBy!Uoi8#q3J7#nh6e_BLx+uV3TJg+&(#sO(~xLpy76T~5_ZQCO`YL24UKDc#0@l~WpieUpYc``m=FesT{n3)rCFgR zjHr>H{zUi?W0l=yUWANdGw7oX{udL1iq_d>Z6nR+lb?8Yx+IdRh>6{)8-iwNtBY`! z2x+OAN$L}|j>x5_Joc!oh=}g^T1&mMD4vTP;4=PDusV_0WDtBRdsT+b$^tEZNqx#n zwY*;YshHiU*VIBQnOf;;7;;Nqf8UCFU_OxMSgcO>(7EP;ZGwoSm*>h`AfTYGXWqRk zm5alG63y$ciJB^`V!jY5dGJV#Dm>x84HG=azQAFoCx8@toD#sd4g)cfFa3*hiYnua z@oX9s`66a9Iz{tBGaifN$jg@8*RDVg+hDvyY8w*J@CuEW&p!|CD{MKs^X) zQt!M&ba7}cUAeA)EdrV?TMF0JWV>wk*}jdfwoz%f?Si9lPyP1XxY}KZ+;|iA7TA9O z?e|qu?j2f>RT5rTkVPY2xGucZeReKrK>kj)>J zI8K|RZkp$(XARY{V_b@aEJME?ycl&jW*FJjOxN{Et>%H4am6|!nXr!F^(8)a4 zi(g`U*1q$kor0S_g*`(dmZ#y`uJaCi%q6MBy@cm`@10EjH8=jd!e5Ub`ZT-CVV?=3 zEPj%~TQR&o+3#}0+aLHS)<4z#PfPSeh{qOnfdV2gC=-;PwG?PP>rGHx2&&J(0O2ov zZ0Lh&iQlE>w?R#5PkjT!(|=B)n&OcUfU!eWD`fYLaNR{4sPY!Mkmj8QCXR$pGogio z(LkdGF@s<6iv