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.
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.
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.
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
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.
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.
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
The shutdown procedure is basically the reverse order in which you launched components.
davinci % vncserver -kill :1Where the ":1" is a display value generated by the VNC server and printed to stderr when you launch the VNC server.