VNC

Virtual Network Computing (VNC) is a tool which projects a GUI session over the network. If may be useful if you want to use GUI tools remotely when X forwarding performs poorly.

VNC works on a client-server architecture, where a remote system (server) runs the programs and sends the virtual screen output to the local system (client). Here, the local system would be your laptop/desktop, while the server is located on the PHASTA Group Machines.

For On Ramp purposes, you only need to follow the sub sections identified with steps 1 through 3: Start VNC Server, Clients, and Starting a VNC Viewer

VNC on PHASTA Machines

Warning: The VNC password is transmitted in clear text over the network and should not be considered secure

Server-Side Setup for PHASTA Machines

Start VNC Server (Step 1)

portal1 is designated to host VNC sessions.

First connect to jumpgate via ssh in a terminal on your personal machine (If following the On Ramp you should already have this terminal opened). To start a VNC session on portal1 type the following in your jumpgate terminal with a return after each line:

ssh portal1
source /etc/profile.d/vncscript.sh
start_vnc.sh

This will setup the VNC viewer for your session on the PHASTA machine side of things. Read through the output from start_vnc.sh as it contains crucial information and some tips which are elaborated on in this wiki.

IMPORTANT: Make sure to remember the generated password and port number ("You should connect to 59zw on portal1", "Your password is abcd1234ExamplePW") so that you can reuse the session you just started. Hint: take a screenshot of the output of start_vnc.sh and store it somewhere safe.

It is common practice to leave your VNC session running on portal1. Next time you want to access your desktop, just ssh into jumpgate with a tunnel between portal1's VNC port (59**) and some port on your machine. Then use a VNC client to connect to the port on your machine. See the Client (Step 2) section below for an explanation of this process.

Killing a VNC Server

If for some reason you want to end your session and kill your virtual desktop, run

source /etc/profile
stop_vnc.sh

ONLY run this if you want to kill your virtual desktop. Most users will never need to do this as the idea is to create one session and continue to use that one for all future usage.

NOTE this will kill all your VNC sessions.

Changing the VNC Password

While ssh'd into your session on portal1, type the following command in your terminal:

 /opt/tigervnc/bin/vncpasswd

Follow the on screen instructions.

View Only Mode

To share your desktop with another user in view only mode set a view only password by running

 vncpasswd

Have the other user connect in the same way you would but have them set their viewer to be in view only mode and use your view only password. Typically this is done as follows:

 vncviewer -viewonly

Changing the Size (Resolution) of an Existing Session

Note: In most modern VNC clients, this can (possibly should) be done via the locally running client. See your VNC client's documentation for details. The below is kept for posterity

You can usually use the xrandr tool to change the resolution of a running VNC session. First you'll need to know your session's display number (this should be the last digit or two of the port number). For example, if your VNC session is running on port 5902, then your screen number should be :2. For this example, we'll use screen 2.

Once you know your screen number, you can see the list of supported modes as follows:

 xrandr -display :2

Once you pick the one you want (generally the same size or smaller than the native resolution of your client), you can choose it by running a command like

 xrandr -s 1400x1050 -display :2

(this example will set the resolution to 1400 pixels by 1050 pixels)

You'll probably be disconnected at this point, but when you reconnect your screen size should be changed (hopefully without crashing your running programs).

Finding an Existing Session

SSH to portal1 and then run:

 /opt/vnc_script/findsession.sh

Which will return the shortened port number of each of your currently running sessions.

Client-Side Setup for PHASTA Machines

Clients (Step 2)

First you need to have a VNC viewer installed on your personal machine. portal1 uses TurboVNC from the VirtualGL project, available from their website

Other VNC viewers will also work, such as TightVNC and RealVNC. Download and install the one you like best for your personal machine (RealVNC seems to be the go to for Mac users in the group).

The instructions given when you started the session on portal1 (the ones you should have taken a screen shot of in Step 1 above) are OK, but it always tells you to start a session (in a terminal on your mac or linux machine command line) with the ssh -L5905:portal1:59zw jumpgate-phasta.colorado.edu command, where zw will be different for each user. That suggestion is OK if you never plan to connect to anyone else's session, but since we often collaborate by sharing VNC sessions, the better practice we adopt is to use zw in place of the suggested 05 (which just an arbitrary local port on your laptop). For example, when I created a session the last four numbers of the connection were 5923, thus zw for me is 23 and the best practice is to ignore the script suggestion in favor of ssh -L5923:portal1:5923 jumpgate-phasta.colorado.edu

The easiest way to set up the portal from the get-go (after you have created the VNC session on the PHASTA machine side of things and left it open, AKA Step 1 above) is to close out of the terminal on your personal machine, reopen it, and run only this command where zw is your assigned port number:

ssh -L59zw:portal1:59zw USERNAME@jumpgate-phasta.colorado.edu

