VNC Tool

Home Getting Started Fundamentals Applications Feedback & Support Glossary Acknowledgments Table of Contents




GBO Logo

CLEO Launch
CLEO Message
Status Screen
Manager Control
Scan Coordinator
Servo Monitor
Motor Rack
Prime Focus 1 Rcvr
Prime Focus 2 Rcvr
1-2 GHz Receiver
2-3 GHz Receiver
4-6 GHz Receiver
8-10 GHz Receiver
12-18 GHz Receiver
18-26 GHz Receiver
I.F. Manager
L.O. 1 Rack
I.F. Rack
Converter Rack
Analog Filter Rack
Switch Sig. Selector
Spectral Processor
Holography Backend
Weather Station
Site Timing
Device Explorer
Sound Server
Analyze Messages
Save / Load All
CLEO Clock
Sticky Notes
LST Appointment Manager
VNC Tool
TkCon Console


VNCTool helps you create and kill VNC Servers, connect viewers to new or existing servers, and manages the SSH tunneling that's associated with the use of VNC.  

Downloading VNCTool

For remote users that don't have CLEO installed on their local systems, one can download executable versions of this application for Windows and Linux.

Passwords, SSH agents, and Other Required Software

VNCTool  woks best if you are also using an ssh agent to manage your login.  Without an agent, you will need to supply a password.  For the Windows version you only need to enter your password on the main application screen.  For Linux, you will be asked multiple times for your password -- these requests will appear in the terminal that you used to start the application and can be easily missed.

The Windows version of VNCTool comes with all the software you need.  It includes a VNC Viewer and a SSH tunneling application called "plink" (a version of Putty that is designed for use within scripting languages).   Linux users should have a version of SSH installed and install for themselves some flavor of VNC Viewer.

Steps Performed

The application facilitates the starting of a remote VNC server directly or through an intermediary computer, creating an SSH tunnel to the server, starting a local viewer, and automatically terminating the server, and closing the tunnel, when you are done.  Each of these steps are presented as options which allows, for example, one to reconnect to an existing server.  If you have the VNC password for another user's server, you and the other person can even connect to the same server simultaneously.  The user is also presented with various options for the specifics of what happens.

VNCTool  also helps you manage servers.  It will list all of your running servers and allow you to manually kill a server.  It even helps you debug some SSH identification issues.

The Application

The application screen should look something like that shown below if you run it from Windows.  The Linux and Window versions are identical except Linux does not have a field for an optional password nor a widget for specifying the path to Plink.  If you would like to know what a widget is for, just hover your mouse over the widget and a 'balloon' help window will appear that will give you some details.

How to Use

Step 1:

You need to fill out the fields in the top, "Step 1"  section of the application:

  • Remote Host : The name of the Green Bank computer you should log into.  If you are working from within the Green Bank network, this can be a computer on either the general Green Bank network or the GBT network.  If you are working from outside of the Green Bank network, you must supply the name of a computer on the Green Bank, not GBT network.  The default computer name is

  • Server (Via) Host: This is an option that handles the case where you are working from a non Green Bank computer but you need to run the VNC server on a computer on the GBT network.  

    • You would use "Remote Host" to specify a computer on the Green Bank network - default

    • You would us "Server" to specify the computer on the GBT network.  

    If you don't specify a Server (Via) Host, then the software assumes the server will be run on the Remote Host.

    Using Server (Via) Host  is optional since all of this functionality can be recreated by specifying a "Remote Host" on the Green Bank network, starting the server and client, and SSH-ing from that server into a GBT computer.  This might be simpler and more reliable than using a Server (Via) Host.

  • Account: Your Green Bank account.

  • Password: An option for the Windows version of the application.  This is your password for your GBT account, which might be different from your VNC password.

Step 2:

In the middle section of the application, one specifies which steps are to be run in the creation of a VNC session, paths to the various VNC applications, a VNC display number, and your local port number.  The various widgets will become active and inactive as you make various choices of what steps you want to run.

The four buttons on the left side of the applications allow one to choose which steps the application should run.  By default, all four options are selected.

  • Start Server: If a server is NOT running but you would like to create one, select this option.

  • Open SSH Port: Normally you would select this option to create an SSH tunnel to the server.  However, if you have started a server beforehand, opened a tunnel, disconnected from the server, left the tunnel running, but want to reconnect to it, you should not select this option.  Note that tunnels remain open if you do not use the Auto Kill Server option. 

  • Start Local Viewer: Normally, you would select this option.  If, for example, you wanted to start a server for later use, and don't want to immediately bring up a viewer, then you should not select this option.

  • Auto Kill Server: If selected, whenever you terminate your viewer, the application will kill the remote server and close the SSH tunnel.  You should not select this option if you plan on reusing the server and the SSH tunnel.  This option is enabled only if you have selected to start a server and a viewer.

