ctys-beamer

July, 2010



.

NAME

ctys-beamer - transfers the final execution to a remote host


SYNTAX


ctys-beamer



   [-b <background-options>]
   [--ctys-predetach-holdtime=<timeout-secs>]
   [-d <debug-options>]
   [--display-only]   
   [--getfreeport}
   [-h]
   [-H <help-options>]
   [-L <remote-login>]
   [--mode=(
        (CTYS-HOPS|CH|0)
       |(SSH-CHAIN|SC|1)
       )
   ]
   [-R <remote-host-list>]
   [--ssh-hop-holdtime=<holdtime>]
   [--ssh-tunnel-holdtime=<holdtime>]
   [-V]
   [--x11]
   [-X]
   [<bypassed-ctys-options>]
   (--|--beam-this)
   <remote-command>


   <remote-host-list>:=<relay-chain>[,<remote-host-list>]

   <relay-chain>:=<relay-host>[%<relay-chain>]

   <relay-host>:=[<user>@](<host>|<access-point>)

   <access-point>:=<physical-access-point>|<virtual-access-point>

   <physical-access-point>:=<machine-address>
   <virtual-access-point>:=<machine-address>


   Evaluated options of bypassed standard set:
     <bypassed-ctys-options>:=[
       -b (0|1|2|3)[,(0|1|2|3)]
     ]






DESCRIPTION

UNDER DEVELOPMENT: The current interface may change and the functionality will be expanded. For now basic features for call-transformation with some advanced routing and call distribution are included.

ctys-beamer is the main interface for the transformation of a local call to a remote host for execution . Therefore an encrypted tunnel with and arbitrary number of intermediate hops on the route to remote host could be assigned. The defined route is hereby independent from the so called routing of the TCP/IP internet layer, enabling routing independent and encrypted connections for multi-level firewalls. The ctys-beamer also supports the definition of multiple targets for remote execution of the same command.

The particular advance here is the full integration into the common name binding and addressing schema of the UnifiedSessionsManager. This provides for extended address notation as well as for full scope of GROUP objects and MACROs.

The call-transfomation has to be distinguished from the remote-execution option of a command, which is semantically slightly different. The

call-transfomation is a call-neutral pure passive transformation for actual first-time execution on the remote site. This could be used particularly for security reasons, when safe and hidden bypassing routes has to be defined for administration purposes.

The distinction to the remote-execution of an executable is the active remote operation of application parts due to defined semantics of the call itself. Thus application specific knowledge for the current remote-execution context could be applied, this is e.g. the case for the combination of remotely collected data into a single list. The call-transfomation as an independent and call neutral dispatcher might fail in general for cases where the combination of the results from various execution sites into one overall result is required.

A typical call for a UNIX command is

  
  ctys-beamer -R app1 -- ls -l -h rpm
  

which performs the directory listing on the host app1. The following call

  
  ctys-beamer -R app1,app2 -- ctys -a list
  

creates two independent LIST action outputs of running ctys sessions, while the call

  
  ctys -a list  app1 app2
  

creates one LIST output for both hosts, which could be listed e.g. by overall SORT option. The following call

  
  ctys-beamer -R netscan/all -- ctys-vping targethost
  

executes independent ctys-vping scans of the 'targethost' remotely on each entititiy listed within the GROUP 'netscan/all'. While the call

  
  ctys-vping targethost
  

executes locally -- ctys-vping scaning 'targethost'. The call

  
  ctys-beamer -R app1%netscan/all -- ctys-vping targethost
  

executes from the relay-host 'app1' independent remote 'ctys-vping' on each entitiy within the GROUP 'netscan/all' for the scan of the 'targethost'.

The following examples show the creation of so called encrypted tunnels.

  
  ctys-beamer -b 0 -z 2 \
    -Y \
    --ssh-tunnel-holdtime=60 \
    --mode=HD \
    -R :3333%delphi%tst/grouptst02:7777%lab01 \
    -- ctys-vping ws22swi
  

This example particularly shows the handling of GROUPS and here the assignment of port to each entity contained in the GROUP. The exception are GROUP members, which have already a port assigned. The assigned ports have (for now - will be changed) priority over call options.

Background Operations:
For background operation the common option '-b' is evaluated, which is by default set suitable for interactive dialogue operations at the command line to SYNCHRONOUS and SEQUENTIAL mode.

