.

NAME

ctys-VNC - Virtual Network Console Interface

SYNTAX

   ctys -t VNC -a action[=<suboptions>] ...
   ctys -T VNC -a action[=<suboptions>] ...
   ctys -T ALL -a action[=<suboptions>] ...

DESCRIPTION

This plugin manages VNC sessions to LINUX/UNIX OS. It encapsulates and handles the complete interaction with the local and remote components provided by the VNC variants RealVNC and TightVNC.

SSH based connections are the only one supported. The sessions are generally categorized into two basic configurations, the coallocated client and server component - DISPLAYFORWARDING - and the distributed client and server component - CONNECTIONFORWARDING . In the latter case an intermediary SSH tunnel is created. Therefore a vncserver is started and managed on the target server, whereas a vncviewer could be started on the target host or on any client by "Display Forwarding" or "Connection Forwarding". Another feature offers the intermixed usage of VNC, where the vncviewer is connected to a VM, this is the case e.g. for Xen or VMware-WS.

A particular advance is the introduction of a generic addressing schema based on the <machine-address>. This offers the definition of dynamic LABELs as an alias to an arbitrary session. This LABEL is from than on a fully valid address identifier which could be used within the whole ctys toolset. The management of distributed port numbers as well as e.g. the multiplexing of VNC connections into one SSH tunnel is handled by this module.

Additional information containing use-cases with application examples is available from ctys-uc-VNC.

OPTIONS

-a action[=<suboptions>]

