This is an archival copy of the Visualization Group's web page 1998 to 2017. For current information, please vist our group's new web page.

Remote Desktop on Davinci.nersc.gov with VNC

VNC is a collection of software components that allow you to access a virtual desktop on a remote computer system (see the References section for further reading). VNC has two parts – a client and a server. The server is a program on the machine that provides a virtual desktop (davinci.nersc.gov in this context) and the client is a program run on a workstation that "watches" and interacts with the server (and is run on a remote workstation in this context).

This web page describes how to set up the two components and the network connection between them so that you can access a virtual desktop on davinci.nersc.gov.

Checklist and Table of Contents

Preliminary Information
Setting up your VNC password on davinci
Starting the VNC server on davinci
Setting up the VNC ssh tunnel from your workstation to davinci
Running the VNC viewer on your workstation
Graceful shutdown
Open and Unresolved Issues
Further Reading

Preliminary Information

The VNC software is usually included as part of a "standard" Linux distrubtion. On davinci, you don't need to do any "module load" commands to gain access to any fo the VNC-related commands shown in this document. All VNC-related commands on davinci are located in /usr/X11R6/bin, which should be part of your $path environment variable.

On your remote workstation, you will need the following two software components: (1) ssh, and (2) a VNC viewer. If your workstation runs Linux or MacOS, chances are you already have a VNC viewer installed. If you're not sure, contact your local system administrator for help.

VNC Password on Davinci

The VNC viewer and server perform a rudimentary form of authorization using what is known as a "VNC password." Prior to launching the VNC server, you need to create a VNC password on davinci. To do so, run the "vncpasswd" command as follows:

	davinci %  vncpasswd

You will then be prompted for a password. Note that the password you enter is NOT your NIM password. You need to think of a new password to enter here. It should not be a "valuable" password like your NIM password, etc. You will be asked to type your new VNC password a second time for verification. Then, you will be prompted with a question asking if you'd like to create a "view-only" password. For now, type "n" (for no). The "view-only" password is used to allow others to connect in view-only fashion to your VNC server session.

Launching the VNC Server on Davinci

Before launching the VNC server, be sure that you have first created a VNC password.

To launch the VNC server, type the following command:

	davinci %  vncserver

You will see some output from that command that looks like this:

138 [w/wes] % vncserver

New 'X' desktop is davinci:1

Starting applications specified in /usr/common/homes/w/wes/.vnc/xstartup
Log file is /usr/common/homes/w/wes/.vnc/davinci:1.log

Launching the VNC SSH Tunnel to Davinci

After you have launched the VNC server on davinci, the next thing you need to do is set up an SSH tunnel between your workstation and davinci. (Some general information about SSH tunnels)

Before setting up the SSH tunnel on your workstation, you must determine which port on davinci the VNC server is using. The default port number if 5901, although the server will choose a different port if that one is in use. To determine which port the VNC server on davinci is using, take a look at the server's logfile. The VNC server typically places its logfile in ~/.vnc/davinci:N.log where N is an integer number. When you start the VNC server on davinci, the server tells you the name of the logfile. In the example above, our server writes its log output to /usr/common/homes/wes/.vnc/davinci:1.log. Search through the logfile and look for a line that looks like the following to determine the port number (in this case, the port number is 5901):

	Listening for VNC connections on TCP port 5901

Once you have determined the TCP port the VNC server on davinci is using, then setting up the SSH tunnel is a one-line command (on your workstation) as follows:

	yourWorkstation % ssh -p 22 -C -l yourNERSCuserName -L 5901:davinci.nersc.gov:5901 -N davinci.nersc.gov

What you are doing is forwarding port 5901 on your local machine to port 5901 on davinci in this example. If the VNC server on davinci is listening on a different port, say 5906, then you would need to modify the above command as follows:

	yourWorkstation % ssh -p 22 -C -l yourNERSCuserName -L 5901:davinci.nersc.gov:5906 -N davinci.nersc.gov