Windows 8
- Same concept as above... close the terminal that was established with PuTTY. Start a new one using PuTTY and entering the following in the Host Name:
USERNAME@jumpgate-phasta.colorado.edu
Again ensuring connection type is set to SSH.
- Next, look to the panel on the left side of the PuTTY window, find the "Connection -> SSH -> Tunnels" menu option and click on "Tunnels". This will 
open a settings page for the tunnel we are trying to establish. 
- In the "Source Port" field enter 59zw, and in the "Destination" field enter 
portal1:59zw, again replacing zw with your assigned port number. 
- Click the "Add" button. 
- Click on "Open". You now have an established VNC connection with portal1 and it will ask you to enter your (jumpgate) password. 
- Remaining steps are the same as non-Windows 8.

You will then be prompted to enter your password (not the one that was just created for the VNC, but the one that you usually use to connect to jumpgate). After entering your password you will be ready for "Starting a VNC Viewer (Step 3)" in the next section. The reason that you must exit and reopen the command prompt is because you cannot connect to the VNC portal zw if you are already connected to jumpgate or portal1; you must connect to jumpgate and your session zw simultaneously for the VNC portal to work correctly.

Starting a VNC viewer (Step 3)

Whether you followed the Mac or Linux or Windows instructions above, successful completion will have established a tunnel from your laptop to portal1. The last step is to start a VNC viewer (graphical windowing program) that uses this tunnel to display your portal1 session on the screen of your laptop. There are a variety of choices for each platform and they evolve but their operation seems, thankfully, pretty universal.

The most basic input is that they provide a box that says "VNC Server". You will want to type localhost:zw in that box and then apply start (or whatever the particular applications action button is). The VNC Viewer will them prompt you for the password that was generated for this "zw" numbered session (Your version of the generated "abcd1234ExamplePW" from previous steps. Note if you changed that VNC password already, use the one you created).

The zw here will need to be whatever you used for the -L59zw:portal1:59zw part of the tunnel. What the number is actually doing is telling this local VNC viewer on which port you have established a tunnel with the session for which you are starting the VNC viewer. Note it is possible to have several different simultaneous sessions. Each needs its own tunnel (established by repeating the process above with a unique zw) and then a corresponding "new" VNC viewer. In this way we might continue to work in our own session but then take a break to look at a collaborator's session without having to close out the tunnel and viewer pair.

Now that you've connected to the PHASTA machines, it's time to learn a bit mroe about using a UNIX based system (Linux). To continue with the On Ramp click here

Web Based Viewer

If you can't or don't want to install a VNC viewer you can use a Java based one. You will need a JVM and a Java browser plugin. You will also need the port that the start_vnc script assigned you to be free on your local computer

Forward your session through jumpgate as before before, adding a second port, 580n. For example, if the script tells you to

ssh -L5905:portal1:5902 jumpgate-phasta.colorado.edu you should

 ssh -L5902:portal1:5902 -L5802:portal1:5802 jumpgate-phasta.colorado.edu

Then point your browser to http://localhost:5802 and log in with the password specified by the script when prompted. (Replace 2 with the value specified by the script)

OpenGL

portal1 is equipped with a VirtualGL install which will allow you to use OpenGL programs (which do not use pthreads)

Simply wrap your OpenGL program with the vglrun command

 vlgrun glxgears

Our lab has 2 VirtualGL servers you can connect to from portal1. You must connect to one of them for large memory and/or computationally intensive processes. The names of the servers are viz002 and viz003 (viz001 is probably never coming back to life). portal1 doesn't have a particularly fast graphics processor and MUST NOT be used for large memory or computationally intensive process)

 vglconnect -s viz002

or

 vglconnect -s viz003

from this connection you will want to run graphic applications (e.g., SimModeler or ParaView) prefaced by the command vglrun. You can test that you have it setup right with the toy-app glxgears as follows

 vglrun glxgears

Note that VGL uses a number of threads. If you have trouble with vglrun crashing with a message about Thread::Start() make sure you haven't set your stack size too large (remove any ulimit -s or ulimit -n calls from your shell start scripts).

NOTE ALSO: The primary purpose for viz00x is for visualization and for debugging. Production runs should be done elsewhere.

Troubleshooting

If you have used vncserver (It doesn't matter which version) before, you will need to clear your vnc settings for the script to work. You can do this by running rm -rf ~/.vnc

stop_vnc.sh may display some errors; this is normal.

If you have trouble deleting ~/.vnc send an email to Benjamin.A.Matthews@colorado.edu

If any of these commands fail, you may need to source /etc/profile to get the necessary environment variables (this should be fixed soon)

VirtualGL has trouble with some threaded programs. If your OpenGL program exhibits segmentation faults or other issues, this could be the problem. Check back for the solution later.

If the given password is rejected you can run stop_vnc.sh and restart to get a new one. Occasionally the random password generator may generate passwords which VNC doesn't like.

If VirtualGL complains about not being able to get a 24bit FB config either vglconnect to another VirtualGL enabled server or complain to Benjamin.A.Matthews@Colorado.edu

If your VNC connection is very slow, you might want to try changing the compression and encoding options. See your vncviewer's documentation or try this

 vncviewer -encodings tight -quality 6 -compresslevel 6

If you have trouble with text distortion try adding

 -nojpeg

If you're running OSX and see an error about Zlib, try changing your compression settings (maximum quality usually works) or use a different client. RealVNC and certain versions of ChickenOfTheVNC both exhibit this issue. The latest build of TigerVNC should work reliably, as does the Java based TightVNC client.