-a CANCEL

  
  CANCEL=(<machine-address>)\{1,n\}
    |ALL
    (
      [FORCE|STACK][,]
      [SELF][,]
      [
        RESET|REBOOT
        |(INIT:<init-state>)
        |(PAUSE|S3)|(SUSPEND|S4)
        |((POWEROFF|S5)[:<timeoutBeforeKillVM>]
      ][,]
    [CLIENT|SERVER|BOTH]
    )
  

<machine-address>

For VNC the following parts of a <machine-address> are applicable: ID|I, LABEL|L. When the VNCviewer/VNCserver is used in the default shared-mode, the address applies to all sharing VNCclients/vncviewer are handled as one logical unit and CANCEL is applied to all at once. The address could be supported with multiple instances.

ALL|BOTH|CLIENT|SERVER

ALL and BOTH kill clients and servers on local machine. Remote clients by CONNECTIONFORWARDING might be exiting when server-loss is detected.

• The SERVER scope is actually for VNC the same as ALL or BOTH, this is due to the default (non-server) behaviour of attached clients, which exit when detecting a server-loss.

• The CLIENT scope just kills all client processes by means of OS, which is simply calling kill on their PID. The server processes remain untouched.

REBOOT|RESET|INIT|SUSPEND

These methods just behave as a "soft-kill" which is a more or less soft shutdown, for VNC only! Application shutdown is not supported. So in this case first all clients are killed, following a call to "vncserver -kill :<id>" for all matched. No additional action is performed in case of a failure.

POWEROFF

These method could be seen as a "hard-kill" which is a trial to "soft-kill" and an immediate following process kill by means of native OS. Thus there might be definetly no difference to a controlled shutdown of VNC managing unprepared applications.

The session(s) are basically just killed, so the caller is resposible for appropriate handling of contained jobs.

-a CREATE

  CREATE=[<machine-address>]
     [REUSE|CONNECT|RECONNECT|RESUME]
     [CONSOLE:<>]
     [(CALLOPTS|C):<callopts>]
     [(XOPTS|X):<xopts>]
     [(SHELL|S):<shell>]
     [(CMD):<cmd>]
     [(VNCDESKIDLIST|VDIL):<list-of-xstartup-custom-ids>]
     [WM:(DTWM|FVWM|FVWM2|GNOME|KDE|TWM|X11|XFCE)]
  

<machine-address>

For VNC the following parts of a <machine-address> are applicable: LABEL|L

When the VNCviewer/VNCserver is used in shared-mode, the address applies to all sharing VNCclients/vncviewers. The LABEL suboption is here mandatory.

BOOTMODE

Not applicable.

CONNECT

Almost the same as \mbox{REUSE}, but no new server will be started if missing.

CONSOLE

Not applicable.

PING

Not applicable.

RECONNECT

Similiar to REUSE, with the difference, that any previous active client will be killed before attaching ONE new client. Therefore in shared mode, when multiple clients could simultaneously share one server, all sharing clients are handled as one logical unit and will be thus killed together. Specific exchange of a single client is not supported.

RESUME

Not applicable.

REUSE

When a server process with matching ID or LABEL is already running it will be used, else a new one will be started. In case of non-shared-mode operations of VNC any running vncviewer will be killed by disconnecting through the VNCserver. This is almost the same behaviour as for RECONNECT. When running in shared-mode, just an additional vncviewer will be attached to the server.

SSHPING

Not applicable.

USER

Not applicable.

VNCDESKIDLIST

A list of custom IDs, which could be preconfigured desktops and/or destop-parts within the $HOME/.vnc/xstartup file of VNC. The list defines parts of a pre-configured desktop to be actually started so it is possible to start specific GUI environments. For an realworld example refer to the installed file, either in the installed package

  ${CTYS_LIBPATH}/ctys-01_10_013/conf/vnc/xstartup

or when actually installed in

  $HOME/.vnc/xstartup.

Various desktops within the VNC session could be pre-configured and utilized call-by-call at runtime.

This option is supported for VNC sessions only, pre-requisite is the execution of the xstartup file, which is by now not performed for KVM, QEMU, XEN and VMW-WS sessions. Currently pre-configured values are:

• demo1
• demo2
• demo3
• demo4
• demo5
  The seperator is the standard seperator character '%'.

VNCBASE

Base port as new offset for port calculations from the DISPLAY number. Standard value is 5900.

VNCPORT

Port to be used literally, required for several VMs with fixed Server-Ports.

WAITC:<delay-after-viewer-call>

Delay after start of vncviewer, internally used as delay before check of PID for JOBDATA. Might not be really required to be varied, but provided for completeness.

WAITS:<delay-before-viewer-call>

Delay for start of vncviewer, required when the execution is too fast for the \mbox{VNCserver} to finish it's init.

The practical application could be the usage within a GROUP and/or MACRO, where for security reasons a password based access to multiple <exec-targets> is provided, e.g. for root accounts within a admin group. With setting of this parameter the initial output of VNCviewer is delayed due to it's own delay, thus a series of password requests occur without beeing poisoned by trace messages of the parallel executed VNCviewer.

WM:<window-manager-enum>

A single window manager to be used for current session. The values are preconfigured for specific distributions and operating systems within the xstartup file of VNC. The provided examples could be customized as required. The appropriate software packages are required to be pre-installed before application. Currently pre-configured values are:

• DTWM
• FVWM
• FVWM2
• GNOME
• KDE
• TWM
• X11
• XFCE

BULK:[0-9]{1,3}

This is a bulk counter for automatic handling of given number of sessions. Mainly used for test purposes. It extends automatically the supported standard <label> with three leading-zero-digits, for each instance. Which could be DEFAULT. The default limiting maximum is set to 20. <bulk> could be used for CREATE only.

-a ENUMERATE

Not applicable.

-a LIST

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

id: The DISPLAY used by the vncviewer and/or vncserver. For the actual display of the server two cases has to be distinguished:

• DISPLAYFORWARDING
  The DISPLAY of vncviewer and vncserver are identical.
• CONNECTIONFORWARDING
  The DISPLAY of vncviewer and vncserver are different, this is due to the intermediate tunnel, which handles the port-forwarfing and an has to do a remapping due to ambiguity within the network scope. The following values are not applicable:

    uuid, mac, tcp
  

  
  
  

SEE ALSO

ctys(1) , ctys-groups(1) , ctys-macros(1) , ctys-plugins(1) , ctys-vhost(1) , ctys-VNC(1) , vncpasswd(1), vncviewer(1), vncserver(1)

For System Tools:
RealVNC: [ http://www.realvnc.com ]
TigerVNC: [ http://www.tigervnc.org ]
TightVNC: [ http://www.tightvnc.com ]

AUTHOR

Written and maintained by Arno-Can Uestuensoez:

COPYRIGHT

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

This is software and documentation from BASE package,

• for software see GPL3 for license conditions,
• for documents see GFDL-1.3 with invariant sections for license conditions.
  The whole document - all sections - is/are defined as invariant.

For additional information refer to enclosed Releasenotes and License files.