   9.2.1. CLI - Command Line Interface
   =================================

   9.2.1.1. Description
    -------------------

     The CLI-plugin starts simply a remote shell from within a local
     shell. No specific desktop functionality such as XTerm is
     supported, just a pure CLI access is performed. The handling of
     own desktop windows such as XTerm or GTerm will be supported by
     the X11-Plugin.

     The execution of the interconnecting ssh-call will be performed
     by setting the "-X" option for automatic X11-Portforwarding. Thus
     even though the CLI session itself is not GUI based, any X11
     XClient could be started and will be displayed on the local
     caller's XServer by usage of the encrypted channel. 

     Chained logins by gateways with Overall-Display-Forwarding is
     supported by OpenSSH, thus by ctys too. This is for example
     required for the PM pluging, when an intermediate relay is
     required for sending a WoL packet during a CREATE action and
     openning a session from the <execution-target> - which is the
     relay - to the started PM.


     When executing CLI almost the same functionality as for an
     ordinary SSH session is supported. The main advance of using
     ctys instead of an ordinary ssh-call is the seamless integration
     of native ctys-addressing for execution targets.

     So, instead of an IP adress the <machine-address> can be
     used. Thus the administration of address-to-target-mapping could
     be completly delegated to ctys and will be utilized by internal
     usage of the full scope of ctys-vhost.

     E.g. the LABELS defined within ctys could be used to open a
     remote shell to any "labeled" instance such as a VM or PM.

     Another option might be the usage of UUIDs or MAC-Addresses for
     persistent definition of the handling commands on frequently
     changing and reinstalled systems with reassigned IP-Addresses and
     DNS names. This could be extremly valuable for extensive tests on
     large systems with different scenarios and participating member
     collections.

     The second important feature of CLI is to start native remote
     commands as shell calls within any managed PM or VM
     instance. Therefore CLI is the working horse for native execution
     of GUI-less ctys-tasks.

     Due to the simple remote-shell nature of CLI, just a few of the
     "Client/Server" based actions are applicable. 


     The default shell used on the target instance is bash by
     definition of CLI_SHELL_DEFAULT, see CREATE action. The execution
     of remote commands is preset by CLI_SHELL_CMD_DEFAULT, see CREATE
     action.

     ATTENTION: The ONLY and ONE supported shell is the bash, any
                other my produce suprising results, so it's your own
                risk.



   9.2.1.2. Options
    ---------------

     -a action[=<suboptions>]
 
 
         CREATE

            CREATE=[<machine-address>]
                   [,<CALLOPTS|C>]
                   [,<XOPTS|X>]
                   [,<PSEUDOTTY|PTTY>]
                   [,<SHELL|S>]
                   [,<CMD>]


            <machine-address>

              See standard for syntax.

              The LABEL suboption is here mandatory.



            <CALLOPTS|C>

              See standard.



            <XOPTS|X>
              See standard.



            <PSEUDOTTY|PTTY>

              The execution will be perfomed by usage of "-t" parameter
              for pseudotty allocation. Multiple presence of this
              keyword behaves the same as for native OpenSSH call.



            <SHELL|S>

              Replaces the standard definition of an interactive shell
              by 

                    CLI_SHELL_DEFAULT='bash -i'

              for remote execution.

              When setting an own shell the masking of SPACEs has to
              be applied by "%" in accordance to common ctys cli
              rules.
              The default will be applied on command line interface
              as:

                 ... -a CREATE=c:'bash%-i' ...




            <CMD>

              Replaces the standard definition of an command execution
              shell by 

                    CLI_SHELL_CMD_DEFAULT="bash -c"

              for remote execution.


            A specific exeception to the sysnchronous character of an
            CLI shell occurs, when multiple execution instaces are
            addressed by the arguments of current call. When the "-b
            off" option for background a.k.a asynchronous operations
            is selected, the standard synchronous foreground operation
            works quite well. The list of arguments is just executed
            sequentially as expected.

            The expected behaviuor as will be implemented later:

               When "-b on" is set, this will be forced to " -b off "
               for an interactive call, whereas in case of a present
               CMD suboption the command will be forked to the
               background on each target. This disables the IO
               streams partly, due to the specific behaviour of SSH
               for detached clients when using "-f" option. So no
               input stream is any longer available for the callers
               terminal. 

            In current implementation the user is responsible for
            handling the appropriate values, which are assigned by
            default. The enforcement of resetting user defined values
            could be somewhat tricky due to permutation of bulk
            arguments, thus is shifted because of priorities.


         ENUMERATE
         =========
 
            Not applicable to CLI.
 
 
         LIST
         ====

           Almost the same output as common standard, with following
           changes in semantics.


             [id]
               The PID of the local SSH termination point, which is
               the locally executed relay-instance of ctys and is the
               parent shell of actual running batch/interactive shell.

             [dsp]
               PID of current interactive shell as child of ctys
               sessions top. The actual DISPLAY has to be evaluated
               inside the running shell appropriately.

             [pid]
               PID of current ctys sessions top.


           Exactly the same semantics as common standard:


             label, type, gid, user, group, host, cs


           The following values are not applicable:

             uuid, mac, cp, sp

           

           List-Output-Format for MACHINE option:
            -------------------------------------

             +-----------------------------+
               0 - h:    host              |
               1 - t:    type
               2 - l:    label             | Structure is 
               3 - i:    id                | identical to ENUMERATE
               4 - uu:   uuid              | action
               5 - mac:  mac               |
             +-----------------------------+
               6 - dsp:  display
               7 - cp:   client access port
               8 - sp:   server access port
               9 - p:    pid
              10 - u:    uid
              11 - g:    gid
              12 - cs:   client|server



         CANCEL
         ======
 
            Not applicable to CLI.
 


     -L (LocalOnly|LO)
       | (DisplayForwarding|DF)
 
       Even though a DISPLAY will actually not be used, this parameter
       also adopts the behavior of the execution to a providing
       environment, which is frequently for ctys true.

       So these are the only location parameters to be applied.