The widgets to the right side of the application are parameters, some optional, for the various steps in a VNC session.  The items in yellow are advanced features that most people will never need to modify.

  • Local Plink Path: Only available if running the application from Windows.  It specifies the path to your PLINK application.  Usually  the default location will work.  If not, use the "..." button to browse for the application.  Or, type in the path if you already know it.  Even though this is Windows, use "/" as the separator between folders.

  • Remote Server Application:  The path on the remote (server) computer where one will find the VNC server application.  In most installations, the default path of /usr/bin/vncserver should work. This option is enabled only if you have selected to start a server.

  • Geometry: The size, in pixels, for the remote server.  The default is 92% of the height and width of your local computer's screen.  This option is enabled only if you have selected to start a server.

  • VNC Display: If you have selected to start a server, the widget will be disabled and the display number will be provided to you by the server.  If you have not selected to start a server, meaning you want to connect to an existing server, you should enter the display number of the server you want to connect to.  If you don't know the display number of an existing server, you would use the List Existing Server button to retrieve a list of running servers. 

  • Base Port #: This widget is enabled only when you have selected to open a SSH port.   The application will create an SSH tunnel from the Base Port # specified on the application to port 5900 plus the VNC Display number of the server.  For example, for a VNC Display of 3, the Unix command would include something like:  ssh -L  Most users should, never need to adjust the local Base Port # for their SSH tunnel.  However, there will be times when some other VNC user on your local computer, or a pre-existing VNC tunnel to a different server, will already have used your local port of 5900.  If you cannot connect and receive messages that a tunnel could not be created, trying changing the Base Port #.  I recommend using a number in the 5900's so that you won't stumble into a closed port on some router or firewall somewhere.  It may take a few tries before you can find an unused local port number.  

  • Local VNC Viewer Path: If you have selected to Start Local Viewer, this widget specifies the path to where you have placed your local VNC viewer.  Use the "..." button to browse for the application.  Or, type in the path if you already know it.  Even if you are using Windows, use "/" as the separator between folders.


What START does

Once you have selected your options, you should press the START button.  Except for your password, the application stores all of the options you have specified into a .cleoVNC file in your home directory when you hit the START button.  

A log window should appear that will show you the various PLINK or SSH commands it is executing and all of the responses the application is receiving from the remote computers.  The log will also show you the results of the application's own analysis, like a list of pre-existing servers.  If something goes wrong, the log window should help you determine the cause of the problem and maybe a solution.  Or, at least provide you with the information you need to properly report a bug.

Start performs the following:

  • If Start Server is selected (e.g.,, and a Server (Via) Host is not specified, the application performs the equivalent of:

    ssh -X -C /usr/bin/vncserver -geometry 1177x942

    or, if a Server (Via) Host is specified (e.g.,, the application does an embedded SSH with:

    ssh -X -C ssh -X -C 
    	/usr/bin/vncserver -geometry 1177x942

    The application then determines the display number from the results returned by the remote computer.  In our example, it returned a display number of :3.

  • If Open SSH Port is selected, and continuing with our example, the application performs the equivalent of:

    ssh -X -C -L

    or, if a Server (Via) Host is specified:

    ssh -X -C -L
  • If Start Local Viewer is specified, the application specified in the Local VNC Viewer Path widget is started.

  • If Auto Kill Server is specified, the application waits until the local viewer terminates.  Continuing our example, after you exit the viewer, or if the viewer fails to come up,  the application executes either:

    ssh -X -C /usr/bin/vncserver -kill :3

    or, if a Server (Via) Host is specified:

    ssh -X -C ssh -X -C 
    	/usr/bin/vncserver -kill :3

(Note:  The exact commands VNCTool executes will be different than those given above and are presented in the log window.  The above commands are for illustration and educational purposes only.)

Other Tools

There are a few other helpful commands VNCTool provides:

  • List Existing Servers: Retrieves a list of all servers you may be running from the account you specified.  Essentially, ssh's into the specified remote computer, does an ls on your ~/.vnc directory and finds files that have .pid extensions. 

  • Manually Kill Pre-Existing Servers: Will kill the VNC server on the specified display on the machine you specified in step one.  A useful tool if, for example, you didn't specify Auto Kill Server and now want to kill a server that server. 

  • Debug Plink/SSH: Try this tool if you are having troubles connecting to the remote computer.  Possible problems can stem from thinks like the remote and local computers not ttrusting each other:  SSH and the window's equivalent Plink will not complete connections to computers that you have not authorized.  This button will help you resolve SSH identifications and check that the other, more complicated SSH commands VNCTool uses will have a chance to succeed.

  • Reset Defaults: Resets the applications options to 'default' values

To Do's

Here's the current wish list for VNCTool:

  • Add an option where the user can specify the color depth the server should use.  This might help users with slow internet connections.

  • List and/or kill all existing SSH tunnel.  Currently, if you don't specify Auto Kill Server, any tunnels you create will exist until you log off.  These tunnels might force you to use a non-default value for Base Port #.



Copyright 2000 Associated Universities, Inc. Washington D.C., USA
Modified: 21 July, 2005 by Ronald J. Maddalena