   9.3.1. PM - Linux and BSD Hosts
   ===============================

   9.3.1.1. Descrition
    ------------------

    This plugin adds support for PM sessions to PhysicalMachines
    running the OS PM. 

    As console currently Soft-Consoles are supported, which are here
    CLI, XTERM, and VNC.


    PREREQUISITES/RECOMMENDATIONS:

      1. The BIOS of the PM has to be configured appropriately. 
         The almost in anycase required configuration includes the
         following flags frequently found in APM mask:

           -> PME Events
           -> Wake On LAN - Event
           -> Wake On Modem/Ring - Event

         The actual naming is similar to the above.

      2. Even though this functionality should be almost HW
         independent, the x86_64 and i386 platform for Intel, AMD, and
         VIA based CPUs is tested only.

      3. The required utilities are "dmiencode" and "ether-wakeup".

      4. A machine record for ENUMERATE with full scope of data should
         be generated as root user by usage of tool "ctys-genmconf". 

      5. The caching database with at least a MAC mapping generated
         from dhcpd.conf by tool "ctys-extractMAClst" has to be
         present.

         Alternatively a manual entry for the destination machine
         could be added manually. For the format refer to 
         "ctys-extractMAClst".

         Preferably the full database in addition should be generated
         by usage of "ctys-vdbgen", which is of course a collector for
         running systems. Therefore for bootstrap MAC mapping is
         required and sufficient.


    Security Requirements
    =====================

     Some specific requirements arise from the specific execution
     structure of CREATE for the PM plugin. This is ingherent to the
     circumstance, that the target of PM as a container is not
     available before the successful execution - at least the first
     step - of CREATE. The specific case here is the fact, that the PM
     requires it's managed target as a runtime container for
     itself. In companion with the restricted permission to some tools
     like ether-wake, a gateway-host for execution of the CREATE method
     is required. 

     For understanding the particular security issues, the following
     current design principles of ctys are needed to be realized.

      - No connection without encryption
      - Currently no 3-party connections, so just clear peer-to-peer
        connection are allowed. Thus a gateway is not "really"
        foreseen, even though some virtual circuits will be added
        soon.

        Any how, the encryption path is the established path only, so
        no bypassing is allowed, chainning of forwarding,
        e.g. X-forwarding could be accepted.

        This point particularly eases the implementation of
        restrictive  individual firewall rules.

     The basic connection instancs for PM are:



                           +-----------+      +--------+
                          /           /|     /        /|
         +------+        +-----------+ |    +--------+ |
         |      |        |           | |    |        | |
         | call +--------+ execution +------+ target | |
         |      |        |           |/     |        |/
         +------+        +-----------+      +--------+
        /        \
       +----------+



        "ctys -t PM -a CREATE=WOL,<target> <execution>"



      Therefore for the CREATE(REUSE,RESUME) method of PM is currently
      the DisplayForwarding sub-option of "-L" supported only. This is
      due to the requirement of implementing a "polled-wait" on an
      initially booted host, which could take some time. For reasons of
      reduction of development efforts the relay-host - namely the
      <execution-target> - is used for the complete task of the action
      CREATE. This means in consequence as the execution base for the
      virtual CONSOLE to attached too. So due to usage of initially
      established "ssh-tunnels" only, for any kind of console,
      DisplayForwarding is the only applicable action. It supports any
      kind of terminal application applicable within an X11 environment.

      This limitation does not apply to the action
      CREATE(CONNECT,RECONNECT) which support only the attachement to
      already running instances, and therefore digging their own fresh
      tunnels.

      Any other action could be applied as common.


   9.3.1.2. Options
    ---------------

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

        CANCEL

            full <vm-address> range is supported.





        CREATE=<machine-address>
               [,WOL]
               [,CONSOLE:(CLI|GTERM|XTERM|VNC)]
               [,SSHACCESS[:<user>]]
               [,REUSE]


            <machine-address>

              The address of the machine to be activated. 


            WOL
              The addressed PM will be activated by Wake-On-LAN, which
              is in current version the only supported
              method. Therefore the default "ether-wakeup" tool is
              utilized by default. This could be changed by setting
              the environment variable CONSOLE_WOL, to which the
              MAC-address of the target will be appended. The current
              implementation expects all PMs within one subnet.
 

            SSHACCESS[:<user>]

              When activating a PM, the standard test includes 'ping'
              only with an additional timeout period. This is due to
              not neccessarily having a SSO setup for handling SSH
              logins. In order to avoid multiple password challenges
              in this case the ping answer only is checked. When SSO
              is configured the SSHACCESS keyword should be set, which
              garantees SSH access before handling the PM state as
              enabled.

              An optional user for trial-account could be provided,
              else current id is used.


            CONNECT|JOIN

              Opens just a new CONSOLE, requires therefore the PM in
              operational state.


            CONSOLE:(CLI|XTERM|GTERM|VNC)

              If given a console will be opened on the site of
              caller. This will be performed in addition to the
              standard console, which may be attached to the
              KVM-connectors.

              Default is CLI, which is based on a complete subcall with
              type CLI.

              The following 

              The "-b" option will be set for the types of consoles
              as:

                CLI    => "-b 0"
                XTERM  => "-b 1"
                GTERM  => "-b 1"
                VNC    => "-b 1"


            REUSE

              When PM is not yet running, it will be booted, else just
              connected with the choosen CONSOLE.


            RECONNECT,REPLACE

              When PM is yet running, it will be rebooted, else just
              booted and connected with the choosen CONSOLE.
            


        CONNECT=<machine-address>,CONSOLE:(CLI|XTERM|VNC)

            <machine-address>

            CONSOLE:(CLI|XTERM|VNC)

              Same as for CREATE.


            Opens just a new CONSOLE, requires therefore the PM in
            operational state.


         ENUMERATE

            This lists a pre-cached record when present. If not
            available the data will be collected dynamically as
            possible. This is defined, because the data is static and
            longterm-stable, additionaly requiering root access for
            parts like the UUID to be fetched by usage of "dmiencode".


         SUSPEND=DISK|RAM|BOTH

            Suspends current state as given.

            THIS IS CURRENTLY UNDER DEVELOPMENT AND MIGHT CHANGE.


         RESUME

            Resumes current state.

            THIS IS CURRENTLY UNDER DEVELOPMENT AND MIGHT CHANGE.



