June, 2010



ctys-VNC - Virtual Network Console Interface


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


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.


-a action[=<suboptions>]


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 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.

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.

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.


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.


Not applicable.

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

Not applicable.

Not applicable.

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.

Not applicable.

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.

Not applicable.

Not applicable.

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
or when actually installed in

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 '%'.

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

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

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.

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.

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
  • KDE
  • TWM
  • X11
  • XFCE

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.

Not applicable.

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:


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 ]


Written and maintained by Arno-Can Uestuensoez:

Maintenance: <<acue_sf1 (a) 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 (C) 2008, 2009, 2010 Ingenieurbuero Arno-Can Uestuensoez

This is software and documentation from BASE package,

For additional information refer to enclosed Releasenotes and License files.