
  8. Common Definitions for Options
  =================================

   The most of preset default values could be changed by setting and
   exporting environment variables, e.g. PR_OPTS for "pr" options,
   or several require timeouts. These are documented inline within the
   sources.

   Specific install and bootstrap information is provided in the
   README and INSTALL documents.


   8.1 Common Syntax Elements and Behaviour
   ========================================

   Options are scanned and set by usage of getopts of bash function,
   therefore they will be evaluated from left to right. This has to be
   considered when options depend on each other. This is e.g. the
   case, when debugging should be set for the evaluation of options,
   therefore it should be set leftmost.

   Some of the options are prefetched for bootstrap phase until the
   CLI processing parts are active, this is e.g. the case for options
   related to dynamic and on-demand load of bash-libararies and
   plugins by "sourcing" them for initial bootstrap. Refer to the
   sources of ctys for extended inline documentation.

   The masking of wildcards etc. could be done in addition to provided 
   examples by any means of shell of course.

   All keyword in parameters are converted and treade internally 
   as uppercase. Though 'all' is equivalent to 'ALL', 'AlL', 'aLL',
   ...

   For most of the keywords alternative short-cuts are supported, but
   due to avoidance of ambiguity caused by generic plugins, no
   wildcard expansion is foreseen. So short-cuts have to match
   literally. For additional information refer to specific options.


   8.1.2. Options Scanners - Reserved Characters
   =============================================

     The foreseen and implemented scanners are designed to allow
     implementation in a straight-forward manner by simply nesting
     loops and using sets generated from simple regular expressions. 
     This is particularly important for simplification of
     user-implemented custom plugings. So following special characters
     are reserved for options definitions syntax:


       '=':   Seperator for option and it's suboptions. The reason for
              not using this as repetitive seperator are "CALLOPTS" and
              "XOPTS", which are bypassed options for remote execution.
              These contain almost for sure a "=", but simplicity of
              the scanner is the priority here, so a second is choosen
              for repetition on groups.
       '§':   Separator for groups of suboptions within one option.
              This is semantially identical to providing multiple
              repetition of the option itself with each group, which
              is not permitted for ctys. 
       ',':   Seperator for suboptions belonging to same group. 
       ':':   Seperator for suboption keys and it's arguments.
       '%':   Seperator for suboption argument values.

       '()':  Grouping character pair for target specific options
              belonging to a common target a.k.a. host.


       Remarks:
       '§':   This is currently not utilized, but pre-reserved for
              future forward-compatibility and usage in custom add-on
              plugins. 


   8.1.3. Sessions Name binding
   ============================


   8.1.4. Common Cache Handling
   ============================

     The name resolution for static and dynamic data could be
     performed basically by two approaches:

       - from cahced data by ctys-vhost and related tools

       - by polling of actual runtime data with "ctys -a LIST" call.

     Both approaches have their advances and impacts a any cache
     system has.

     When using the cache, this obviously has to be uptodate, when a
     data match occurs. When no match could be get, the realtime
     polling will be used by default.

     The perfomance impact of the realtime poll vs. cached data is
     frequently a factor more than 10, which is 5-15 seconds vs. 0.5
     seconds. The usual case is even more dramatic, usually 30 to
     60 seconds, for CREATE, could be even much longer, depending from
     the filesystem to be scanned. 

     In cases of runtime systems scan via LIST it depends on the
     actual load. This approach is normally somewhat different from
     the pure CREATE call, because just a part of the data could be
     used from the cache DB, which just represents "potential
     candidates", the actual runtime state has to be polled in any
     case, but could be done much more efficient of course.

     But anyhow, in specific situations the usage of the poll approach
     is the only one applicable. The systems bootstrap for example is
     normally performed with an empty cache DB, so no decision is
     required. This is particularly the case, due to the usage of
     ENUMERATE itself for evaluation and collection of the cache DB.


     The cache behaviour could be commonly controlled by the following
     two keyword:


       NOCACHE

         Disables the usage of cached data for address resolution. 
         Therefore the call of "ctys-vhost" and related utilities is
         disabled.

         The default behaviour is to used CACHE first, which resolves
         for the low-medium reference system frequently within less
         than 0.5 seconds to a match. When no match found POLL is
         used, which is an internal ENUMERATE call and may have an
         performance impact of multiples of 10 and even more,
         depending on the size and structure of the scanned
         filesystem. The responsetime is frequently in the range of
         30-60 seconds, and more.

         When activated, at least polling has to be allowed, otherwise
         no resolution will be possible.


       NOPOLL

         Disables the polling of data, thus CACHE is required.  A
         missing hit on cached data will lead to failing of
         resolution.



   8.1.4. Common Stack Handling
   ============================

     The utilization of VM stacks, which are nested and therefore
     encapsulate each level requires for several methods some specific
     recognition and stack-awareness.

     Almost each action requires it's own specific handling.


       CREATE

         The CREATE action is almost only effected specifically, when
         a stack-level is requested to be activated, for which the
         containing (n-1)-level stack entity is not yet present, this
         statement includes any lower missing entity too.

         Therefore it has to be decided whether the request should be
         rejected or an implicit stack-recovery has to be performed.

         When the decision is made for implicit recovery, the
         algorithm could be said to 

             "process-upward-from-highest-existent".


       CANCEL

         The CANCEL action is effected by stack-awareness when a stack
         entity is requested to be canceled, which has active
         contained upper stack entities.

         In this case the decision to be made are one or a combination
         of

           - propagate CANCEL request to upper stack
           - use hypervisor only, ignore upper stack
           - "kill" if supported (e.g. not Xen) the current level
             hypervisor
           - CANCEL the execution target, which is the execution level
             of stack "itself", e.g. essential for PMs.

         When the decision is made for state-change-forward-propagation,
         the algorithm could be said to 

             1. "walk-upward-to-all-highest-existent"
             2. "process-downward-to-request-target"


       LIST

         This action has to be stack-aware on request, it is the most
         beneficial dynamic information collector for the user in
         order to manage VM stacks.


       SHOW

         This action should be stack-aware on request, it is a
         beneficial dynamic information collector for the user in
         order to manage VM stacks.


       ENUMERATE

         This action must not be stack aware, what is due to the
         practical circumstance, that the destination VMs has to be
         active, when to be enumerated for the executable VMs. 

         Thus, as long, as not the offline VM images could be scanned
         (which will be exepectedly never the case for all VMs), this
         call would have lead to the activation of ALL VMs executable,
         thus it probably could be said, will never finish due to
         bulk-start-perfomance-impact!

         

       INFO

         Basically almost the same as ENUMERATE.



     Due to the impact of stack awreness for execution, this behaviour
     could be controlled for the methods

     Almost each action requires it's own specific handling.

       FORCE

         Performs the requested action immediately by calling the
         hypervisor. No forward propagation is performed. 

         The specific range of features for the various hypervisors
	 could and do vary, thus will be specialized within the
	 description of the specific plugin.


       STACK


         Performs the requested action first by state-propagation
	 "deeper into the nested stack", which means upward due to
	 ISO-like stack model.

         The behaviour when failing with state-change-request
         propagation depends on the actual request.

         The hypervisor might be called as final anchor in case the
	 propagation fails or timeouts for a CANCEL request, because
	 otherwise the request may fail, even though it could have
	 been finished by usage of the hypervisor. A decision whether
	 or not to perform a "final and ultimate kill" on the stack is
	 not obvious due to the hidden upper part, which basically
	 could include any highly sensitive task, resulting in crucial
	 failure when canceld abrupt. This risk will remain for
	 generic actions, and has to be handeled by the application
	 and it's close systems within the encapsulated stack
	 entities.

         For the CREATE action - which is in case of STACK an
         iterative upward execution - the call of the hypevisor is
         necessarily the first call on each level. Thus in case of
         CREATE in contrast to the CANCEL action the transparency of
         the stack is system immanent. 

         The call of the hypervisor could be followed by an
         state-change-propagation request after success only. The
         remaining question for partial execution is here what to do
         with an uncomplete VM stack. 

         The answer for now is "let him live". This has to be
         monitored and handeled appropriately by the user when the "-b
         on" option for asynchronous background operations is
         choosen. In case of synchronous operations the job will be
         canceled, but also no roll-back is performed. Just the
         monitoring is implied due to synchronity.

         The dynamic information poll methods LIST and SHOW just
         ignore a propagation failure, this is the same behaviour as
         in the case that nothing was found.



       SELF

         The SELF keyword is currently for CANCEL action used only,
         but will of such basic level of understanding, that it is
         shown here.

         SELF causes the inclusion of the execution target for
         requested operations too. 

         This is due to the technical requirement, that any method for
         an stacked entity has to be initially performed within it's
         container entity, which hosts the bottom controller instance
         of the targeted stack-level - it's hypervisor - for ultimate
         superposing action.

         The basic call structure 

             ctys -a <action>=<action-target> <execution-target>

         of ctys is splitted into the <execution-target> where the
         first communications peer entity resides, and the
         <action-target>, which is the destination of <action> to be
         performed.




   8.1.4. The Untold Shifted Stack Essential - CREATE
   ==================================================

     One of the most beneficial features for stacked VMs would be the
     implicit creation of missing sessions within the execution
     stack. Anyhow, even though it is basically possible to do this
     with some current VM implementations, this feature is shifted. 

     The reason is simply the lack of a common strategy within the
     used VMs, where at least XEN and QEMU would be suitable, but
     others not for an unattended and ServerOnly iterative CREATE
     chain. In avoidance of a quick-shot resulting in some
     "savage-variants" when coming to details, the decision for this
     version is not to implement the automatic and implicit creation
     of inactive intermediate stack entities.

     Therefore this feature is currently shifted and will be
     implemented within a later version. For now each stack entity has
     to be CREATED seperately and explicitly by the user, in manual
     iteration.

     For CANCEL anything stays as it is, stacked operations are
     supported as described.
