
  6. Software Architecture
  ========================

   6.1. Basic Extendibility Design
   ===============================

    The architecture and design of teh UnifiedSessionsManager is
    targeted to be capable for integration of any third party
    tool. Therefore a plugin systems with dynamic and fully automatic
    load and operational state evaluation is designed and
    implemented. 

    One main driving argument was the required amount of space for
    the bash modules, including their embedded comments, which
    originally exhausted the mainly static defined bash memory. The
    dynamic load of plugins on demand reduces the memory requirement
    dramatically.

    The usage of the bash has some limitations of course, but it's
    simplicity and widely applicability by the targeted audience made
    the decision for it. So almost anybody should be able to custom
    and extend the UnifiedSessionsManager as required. It is proven to
    implement a new VM within a few days, completely and with
    tests. This is possible because of the presence of the limited
    number and almost completely implemented patterns to be
    combined. The support environment of the framework accomplishes
    the task.

    The unification requires the restriction of the interface to
    essential actions only. Thus specific features are not supported
    by ctys tools, but could be executed within the HOSTs packages as
    a native call. Some specific options could be supported by their
    own suboptions, which are evaluated within the called plugin only.
    So even specific and prorietary features could be used with full
    advance of stacked VMs addressing, connection encryption, and GUI
    management, when these are just executed within a session.


    The usage of a scan mechanism which only detects present plugins
    and sets their operational state appropriately, has the advantage
    of simple configuration opportunity for any user. A remove or copy
    of a plugin subdirectory is anything to be done.

    It should be mentioned here, that the compatibilty of remote calls
    between client and server component of ctys will be checked by the
    hard coded version string of the "ctys" call. The plugins are not
    checked, but just trusted to be suitable to the ctys version. This
    is for complete installation or updates true, but could be
    undermined when installing or removing components only. Particularly
    the standard HOSTs component VNC could have serious impact on the
    VMs XEN and QEMU, when used as console.


   6.2. Development Environment
   ============================

    As a draft pre-remark it should be mentioned, that the context
    help supports the listing of functions and their headers. Thus
    supports an embedded online help system.



    Additional documentation will follow.

    ffs.

 
    6.2.1 Some basics on "bash"
    ===========================

     The benefit of the bash is obviously it's widely and easy
     applicability due to the available knowledge of the targeted
     users.

     The usability of ctys within shell scripts, offering a
     namebinding for login configuration of complex user interfaces
     and enhaced desktops is another argument.

     But there are some drawbacks, which do not eas life very
     much. The main challange is the missing of structured data
     structures and associative arrays. Even though this could be
     partly emulated, the decision to a remarkable number of global
     variables was made. Arrays are used for task management only,
     which would be utilised by incremental access only.

     Another challange is given due to the limited namespace
     capabilities and inheritance behaviour within nested function
     definitions. The definition of nested calls for loops has to be
     checked frequently for overlapping or better local-only
     definition of index variables.

     But anyhow, the lack of an implicit namespace was the feature
     what made the design of a function based dynamic-source-ing
     environment possible at all. So, really could be said "it's a
     feature, not a bug".
    

     6.2.1.1. "source-ing"
     =====================

      The most important feature used within the UnifiedSessionsManager 
      is the source of components. This is developed within ctys tools
      to be used as similar approach to shared libraries of the
      compiler environment.

      Therefore almost the whole scripts of the ctys tools are just
      plugged together by using a load mechanism based on "hook"
      convention.

      
 
     6.2.1.2. Using bash-modules as self-configuring dynamic objects
     ===============================================================

      ffs.

 
    6.2.2. Component Framework
    ==========================

     ffs.

 

     6.2.2.1. Hook - The Extendibility Interface
     ===========================================

       The interface to load a component dynamically is based on some
       minor but important naming convention and a basic set of
       interfaces. This includes a level based set of initialization
       calls and propagation of these.


       ffs.
 

      6.2.2.1.1. Static Load of Modules
      =================================


       ffs.
 


      6.2.2.1.2. Dynamic OnDemand Load of Modules
      ===========================================

       ffs.
 

      6.2.2.1.3. Operational States
      =============================

       The available plugins are utilized and managed by usage of
       their integral state variables. Particularly the operational
       state defines the accessibility of the features provided by
       individual plugins. 

       The usage of sets of plugins could be triggered by explicitly
       called CLI options "-t" for specific targets, or by the
       pre-load option "-T". In case of generic actions like LIST,
       ENUMERATE, SHOW, and INFO, ctys will parse all loaded and
       available plugins for representation of statistical or bulk
       results. This will lead frequently to errors, when some
       prerequisites of individual plugins are not met for any
       reason. 

       The basic issue when implementing a plugin and using it at run
       time is the availability and operability of the prerequisite
       third-party software components. This could involve the
       detection of the appropriate software call interface as well, as
       the validation of it's successful intialization. This becomes
       cumbersome quickly, when managing it manually in a higly
       volatile test and development environment, where multiple
       kernels and multiple hypervisors, additionally multiple OSs are
       used. 

       The continous installation and deinstallation of appropriate
       plugins seems not to be aviable approach.

       Therefore the operational state of each plugin is introduced. 
       Any available plugin could and will be installed now and
       independently for each call it will be detected whether the
       operational prerequisites are met and teh state will be set
       appropriately.

       The state variable for a plugin will be dynamically determined
       based on the array of runtime detected and loaded
       plugins. Therefore in the entry-hook of each plugin a variable
       with the following naming conventions has to be defined:

         <plugin>_STATE

      where <plugin> is the name of current plugin in UPPERCASE, same
      as the containing directory name. E.g.

         XEN_STATE or VNC_STATE

      The variable can be assigned one of the following states
      similar to the ITU-T definition for telecoms:

          AVAILABLE(0)
            This is the implicit state of any found module, which is
            not handled actually. Or better to say any present plugin
            is registered in a list of available plugins, which
            represents it's presence. The default state is set to
            DISABLED, because this is the first non-obvious "level"
            of state requiring management information exceeding it's
            pure presence recognition.

          DISABLED(1)
            This is the default state, which is stored in the runtime
            modules.

          ENABLED(2)
            This state is set, when during initialization of the
            module any prerequisite is met. Else the state remais
            DISABLED(1).

          IDLE(3)
            This state will not be utilized, due to the fact that all
            tools are One-Call Utilities, not daemons. So any
            ENABLED(2) plugin will be utilized to BUSY(4) or just
            remains as pre-checked, which is ENABLED(2).

            This behaviour might change (but does not seem so).

          BUSY(4)
            This state will be managed just for statistical reasons
            when for ctys teh "-v" option is choosen. This option
            displays after completion of execution the last state of
            ctys just before termination. Therefore it shows the
            actual state of the completed call, thus marks the
            actually used modules as BUSY.

            REMARK: This feature is not yet finally implemented.


      6.2.2.1.4. IGNORE-Flag - A stateless State
      ==========================================

       There is a special flag available, which could just be named
       indirectly a state, if so it would be similiar to DISABLED. But
       this does interfere and not match with the used DISABLED state,
       which is the result of an at least partly failed initialization
       of a present and at least basic executable plugin.

       In difference the IGNORE flag - which could  be constrained by
       simple bash-conditionals - influences the loader and prevents
       the load of the plugin at all. This is due to configuration,
       for whatever reason.

       So the IGNORED state is actually the "unavailable" state,
       avoiding execution failure during initialization on an
       unsupported platform e.g.

       Commonly in the configuration file "ctys.conf" for each plugin
       a flag with the syntax

         export <plugin-type>_IGNORE=1

       could be set and will be recognized by the loader bootstrapping
       hooks. The <plugin-type> is in accordance to common ctys
       convention the literal name of the plugins own root directory.

       The implementation as a bash variable which could be initialized 
       by evaluating arbitrary contraints as simple shell scripts,
       offers particularly a smart means of machine dependent assembly
       of plugins. This works also perfectly when the identical file
       is commonly mounted by all of the execution targets as VMs and
       PMs. It is for example a common managed task seamless
       distinguishing between client and server locality for a Xen
       session and therefore cope the different runtime environments
       with it's completetley different requirements. This is
       particularly the case for the CREATE and CANCEL action to be
       performed within the Dom0. 

       Due to the power behind this feature some examples are given:

          #When set, the bootstrap-loader ignores the given
          # <plugin-type>.
          #This should be in case of dependencies such as of XEN from
          #VNC utilized carefully. But on machines with OpenBSD
          #e.g. the plugins VMW and XEN could be set to ignore safely.
          #
          #export PM_IGNORE=1
          #export CLI_IGNORE=1
          #export X11_IGNORE=1
          #export VNC_IGNORE=1
          #export XEN_IGNORE=1
          #export VMW_IGNORE=1
          #export QEMU_IGNORE=1
          #export OVZ_IGNORE=1
          #
          #
          # This could be configured conditionally for each of the
          # following variables, and any other valid shell variable.
          # This is particularly helpful in case of NFS mounted home
          # directories sharing the identical user-configuration for
          # multiple machines within a cluster:
          #
          #   MYHOST   : actual host
          #   MYOS     : actual OS
          #   MYOSREL  : release of actual OS
          #   MYDIST   : actual distribution
          #   MYREL    : release of actual distribution
          #
          #
          # Some examples for ignoring of XEN-plugin on specific sets
          # of nodes:
          #
          #   ->host01 only
          #     [ "$MYHOST" == "host01" ]&&export XEN_IGNORE=1;
          #
          #   ->Any node NOT on "clust0*"
          #     [ "${MYHOST#clust0*}" == "${MYHOST}" ]\
          #           &&export XEN_IGNORE=1;
          #
          #   ->Any node IS on "clust0*"
          #     [ "${MYHOST#clust0*}" != "${MYHOST}" ]\
          #           &&export XEN_IGNORE=1;
          #
          #   ->Any node in domain "exe1"
          #     [ "${MYHOST##*.exe1}" == "${MYHOST}" ]\
          #           &&export XEN_IGNORE=1;
          #
          #   ->Any node NOT running OpenBSD
          #     [ "${MYOS}" != "OpenBSD" ]\
          #           &&export XEN_IGNORE=1;
          #
          #   ->Any node IS running Linux
          #     [ "${MYOS}" == "Linux" ]\
          #           &&export XEN_IGNORE=1;
          #
          #   ->Any node IS running CentOS
          #     [ "${MYDIST}" == "CentOS" ]\
          #           &&export XEN_IGNORE=1;
          #
          #   ->Any node which IS NOT final execution target
          #     REMARK: for now patched: [ -z "$CTRL_EXECLOCAL" ]\
          #     [ -z "`echo $*|sed ....`" ]\
          #           &&export XEN_IGNORE=1;
          #
          #   ->....
          #
          #
          # Almost any combination and any additional constraint could be
          # added by means of bash.
          #
          # When using internal state variables the user is responsible for
          # any resulting side effect.
          #
          
          
          ##################
          #Configuration of supported contexts for standard plugins.
          #
          
          #PM supports currently Linux and OpenBSD
          [ "${MYOS}" != "OpenBSD" -a "${MYOS}" != "Linux" ]\
                       &&export PM_IGNORE=1;
          
          #XEN is supported on Linux only as server, else as client only.
          #VNC check will be done by plugin
          #Check for "-e", because CTRL_EXECLOCAL is not yet initialized.
          [ "${MYOS}" != "Linux" -a -n "`echo " $* "|sed -n '/ -e /p'`" ]\
                       &&export XEN_IGNORE=1;
          
          #VMW is supported on Linux only, else as client only.
          #Native local client and VNC access for WS6 will be checked
          #by plugin.

          [ "${MYOS}" != "Linux" ]\
                       &&export VMW_IGNORE=1;
          
          ###########################################################
          #                                                         #
          #ATTENTION:                                               #
          #  The plugins CLI+X11+VNC could be called MANDATORY for  #
          #  others, so their "IGNORE-ance" might force unforseen   #
          #  side-effects, think twice!!!                           #
          #                                                         #
          #  Same is true for PM when you require WoL and           #
          #  controlled PM shutdown, what might be obvious!         #
          #                                                         #
          ###########################################################


      6.2.2.1.5. Multi-OS Boot Environments
      =====================================

       The usage of multi boot environments opens a bulk of issues to
       it's management. One is the installation of appropriate
       software components and not using parts, which might
       fail. Another might be the ongoing synchronization of updates
       for the system and the available plugins.

       Therefore the decision for ctys was the introduction of the
       previously described state variable. The state of each plugin
       will be determined dynamically, so all available plugins could
       be installed at once. Even though e.g. the Xen plugin might not
       neccesarily usable on a configured kernel for VMware. 

       This feature becomes very handy, when e.g. in case of Linux
       several kernels are installed for the usage of multiple
       hypervisors. E.g. VMware for building OpenBSD and Xen as
       paravirtualized on non-HW-VM for some number crunching on a
       partitioned Linux machine with some Linux-VMs.

 
     6.2.2.2. Interface-Specification - Online-Help     
     ==============================================

       ffs.

 

      6.2.2.2.1. Interface-Specification-Rules
      ========================================

       ffs.


 
      6.2.2.2.2. Generic Context-Help for Shell-Scripts  
      =================================================

       ffs.

 

   6.3. All about bash-Plugins and bash-Libraries
   ==============================================

    ffs.
 

    6.3.1. The Differences
    ======================

     The main differences between libraries and plugins are the static
     load behaviour and fixed hardcoded load of libraries only. 
     Therefore no init procedure despite the automatic processing of
     calls is performed. This is equivalent to the init-level 0 of
     plugins. 

     Another difference is the more conventional reason than
     technically, that libraries are designed as generic components to
     be used in any project. Whereas plugins are specifically designed
     in order tto support a unique project primarily.

     Plugins are loaded static and/or dynamically. They could be just
     default initialized when required.

 
    6.3.2. Libraries
    ================

     ffs.

 

    6.3.3. Plugins 
    ==============


     6.3.3.1. Category CORE
     ======================

      This category offers basic features, which are generic and
      applicable to multiple specific plugins. Thus CORE plugins are
      very close to libraries, but are project specific and loaded
      atomatically. Sub components could be loaded on demand by
      generic scanned top-level entries.

      E.g. the CLI CORE component (which has nothing to do with the
      CLI plugin), handles the ctys tools specific options scan for a
      number of tools.

      The GROUPS component handles the resolution of group names into
      host entities.

 
     6.3.3.2. Category HOSTs
     =======================

      These category contains plugins to be just executed natively
      within a running OS. Therefore most of them serve as console
      clients for VMs.

      Currently the plugins CLI, X11, and VNC are supported.

 
     6.3.3.3. Category VMs
     =====================

      These are the bread and butter applications for stacked
      VMs. Each of them support at least one specific VM. Some support
      muultiple variants, when these just do require minor variations
      only. When more specifics are required it is recommended to
      support another one seperately. This helps to reduce the
      required runtime resources as well as the reduces the
      maintaining efforts, even though some parts might be redundant.

      The standard support is available for XEN and QEMU, and for the
      initially implemented VMW, which includes Server, Player, and
      Workstation.

 
     6.3.3.4. Category PMs
     =====================

      The PMs plugins support the required functionality for handling
      of physical machines. This varies somewhat from VMs in various
      aspects. 

      The main difference for conceptual ressons might be within the
      CREATE method, what has to be executed for the initial
      "switch-on" of the PM on another machine. This breaks he basic
      command call structure as the only exception, where the action
      argumens "-a CREATE=.." contains the subparameter referring not
      to a contained subinstance, but even cross-over to another
      machine without any encryption. Which is required for the
      initial Wake-On-LAN packet.

      OK, this could not realy be seen as a security flaw and thus
      designed this way.

      Another point is the automatic openning of a console
      session. This has to be performed in an exceptional structure
      too. This is due to the same reason as the initial WoL
      packet. The session could be opened from another machine when
      the execution-target to be waked up is SSH-accessible. Therefore
      a polling mechanism based on timeouts and trial-counters is
      implemented.

      The stacking and tehrefore the state-propagation works similar
      to the VMs.