LIMITATION:
The current version supports DISPLAYFORWARDING only. CONNECTIONFORWARDING is foreseen for a later version. Some options may vary for the different modes. The SSH modes - performing native ssh calls - may be used for now with common IP addressing([<user>@](<host-name>|<host-address>)[:<#port>]), whereas the CTYS modes - which use ctys as call interface - may cope the full range of addressing.

.

OPTIONS

ctys-beamer

Additional options are transparently bypassed to the internal 'ctys' call. This is particularly the case for the '-Y' option activating 'ForwardAgent yes'/'-A' of OpenSSH.

-b <background-mode-args>

Refer to "ctys" generic options for additional information.

--ctys-predetach-holdtime=<timeout-secs>

The holdtime before closing local foreground process. This applies in case of '--mode=CTYSHOPS' in order to prevent the early release of current tunnel for display of remote output. The default value is 10seconds, which should suit in almost any case. In almost any case about 5seconds should be OK.

The parameter is not senceful applicable in case of synchrounous operations by bypassed '-b' option of ctys..

-d <debug-args>

Refer to "ctys" generic options for additional information.

--display-only

This deactivates the actual final execution and displays the results only when e.g. '-d pf' is activated. The intermediate calls, e.g. for remote evaluation of free ports for an SSH tunnel are evaluated.

--getfreeport

This returns the first available free port on the execution site. Some configuration parameters like the SEED for handling the random generation within a range are provided.

-h

Print help, refer to "-H" for additional information.

-H <help-option>

The extended help option is based on system interfaces for display of manpages, PDF and HTML documents. This comprises the man pages and installed manuals.

For additional help refer to the documents or type ctys -H help.

-L <remote login>

The remote user for the inherent beamer function to place the execution immediately on an arbitrary execution relay. The semantics is somewhat different from the ordinary remote operations, which is application specific, whereas this 'beam-up' is a generic pre-execution forwarding.

--mode=<tunnel-mode>

Sets the mode for the encryption tunnel to be created for remote execution. Current version supports only one mode.

CTYSHOPS|CH|0

The encryption is performed in assembled sections, where the intermediate peers provide sections of the segment. The executable used is ctys, thus ssh is used as internal call only. The security of the intermediate hops has basically still to be assured, but the internode communications ist peer-to-peer encrypted.

SSHCHAIN|SC|1

The encryption is performed in assembled sections, where the intermediate peers provide sections of the segment. The security of the intermediate hops has basically still to be assured, but the internode communications ist peer-to-peer encrypted.



-R <remote-host-list>

The remote hosts including the relays on the way to be used. This enables the call of multiple execution hosts as well as an arbitrary chain of relays to be actually passed. The main advance of this funtion is to pearce multi-level firewall solution with chained DMZs, and still provide reliable and secure connections.

The relay chain could be opened and terminated by the optional assignment of access and termination ports, else the first free within the defined range is used. For the intermediate hops ports could be assigned too, but these are not checked for availability, when automatic assigment for intermediate ports is choosen(default), free ports are assigned as available. The port assignment may not be applicable to any mode of interconnection.

Valid calls are:

  ctys-beamer -R :3333%hop1%hop2%target ....
  ctys-beamer -R :3333%hop1%hop2:3333%target ....
  ctys-beamer -R :3333%hop1%hop2:3333%target:22 ....

Another closely related advance is to circumvent the routing of TCP/IP by usage of well-defined hops with stil reliable access by OpenSSH.

In case of multiple chains these are seperated by a ',', which terminates the previous and starts another definition of a chain of hops. Each chain starts at the current node and takes the given path of hops. The definiton of multiple chains of hops implicitly leads to parallelism by multiple executions of the identical target process. This could be a quite smart solution for a number of cases, but may be a serious drawback for others. E.g. in case of required uniqe identifiers exactly-cloned parallel execution threads are impractical, whereas a multiple ping measuremen of one target from 100 hosts initiated by one single call may fit quite well.

--ssh-hop-holdtime=<#timeout>

In case of CTYS-modes with applied asynchronous background mode the channel will be hold in idle mode at least for the assigned time. The value could be a numeric value in seconds, or provided with a valid 'sleep' unit-postfix.

--ssh-tunnel-holdtime=<#timeout>

In case of SSH-modes this is the timeout value for the final termination point of a one-shot tunnel. The value could be a numeric value in seconds, or provided with a valid 'sleep' unit-postfix.

-V

Version.

--x11

This parameter activates the X11Forwarding for ssh-tunnels '--mode=SC'.

-X

Terse output format, effects "-V" when set left-of.

.

ARGUMENTS

<remote-command>
The command to be executed on the final execution host. This command of course could be any command - including the ctys-beamer itself - which again calls a nested remote operation.

.

EXIT-VALUES

0: OK:
Result is valid.

1: NOK:
Erroneous parameters.

2: NOK:
Missing an environment element like files or databases.


SEE ALSO

User Manual


AUTHOR

Written and maintained by Arno-Can Uestuensoez:

Maintenance: <<acue_sf1 (a) users sourceforge net>>
Homepage: <http://www.UnifiedSessionsManager.org>
Sourceforge.net: <http://sourceforge.net/projects/ctys>
Berlios.de: <http://ctys.berlios.de>
Commercial: <http://www.i4p.com>




COPYRIGHT

Copyright (C) 2008, 2009, 2010, 2011 Ingenieurbuero Arno-Can Uestuensoez

For BASE package following licenses apply,

This document is part of the DOC package,

For additional information refer to enclosed Releasenotes and License files.