You need to run this command on your workstation, not davinci. By setting up the SSH tunnel in this fashion, you can tunnel through firewalls and NAT setups that might be present at your local site. You should replace the string "yourNERSCuserName" with your NERSC user name. After you successfully authenticate, the command above does not return you to a command prompt. If you type "control-C", you will kill the SSH tunnel.

Launching the VNC Viewer on Your Workstation

After you have successfully set up the VNC server on davinci and set up the SSH tunnel between your workstation and davinci you may then launch the VNC viewer on your local workstation. Assuming that the VNC viewer is in your path, type the following command on your local workstation:

	yourWorkstation %  vncviewer localhost::5901
             - OR -
	yourWorkstation %  vncviewer -encodings "tight" -quality 9 localhost::5901
             - OR -
	yourWorkstation %  vncviewer -encodings "hextile" localhost::5901

You will then be prompted to enter your VNC password on davinci, then the viewer will launch. Inside the viewer, you can launch an xterm or other applications as if you were sitting at davinci's console.

This window dump shows the contents of a VNC viewer running on a remote workstation connected to a VNC server running on davinci. In this session, we are running AVS/Express and displaying a volume rendering demonstration.

The difference between these different startup commands is how you specify the pixel encoding in the RFB format. The first option, which contains no pixel encoding specification, will result in the "raw" encoding being used between vncviewer and vncserver. The "raw" encoding option is just that - no compression. Since we specified that the SSH tunnel use its own built-in compression mechanism, this route is viable, even for slow remote connections.

The other two options, -encodings "tight" -quality 9 and -encodings "hextile", use lossy and lossless forms of compression, respectively. The tight encoder will yield the best performance over a remote connection; even by specifying maximum quality (-quality 9), the resulting images in your vncviewer will still show some visible encoding artifacts. Using the "hextile" encoder, which is a lossless compression/encoder, is a better choice. There is some gain from the "double compression" that results when using hextile with the SSH tunnel's compressor.

Troubleshooting VNCviewer and VNCserver Connections

Viewer seems to connect, but you're not prompted for a VNCpassword. We've seen this situation occur when the VNCviewer you're using is not compatible with the VNCserver on davinci. Try a different VNCviewer.

Graceful Shutdown

The shutdown procedure is basically the reverse order in which you launched components.

Cleanly shut down applications running on davinci in your VNC viewer. This step will ensure that licenses are reclaimed, etc. and available to other users.
Shut down the VNC viewer application on your local workstation. You can either type "control-C" from the xterm where you launched the vncviewer, or you can use your mouse and window manager to just close (terminate) the VNC viewer window.
Shut down the SSH tunnel on your local workstation.
Shut down the VNC server on davinci. When you launch the VNC server on davinci, the server is created as a background process. Therefore, to kill the VNC server on davinci, you will need to type a command as follows on davinci:
```
	davinci % vncserver -kill :1
```
Where the ":1" is a display value generated by the VNC server and printed to stderr when you launch the VNC server.

Open and Unresolved Issues

VNC Server Listen port number on davinci. By default, the VNC server listens on port 5901 for incoming connections from the remote viewer. The instructions on this page assume that there is only one VNC server running on davinci at a time — we need to determine what port does the second VNC server try and listen on if there is already a VNC server running on davinci. Since we are tunneling all VNC client-server connections through an SSH tunnel, we need to know what port number the VNC server is listening on prior to building the ssh tunnel. This issue will have ramifications on the listen and forward ports on the SSH tunnel.

VNC server desktop initialization and configuration. This page does not contain any information describing how to customize the settings for the virtual desktop created by the VNC server. The default desktop consists of a version of the "twm" window manager, and an unknown set of applications (xterm, etc.). Chances are, you will be presented with a "naked" desktop where only the twm window manager is running: you will need to fiddle with your mouse to launch an xterm, etc. We need to provide some instructions describing how to customize the desktop.

VNC viewers are buggy. We need to document the typical types of errors one might expect to see.