   9.3.3. XEN - Xen
   ================

   9.3.3.1. Description
    ------------------

    This plugin adds support for XEN sessions. The current supported
    client type of this package is CLI, X11 and VNC.

    Any not listed standard option of ctys applies as defined. In
    cases of divergent behaviour for similiar options, and options
    with specific suboptions are are listed in this section.

    There are some specifics to be recognized and/or applied specific
    to Xen. This is primarily due to it's nature ot the hypervisor
    interface, where DomU-s are children of the one and only Dom0,
    which is not "visible" to "ps" as a normal process, but to the
    specific tools "xm" and "virsh". Where virsh is part of "libvirt"
    but prerequired for ctys.

    One main challange in combination of access to restricted system
    resources is the requirement of root permissions for some calls to
    manage DomU-s. This requires for user-level on demand CREATE and
    CANCEL the configuration of "sudo" or "ksu".

    Some drawbacks for the common applied tricks of ctys, using the
    CLI and "ps" as an dynamic storage and exchange interface for
    runtime information are not working in the altered runtime
    environment. Even though paticularly the "virsh dumpxml" call
    offers a variety of information. One missing data, that really
    "hurts" is the missing information of the used configuration file
    for the list-ed or dumpxml-ed domain. The "source file" is
    available - which is the virtual boot-device. But this does not
    allow an back annotation to related configuration file - this
    could be just safely defined by additional naming convention, what
    is done within ctys fo simplicity.

    Another specifics is a legacy of ctys, which is the definition of
    ID as a static unique identifier for a VM and PM entity, which
    does not change, when the entity changes it's state to
    offline. Resulting of this, the ID is for VMW, PM, and XEN the
    fully qualified pathname of the configuration file, which is still
    not neccessarily unique, due to NFS mounted shares on multiple PMs
    and/or VMs. This is still not unique, when combining the PMs
    hostname and the pathname of the configuration file, because the
    contained IDs, e.g. TCP/IP address, MAC address, and UUID are now
    available within multiple entities, and thus will be listed as
    though when using administrative management utilities. Anyhow, it
    should be at least guaranteed by the user, that the entities are
    unique within the scope a single node. The toolset is prepared to
    handle various constellations, but it makes the selection by the
    user somewhat easier.

    For this the following shortcuts and conventions apply.

     - The Domain-ID as provided by Xen is for now ignored, the
       Domain-Name is required to be unique, so the LABEL, which is
       the Domain-Name, is sufficient as selection criteria. This is
       anyhow a static constant identifier, which is not true for the
       Xen-Domain-ID.

       The Domain-ID within ctys - "IDS" for ctys-vhost - is a
       holomorphic identifier, which is for machines - VMs and PMs -
       a configuration filepathname, for types of the category HOSTs a
       dynamic systme generated ID such as a PID, DISPLAY, or port. 

       Therefore the Domain-ID for Xen within ctys is the filepathname
       of the configuraitopn file. This is particularly important due
       to stored information within the configuration file itself, or
       within the same directory. Due to the only available
       filepathname for the boot-image of the DomU instance by
       "virsh", the fixed - maybe already widely applied - convention
       is defined, that the configuration file has to be coallocated
       within the same directory as the virtual boot device for the
       DomU and to be named the same as the name of the containing
       directory. This has not neccessarily to be the LABEL which is
       the Domain-Name of the DomU, but could be. SO boot devices,
       which are physical, not virtual files, are not supported for
       now.

     - NO SPACES within ANY entry are supported.

     - When multiple LAN interfaces are configured, the first matching is
       provided only.

     - Due to the variety of consoles - CLIENTS - which could be
       attached and are not simply correlated, the LIST action only
       displays the SERVER components, which are Dom0/DomU, the
       clients has to be listed by an extra call to CLI, X11, and/or
       VNC.

     - The execution of the creation by "xm" and some "virsh" access
       permissions has to be activated and reuqired to be with root
       permissions. Therefore the configuration file "/etc/sudoers"
       and/or "/root/.k5users" has to be configured. The access
       privileges by "sudo" and "ksu -e" will be checked and set
       appropriately. The variable "XENCALL" and "VIRSHCALL" could be
       preconfigured.

     - The execution of XEN requires in any case the VNC module.

     - The version supported by XEN is the 3.x version. The tested and
       verified version is Xen-3.0.3 of the CentOS-5.0 distribution,
       even though any 3.x version might work. The version evaluation
       is done by usage of rpm or xm or virsh or xmtrace. The
       installation paths are evaluated by which call and should be
       prepared for execution by PATH.

     - Due to the warning-output of some tools, this is fetched as
       ctys WARNING, which could be fully activated by "-w" option and
       fully suppressed by "-W" option.


     - The XEN plugin is stack-aware, though prepared to propagate
       CREATE and CANCEL actions, same for LIST. 

     - XEN_CONSOLE_DOMU_INIT_WAIT
       This variable contains the sleep value after "xm create ..."
       and before calling a "gnome-terminal" or "xterm". Therefore in
       case of a machine which has difficulties due it's performance
       the value couls be adjusted. The current value of 8seconds
       seems to be safe for initialization of created DomU.

   
   9.3.3.1. Options
    ---------------

    -a <action>[=<action-suboptions>]

        CANCEL

            full <vm-address> range is supported.


        CREATE

           All standard parameteres not listed here could be applied.


           Additional keywords, some will be brought to the standard
           pool:

             NOCACHE
             NOPOLL
             CONSOLE:(CLI|XTERM|GTERM|VNC)


           Dependent on the choosen parameter set some specific
           CONSOLE types can - whereas some cannot - be applied. The
           appropriate settings for the choosen console has to be
           prepared within the related config file of course.


                                  |  CLI  | XTERM |  VNC
                                  |       | GTERM |
            ----------------------+-------+-------+--------
            ConnectionForwarding  |   -   |   -   |   X
            DisplayForwarding     |   X   |   X   |   X
                                  |       |       |
            CONNECT               |   X   |   X   |   X
            RECONNECT             |   X   |   X   |   X
            REUSE                 |   X   |   X   |   X
            RESUME                |   X   |   X   |   X
                                  |       |       |
            "-b 0" - foreground   |   X   |   A   |   A
            "-b 1" - background   |   -   |   X   |   X


            X)   Supported.

            A.)  Supported, but will block the call-terminal for the
                 whole session, so might not be used from a
                 single-console environment.



           Types of CONSOLE to be applied depends on the "-b"
           parameter for background execution too.

           The following behaviour applies:

             "-b 0" - synchronous foreground execution

               In this mode the current execution thread is performed
               synchronous in the foreground, this means particularly
               a CLI based console cannot be detached, when multiple
               tasks are in the queue in order to begin the next. Thus
               it would result to blocking the remaining sessions
               until the current has been finished by the caller.

               This parameter is allowed to be applied, but the
               caller has to be aware of the drawbacks, when choosing
               multiple execution targets.


             "-b 1" - aynchronous background execution

               In this mode the DomU will be started by differnt means
               for XTERM and VNC only.

                CONSOLE:CLI
                  Will be generally rejected, because multiple
                  execution targets cannot be handeled by a single
                  physical console, and one target could be perfectly
                  handeled by "-b 0".

                CONSOLE:GTERM
                  The "gnome-terminal" which is currently simply
                  mapped to XTERM.

                CONSOLE:XTERM
                  Starts first an xterminal by using the X11 module
                  and initiates the startup of the DomU within the
                  Xterminal session as a native and synchronous call
                  to "xm -c ...". So it is basically the asynchronous
                  variant of a CLI call.

                CONSOLE:VNC
                  This case is somewhat different to the previous, in
                  the way that two independent calls for the DomU
                  itself are required. 

                   1. The DomU has to be started, which is performed by
                      calling "xm <conf>".

                   2. The VNCviewer has to be attached to the offered
                      port by the DomU.

                      Therefore a timeout will be applied, which could
                      be controlled by the environment variable
                      "XEN_CONSOLE_DOMU_INIT_WAIT", which is used for a
                      sleep-call.

                      So, due to buffer handling some console messages
                      could probably be lost.

                  The client call is in internal call to VNC pluging,
                  which is basically completely independent and could
                  be applied seperately.



             - <callopts> 

               When <callopts> are given, these will be passed
               through to the

                  "xm [-c] <conf-path> <callopts> "

               call.  
               For additional information refer to Xen manual.


             - <xopts> 

               XToolkit options, when are given, these will be passed
               through to the client call when applied with XTERM or
               VNC. It has to be recognized, that some options require
               to have DH "--" whereas some require SH "-". So it is
               recommended to use a seperate client call, when
               resources have to be set. Or use rc-files with
               X11-resources as supported by the application.

                  "vmware <callopts> <vmx-path> -- <xopts>"

               call. The required "--" double hyphen will be inserted
               as required.

               Be aware, that some of these such as "-geometry" and
               "-name" are already implicitly utilized by other
               options, thus use this if, than CAREFULLY.



    -g <geometry>|<geometryExtended>

       The geometry has no effect on the server started within the
       DomU. Just the client will be set:

         CLI
           Not applicable.

         XTERM|GTERM
           The size Xsiz and Ysiz provide the UNIT of CHARACTERS only.

         VNC
           As expected.


    -r <resolution>

       Not supported.
 


    -L (LocalOnly|LO)
       | (ConnectionForwarding|CF)
       | (DisplayForwarding|DF)
       | (ServerOnly|SO)


        Currently the following selections are supported:


                                |LO |CF |DF |SO
           ---------------------+---+---+---+--
           CLI                  |yes|no |yes| 1.)
           XTERM                |yes|no |yes| 1.)
           VNC                  |yes|yes|yes| 1.)


           1) The console has to be attached by an seperate call.


