

Usage: 
======

   ctys-vhost [options] <awk-regexpr>[ <awk-regexpr>[ <...>]]


   ATTENTION: Default behaviour is no output, thus
              you need to select one, e.g. "-o ...".


Description:
============

   This is the basic address resolution interface for runtime
   execution of commands based on ctys addressing. 

   The similiarity of UNIX "host" function is expanded with several
   features, which take into account the roaming of VMs and thus
   changing their actual execution path within a so called "execution
   stack" assembled by PMs, VMs, and HOSTs.

   Due to technical reasons the locator functionality required for
   building complete fully qualified ctys-addresses of execution
   stacks, which could be seen as a UNIX "ping" similiarity, is
   included.

   Particularly a basic load-balancing is included, which is very
   basic of course, but could be extended easily. The current version
   requires at least one of the potential ExecTargets to be active,
   which could be a PM for execution of a VM to perform acommand, or a
   VM for execution of a command only, no automatic start of
   deactivated sessions are performed.


   The main task of this tool is supporting a scripting-IF as a link 
   with an convenient name-binding scheme between a GuestOS and it's
   containing VM and PM by an open and GuestOS-Native interface. The
   whole access and security facility of VMs and PMs including 
   HOSTs(e.g. VNC) is handled by encrypted connections only. It is 
   designed and implemented as a seamless SSH-based authorization and 
   authentication system. The authors environment utilizes Kerberos, 
   LDAP, and SSH with automount for SSO. The ctys-vhost  supports
   mainly the glue for seamless binding of roaming VMs on a homogenous
   UNIX platform.

   Simplicity and common extendibility by widely used bash is another 
   present feature.

   Due to targeted simplicity and efficiency the address resolution 
   is based on simple unstructured pattern matching by regular 
   expressions. Even though the line-record is structured by fields
   as given by "-a LIST=MACHINE" and "-a ENUMERATE=MACHINE", the match 
   itself will be performed as a simple regexpr by "awk-match". 
   Whereas the output is performed on the level of fields. Multiple
   regexprs are supported and will be iterative applied on the
   intermediary results. The reduction of the output as requested by
   the "-o" option is performed on the final set of resulting records
   only.

   This fits perfectly, as long as the given IDs are kept unique,
   when ambiguity occurs, the match will be taken as defined by
   "-M" option.

   REMARK: 
      This flat-and-simple approach works as good or better to say
      much better than any "Attribute-Value-Assertion"  or any other
      kind of an Object-Tree based access. And the best is, you
      can implement it within some days, without any framework to be
      used!!!

   Ambiguity occurs frequently when using a VM with NFS(or an other
   some more secure network file system) from multiple machines and
   using the nodes as processing-capacity-only. Accessing the same
   files and enumerating them for selection of the appropriate
   execution machine could be a mandatory requirement for
   load-distribution policies. In this case a basic COST option "-C"
   supports the very basic "-M" option for some quite usable load
   distribution within execution-groups.

   In most other cases uniqueness should be given, e.g. the key
   UUID is defined to be uniqe, but could be tampered e.g. by
   co-allocated backups. For avoiding of backup-access the "-M first"
   option might be helpful.

   Anyhow, the management of up to some hundred VMs might not be a
   challange by the current file-DB and not really
   performance-optimized toolset. One of the next versions will
   additionally support LDAP based nameservices, targeting an
   enterprise environment with "unlimited" and "volatile" distributed
   services to be managed.

   When a MAC-IPAddress-HostName mapping table a.k.a. "macmap-DB"
   is present this will be used for open mappings which are not
   configured within the VM configuration files a.k.a. enum-DB. 
   Particularly any IP or PM/Hostname address for given MAC-Address
   will be resolved when not present within the enum-DB.

   The address resolution will be performed by the following steps:

     1. Check the static list of given ExecGroup for possible
        candidates.

     2. List the active sessions on the given ExecGroup.

     3. Take the appropriate PM/VM by utilising "-C" and/or "-M" 
        option.

   For additional help refer to online help within  "ctys" to the 
   section "NAMESERVICE-BASE".

   Now some real benefits when using ctys-vhost as interactive tool 
   instead of using id from scripts:

   -> Given partial strings, e.g. "192.168.1" lists all machines of 
      that subnet. When the "-M active" option is choosen, all
      currently active sessions within that subnet are listed.

   -> Any string could be used as partial pattern, e.g. parts of
      MAC-Ids of fragments of UUIDs. The given string will be matched
      against complete record, mostly ba awk-regexpr, thus any part,
      even spanning multiple FIELDS could be used. But currently not
      regexpr, just literal characters are supported.

   -> The database founding the mapping information of ctys-vhost
      could be altered by "-p" option for handling of multiple sets,
      e.g. for test-purposes. 

   -> The databases enum-DB and macmap-DB are populated just with the 
      native information provided by their main sources, dhcpd.conf
      and the config-files of supported VMs. Therefore not any
      information might be present in each of them, e.g. the
      IP-Address of the GuestOS might be present within the macmap-DB,
      but not within the VM-config. The "-S" option allows the
      combined usage of multiple sources, e.g. by values "all",
      "macmap", or "enum".

   -> ctys specific configurations-extensions as described for the 
      "-a ENUMERATE" option are fully supported. This includes
      particularly the storage of GuestOS information within the
      VM-config by specific ctys-Prefixes(#@#) and some helpful
      keywords.


Options:
========

   -c <spent cost on execution environment>

      Cost as for load distribution when selecting a target.

      <spent cost on execution environment>=MINCNT|MAXCNT
        

        MINCNT: Gives minimum loaded target, number of given types are
                simply counted.
        MAXCNT: Gives maximum loaded target, number of given types are
                simply counted.
        CNT:    Lists each target with it's TYPE-COUNT.

      Companion options apply to resulting set of equal cost.


   -C <DB sources>

      Limits the generation of the cache DB to the for
      mapping-resolution to the listed souces. Default is to use
      all. Only available databases will be used, missing are
      silenty ingnored.

      Due to some peformance issues when repetitively accessing same
      temporary runtime data, some internal caches are defined. These
      can be controlled, and resused  or cleared by usage of some of
      the following keywords. But additionally some automatic checks
      apply.

      1. For data from static information, which has to be
         pre-processed a local chache-DB is created. This cache-DB
         will be checked for modification time of it's sources before
         each access and updated when outdated.

      2. The modification time of the cache files will be checked
         additionally for their age. When these exceeds the value
         defined by CACHECLEARPERIOD, which is by default 3600seconds,
         the caches are forced-cleared and rebuild silently by next
         call.

      The following data sources will be utilized:

      ENUM      Enumaration results only, as supplied by cached local
                "enum.fdb".

      MACMAP    DHCP information for MAC resolution, the macmap-DB
                should be available, but is otherwise simply ignored.

                This will be utilized in conjunction with an enumeation
                result, e.g. ENUM. 

      GROUPS    Adds caching of GROUPS for all group files from the
                current CTYS_GROUPS_PATH variable. Therefore each
                group file will be completely expanded by nested
                evaluation and replacement of "#include" statements
                and stored by repacing each resulting entry with it's
                MACHINE format entry from the staticCacheDB.

                Each group will be cached within an file by it's own,
                thus the access could be performed by just one
                file-selection for the complete nested resolution of
                it's entities.


      <DB sources>=
          OFF|
          CLEARTMP|
          CLEARALL|
          GROUPS|
          KEEPALL|
          LIST|
          LISTARGETS|
          LISTGROUPS|
          MEMBERSDB|
          MACMAPONLY|
          MACMAP|
          REBUILDCACHE

      This group of keywords controls the runtime behaviour, which
      has an impact to the overall performance.

      OFF        Bypasses the usage of caches. 

      MACMAPONLY
                Uses the macmap.fdb only for mapping, this is just
                senceful for mappings between DNS, MAC, and TCP. The
                request will be rejected, when "-o" option contains
                any other input.

                For matching entities within MACMAP this might be the
                fastest approach. It is the only applicable approach,
                when the target is not yet populated in standard DB,
                for example due to pre-initial conditions.

      MACMAP    Activates the raw usage of macmap.fdb for DNS, MAC,
                and TCP as preferred source of resolution.

                This has two flavours, depending from selected output
                attributes:

                1. Only one of, or all: TCP|MAC|DNS
                   In this case the MACMAP DB will be utilized within
                   the "bigger awk", due complete probable
                   containement of information thus first a raw access
                   to MACMAP will be tried. When no result was found,
                   the general script with DNS/Bind access will be
                   performed. In standard manner(due to SW
                   architecture, ignoring previous trial).

                2. Additional output requested:
                   In this case particularly the field positions of
                   the resulting output can not be handled in a smart
                   manner for an independent pre-filter, though the
                   standard execution path is performed.

                When the macmap.fdb is properly maintained and
                contains the complete scope of mapping information,
                this enhances the performance, else it could have an
                negative impact, even though it will not be dramatic,
                or for small amounts almost not recognizable.

                A second aspect to be aware of is, that the two
                different databases might diverge. Particularly the
                order of the stored records could not be relied on to
                be the same. When using the option "-M all" the order
                might not be relevant, but for "-M first"(default) and
                for "-M last" the results might frequently be
                different.

                The basic difference of the contents is the fact, that
                the macmap.fdb (let us say!) contains any networked
                host, whereas the standard enum.fdb the registered VMs
                only, so might be a subset of macmap.fdb.
   
                The correlation of both will be performed, when a
                cache is build and addressing references are resolved
                for faster access.

      GROUPS    Activates the usage of GROUPS and it's related cache
                data which is due to performance issues deactivated
                for now by default.


      The following additional keywords control and support the
      management of internal caches.


      LISTCACHE  Lists all current caches. 

                 This call terminates immediately after performing, so
                 any remaining options are ignored.

      LISTTARGETS
                 Lists all current cached targets. 

                 This call terminates immediately after performing, so
                 any remaining options are ignored.

      LISTGROUPS Lists all current cached groups. 

                 This call terminates immediately after performing, so
                 any remaining options are ignored.

      MEMBERSDB  Displays a list of all current staticCacheDB members
                 in ctys-stacked-address notation.

      CLEARTMP   Clear it's internal temporary caches first and
                 rebuild on demand.

      CLEARALL   Clear all it's internal caches first and rebuild on
                 demand.

                 This includes a directory-wildcard-clear, which
                 includes probably the caches of other tasks, so use it
                 considerably.

                 This call terminates immediately after performing, so
                 any remaining options are ignored.

      REBUILDCACHE
                 The static data to be concatenated from static
                 assembly databases, for now the enum-DB and the
                 macmap-DB is cached within a static database and
                 concatenated with the volatile RT data into the
                 RTCACHE. 

                 The requirement of rebuild for the static data is
                 checked by modification time of it's components, and
                 when required updated silently. 

                 When setting this flag, the data is rebuild in any
                 case.


      Additional information is available from description of:

       -> NAMESERVICES of "ctys -H"
       -> "ctys -a ENUMERATE...." 
       -> "ctys-extractMAClst"
       -> "ctys-vdbgen"


   -d <debug-level>

      Same as ctys.


   -h 

      help


   -i <input-list>

      Options controlling input content for specific cases.

      <input-list>=
         [(CTYSADDRESS|CTYS)]


         CTYSADDRESS|CTYS

           A fully qualified address is supported for mapping of one
           of the given output attributes.


   -I

      Interactive, gives summarised display of progress for main values.


   -l <USER>
      DEFAULT=CTYS_NETACCOUNT(DEFAULT->USER)

      Remote user to be used for SSH-access-checks, when the "-R"
      option is activated.


   -M <result-set-output-reduction>

      Restricts a set of multiple results with additional 
      constrains for output:

      <result-set-output-reduction>=FIRST|LAST|ALL

        FIRST   : First matching entity.
        LAST    : Last matching entity.
        ALL     : All matching entities.


   -o <output-list>

      Options controlling output content. Values of all given options are
      listed as one RECORD per line for each matched entity. The keywords
      are not case sensitive and could be used as a comma-seperated list.
      Shortcuts are applicable mostly as one-character alternatives as
      listed.

      <output-list>=
         [(CLIENTACCESS|CACCESS|CPORT|C),]
         [(CLIENTDISPLAY|CDISPLAY|DISP|D),]
         [(CTYSADDRESS|CTYS),]
         [(DNS),]
         [(IDD),]
         [(IDS|ID|I),]
         [(MAC|M),]
         [(MACHINE),]
         [(MAXKEY),]
         [(UUID|U),]
         [(OS|O),]
         [(PM|HOST|H),]
         [(SERVERACCESS|SACCESS|SPORT|S),]
         [(TCP|T),]
         [(MT|MTYPE)]


         MACHINE

           Complete records matching the <regexpr-list> in terse
           format for postprocessing.

         MAXKEY

           The maximum common set of attributes for LIST and
           ENUMERATE.

         CLIENTACCESS|CACCESS|CPORT

           Client access port for execution of a TCP/IP connect. This
           is the raw port to be used for vncviewer or proprietary
           clients with their own MuxDemux-dispatcher.

         CLIENTDISPLAY|CDISPLAY|DISP

           DISPLAY to be used by XClients, which in case of VNC is
           already calculated by usage of context-specific PortOffset.

         CTYSADDRESS|CTYS

           A fully qualified address to be used within ctys. This
           includes the complete address for the whole execution-stack
           of the destination instance, beginning with hosting PM.

           Whereas almost any other output is just a subset of the
           generated static database, this value is the result of the
           assembly of multiple items to a complete address for an
           unambiguous execution path. The namespace could be the
           private network or even the global network, when globally
           unique PM addresses as FQDN are used.


           REMARK: A probable extension to ISO object identifiers is
                   within evaluation of future extension.


         DNS|D

           Output of TCP/IP address (any valid for the VM). This
           option supports the name representation as reported by DNS,
           for the numerical representation refer to DNS.

           ATTENTION: Only the first match will be listed when
                      multiple addresses are present for the same
                      entity.

         IDD ( => Not yet Implemented)

           Output of dynamic ID, which is a UNIX-pid or in case of XEN
           the actual DomainID. When seperate Client/Server-Components
           exist, they will be distinguished by their IDD too.


         IDS|ID|I

           Output of static ID, which is a pathname for VMs, and a
           runtime ID for HOSTs. The IDs are (foreseen to be!?) unique
           within the namespace of their PM or VM. This should be
           considered when roaming VMs between PMs.

           Following current exceptions apply:
  
           - XEN
             The value is the configuration path statically unique on 
             local host, common to IDs of other VMs. 

             The domain-ID is handled - due to hypervisor architecture 
             and structural and dynamic means of accessibility -
             similiar to an ordinary "UNIX-pid".

           - HOSTs
             For plugins of type HOST, which are more or less simple 
             processes offering specific services, the "UNIX-ID" is 
             utilized.

             The "UNIX-ID" could consist of several kinds of
             entries. A common example is VNC, where the entries
             semantic could be one of:

               -> DISPLAY = VNC-port-offset
               -> DISPLAY = VNC-port

               -> Any of above could be context-specific, and utilized
                  more or less correlated by any other FBP-aware
                  application too. E.g. vncviewer for XEN and
                  WMWare-Workstation 6.


             In addition, for a pluging a ctys specific ID might be
             defined, e.g. based on "UNIX-PID".


             So, ... it is just an abstract ID, no bigger
             overall-algorithm applicable.


         LABEL|L

           Output of LABEL.



         MAC|M

           Output of MAC address.

           ATTENTION: Only the first match will be listed when multiple 
                      addresses are present for the same entity.


         UUID|U

           Output of UUID.


         OS|O

           Output of OS as configured.


         PM|HOST|H

           Output of TCP/IP address of the PM-Physical Machine, which
           is the hosting machine.
         

         SERVERACCESS|SACCESS|SPORT|S

           Server access port for execution of a TCP/IP connect. This
           is the raw port to be used for server specific admin tools,
           which is different from user's client access. This port is
           currently rarely supported, namely not utilized due to
           security reasons, e.g. in case of XEN.

           The main intention of ctys is to avoid propriatery
           interfaces as much as possible, and support "bare support
           tools" only. This interface could only be propriatery. So
           being honest, 'do not really like that!


         TCP|T

           Output of TCP/IP address (any valid for the VM). This
           option supports the numerical representation, for the name
           representation refer to DNS.

           ATTENTION: Only the first match will be listed when
                      multiple addresses are present for the same
                      entity.


         MT|MTYPE

           Output of the type of machine, either a VM, PM, or a
           HOST. It' TCP/IP address is the "-t" option.



   -p <db-directory-path-list>

      Comma seperated path list to directories containing the
      name-resolution DBs, same for each <db-directory-path> as for
      ctys-vdbgen. 

      ctys-vhost could handle multiple mapping-DBs for virtual
      concatination. The advantage of this is the ability of
      substructuring VMs and PMs into access-groups by ctys-vdbgen 
      and using them in combinations as required during runtime. This
      offers particularly advantages when performing ctys-vhost for
      loadbalancing by usage of cost-option "-C".      


   -r 
      Activates the common usage of dynamic runtime data. Without this
      option only some distinct functions like load-distribution
      utilize selective calls of runtime-data-evaluation for further
      restricting their intermediate results. This is e.g. obviously
      the count of actual executed instances on a PM for the case of
      cost evaluation on a potential distributioon target.

      When runtime data evalation is activated in general, the "-R"
      option alplies to any result as a further constraint.

      The usage of runtime data evaluation cost performance of
      course. This could become dominant, when huge clusters are
      evaluated, thus should be considered whether really required,
      and applied to reasonable sets only. But anyhow, when some
      bigger sets are required by definition, caching of data with
      different strategies could be applied.


   -R <runtime states>

      Restricts a set of multiple results with additional 
      constrains for output.

      Only the possible targets which are actually operational are
      listed. This includes the actual running VM with it's hosting
      PM, and in addition all other operational machines, where the
      current VM is available too. This case is the most common for
      NFS based exec-pools, where a single VM could be accessed
      remotely by a number of PMs. This particularly offers the
      advantage of copyless-migration of online and offline VMs.

      Very handy, and in companion with others probably one 
      of the most important internal top-level-calls for 
      GuestOS-Command-Execution.
      
      <runtime states>=[MARK|(REVERSE|R|-),]PING|SSH[,PM|VM]


        MARK    : A match for any of the following keywords is simply
                  maked with a prfix as running by "R;", instead of
                  just showing the resulting set.

                  The remaining will be formatted with "-;" as prefix
                  for alignment.

        REVERSE|R|-:
                  This reverses the resulting set, thus the "not
                  matching" states only will be shown.


        PING    : A RUNNING session is simply "ping-ed".

                  Resulting statement of operational mode may result on 
                  applied security policies, but not exclusively on the 
                  state of the running OS's IP-stack.

        SSH     : A RUNNING session is additionally checked for 
                  SSH-connect by a dummy-interconnect.
 
                  This might be really senceful, once SSO is established.

                  "ssh" is the only and one state, which is a viable 
                  confirmation for the ability of establishing ctys 
                  connections.

        PM      : Checks only PM for accesibility, which is the
                  default behaviour.

                  PM accessibility is defined as the accessibility of
                  the running OS on PM.

        VM      : Checks VM for accesibility, this is
                  particularly related to the SSH key.

                  VM accessibility is defined as the accessibility of
                  the running OS on VM.


   -S <BasicDataManagementSupport>

      The "-W" option represents some basic management interfaces for
      the additional entity class GROUPS and the entity
      chrachteristics CONTAINMENT. Where the containment is applied to
      the whole set of stored entities.

      These interfaces allow some smart listing and display of current
      supported data, the handling of data as deletion and creation is
      handeled by the ctys-vhost command as appropriate.

      <BasicManagementSupport>=
          LIST|
          LISTDB|
          MEMBERSDB|
          LISTGROUP|
          MEMBERSGROUP[23]


      The following keywords may be applied.

      LIST       Displays a list of all current data sources, the same
                 as 

                      LIST = LISTDB + LISTGROUP


      LISTDB     Displays a list of current file-databases.


      MEMBERSDB  Displays a list of all current staticCacheDB members
                 in ctys-stacked-address notation.

      LISTGROUP

                 List all current groups from the CTYS_GROUPS_PATH.

                 The output format is as follows:

                 " <size> <#lrec>/<#incs> <#srec> <group>"


                  <size>      Size n kBytes.

                  <#lrecs>    The overall number of target entities
                              without resolution of nesting, so just
                              the current file is evaluated.

                  <#incs>     The overall number of include-statements
                              contained within current file.

                  <#srecs>    The overall number of target entities
                              with  resolution of all nested includes.

                   <group>    The name of current group, which is the
                              filename too. When "-X" option is set
                              (LEFT of this option), than the basename
                              is shown only, else the full
                              filepathname.

      MEMBERSGROUP
                 List all members of current groups from the
                 CTYS_GROUPS_PATH. The nested containment hierarchy
                 will be expanded before output.

                 Two types of storage are shown:

                   1. Raw group files, which may contain target
                      entities, include-statements and comment lines.

                   2. Cache group files, which contain the whole
                      resolved set of containement tree as flat target
                      entity recoerd from the statCacheDB.

      MEMBERSGROUP2|MEMBERSGROUP3
                 Same as MEMBERSGROUP, but with slightly different
                 output format.


      Additional information is available from description of:

       -> NAMESERVICES of "ctys -H"
       -> "ctys -a ENUMERATE...." 
       -> "ctys-extractMAClst"
       -> "ctys-vdbgen"


   -T <type-list>

      Types to be recognized when calculating target.
      For additional information refer to "-T" option of ctys.


   -V

      Shows version.


   -W

      Suppress warnings.


   -X

      See ctys, terse for machine output.

      REMARK: Due to order dependency of options evaluation, set this
              as first/leftmost option.


Arguments:
==========
       
   <awk-regexpr>[ <awk-regexpr>[ <...>]]

      A list of simple awk regular expression, for matching based on $0. This
      is called here "flat-matching", though no structural information
      like in case of attribute-value assertion, is recognized for
      the pattern match.

      The given lists are matched each on the resulting set of
      complete records from the previous pattern-matching. The last 
      filter applied will be accompanied by reduction of fields of
      final matching records as selected by "-o" option.

      The main advantage of this approach is the simplicity of data
      structures and the utilization of common tools and data
      structures. Some performance gain is another advantage.

      The drawback is, that in some cases the regexpr has to be
      choosen thoroughly.

      Some Examples:

        inst
              All items which contain any string "inst"

        '^inst' 

              All items, which start with "inst", where the first
              field in a record is the hostname.


      The format of the records is as given by ENUMERATE, the fields
      are seperated by semicolons:


        Enumerate-Output-Format:
        ========================

          +-----------------------------+
            0 - h:    host              |
            1 - t:    type              |
            2 - l:    label             |
            3 - i:    id                | Identical to LIST
            4 - uu:   uuid              |
            5 - mac:  mac               |
          +-----------------------------+
            6 - IP
            7 - VNCPORT
            8 - VNCBASE
            9 - VNCDISPLAY
           10 - DISTRO
           11 - OS
           12 - VERNO
           13 - SERNO
           14 - CATEGORY


