Using VNC to a Linux system

Document version: 20120326. L.S.Lowe. Part of Guide to the Local System.

This document explains how to set up VNC to show a full desktop session window from a Linux server, on your home PC or laptop, or office desktop PC. If you don't want to see a full desktop session window on your PC, and are content with individual X windows, one for each remote application, then see other documentation. Also for using VNC to a Windows PC or server, see other documentation.

This note covers the situation where your desktop PC or laptop is running Windows, or Linux (see later sections).

VNC is a useful protocol for remote desktop work, and in particular is handy in that the session's state is stored within the vncserver program itself, such that you can reboot your desktop, or move to another desktop (say at home) and take-over the same session in its current state from the original desktop you were using. Apart from this flexibility, this makes VNC useful when the client you are working from, or its network, is unreliable (eg internet cafe or airport lounge): in the event of a break in service it's trivial to reconnect and continue from exactly where you were before.

When you connect to a session with a previous viewer of that session still active, then by default the original viewer is disconnected, but you can if you wish ask for a Shared session so that all clients can interact with the session at the same time.


You have several choices for using VNC, from the PC in front of you (here called just desktop), to a Linux server (here called just server); they are:

Size of the VNC session window

The default size of the session window that is created within your vncserver is 1024x768. This is fine if your desktop screen size is larger than this. But if it's not, then your VNC client window will not be able to show all the session window at once, and will have scroll bars, which can be confusing and irritating. To specify a different size, use the vncserver -geometry option. I've found that for Windows XP with a 1024x768 resolution screen, -geometry 1014x704 is about the maximum, and for a 1280x800 wide-screen laptop, -geometry 1270x736 should be OK, to avoid scroll bars. For a Windows 7 netbook client with a 1024x600 screen, using -geometry 1008x532 is OK. For more details on options, see man vncserver.

Automatic starting of vnc servers

If your friendly server system administrator wishes (perhaps it's yourself!), s/he can set up for the vncserver to be started for you, at system start-up time. If this is in place, then you can omit the steps above which say "start vncserver on the server". This is really only an advantage when you are permitted by firewalls to use the Direct method above, because in that case you don't need the initial ssh or other call, and it's only sensible if you are logging in every day, otherwise you are wasting server resources.
For example, on Red Hat systems, the administrator can set up /etc/sysconfig/vncservers to contain a list of several number:userid items, and the vncserver service needs to be chkconfig'd to start. This also helps eliminate the free-for-all when allocating yourself a display number. For more details, and how to specify options like geometry, your administrator should look at the comments in the /etc/sysconfig/vncservers file.
There is also an option for the underlying Xvnc command to be started on demand on a per-user basis by inetd or xinetd: administrators can look at man Xvnc .

Software you may need to download for a Windows client

The SSH software you can use is PUTTY: download from and I would recommend choosing the Windows Installer version (1.8 MB); this requires you to be in Windows Administrator mode. (If you're always in Administrator mode, then think again). There is alternatively a commercial ssh implementation from not documented here.

You will also need a VNC viewer client for Windows: a good choice is to download from click on the Download button for the VNC Viewer for Windows exe, and download it to somewhere convenient like your Desktop, with a Desktop icon. You don't need to be in Administrator mode.

I advise against downloading the full Server and Viewer product for Windows for the scenario described here, because you do not need the VNC Server on your Windows system, and if it is running its use of network port 5900 may cause an inadvertent clash with your use of SSH tunnels. There's an alternative of TightVNC, not documented here.

Starting VNC forwarding - from a Windows desktop

In order to allow Putty to forward the VNC port to the server, you need to set up the appropriate Tunnels on your desktop. So start Putty first. You may already have a Putty setup for calling your server, saved within Putty saved sessions: if not, then on the initial Putty Session window, enter the server DNS name. Then choose Tunnels from the left hand pane, enter a Source port of 5900, and enter a Destination of localhost:59nn, where nn is a number from 01 to 99, which you have chosen to use on your vncserver command, different to anyone else who regularly uses VNC to this server: you are advised to avoid the low end of that range; also avoid 73, used in this example!

VNC forwarding, step 1

After clicking on Add, you should then see:

VNC forwarding, step 2

Then click on Session in the left hand pane, and Save this session definition, possibly with a new name like serverVNCppnn to distinguish it from sessions with different VNC settings.

To start a session, double-click on this session name in putty, with the usual login dialogue, and a tunnel will be set up so that connections to port 5900 on your local desktop will be forwarded to localhost:59nn which is vnc session nn on the server.

You are now almost ready to start your vncserver, but if this is your first time of use, you may want to be sure that the sort of session that vncserver will start is the sort you want. By default you get a twm window manager with an xterm window running in it. This is a bit spartan for the average user, though is fine if you want a lightweight low-bandwidth session and are going simply to start one or two X-applications from inside or outside that session window. But you may prefer to use a full KDE or Gnome or ICEwm session manager, in which case if you have my vncdesktop command available to you, use it; you only need to run it once ever: you can specify kde or gnome or icewm as an argument to change your default, but otherwise type it in to the server as shown to get your default session:
If you don't want to use that command, then run vncserver once, and then modify your $HOME/.vnc/xstartup file, guided by the comment in that file, and use the switchdesk utility to choose which session manager to use for future sessions.

The vncdesktop (or vncserver) command above will prompt you for a VNC password, if this is your first time of use. Choose this password carefully; make it obscure and different to your normal login password. Don't use one that others on this server might also use; this VNC password is your only protection against accidental or deliberate misuse by other users of this server. (It would be anyone world-wide if you were allowing the Direct method). You can change the password from time to time later using vncpasswd.

You can then type in to the server a vncserver command. You should specify a  -localhost option to prevent Direct VNC connections, unless you're sure the server is firewalled and doesn't allow such connections. For advice on the best -geometry option, see section above. So enter one of these, for example:
       vncserver :nn
vncserver :nn -localhost
vncserver :nn
-geometry 1014x704 -localhost
At this stage you may get a message saying A VNC server is already running as :nn. If there's a chance that the already-running VNC server is your own, you can simply carry on and use that existing session, but if you don't want it, then you can enter vncserver -kill :nn, and try again. This command can do no harm to other users' sessions, but it does kill off your session. Otherwise it's somebody else's session and so your nn was a bad choice: you need to choose another and redefine your tunnel. Low values of nn are more likely to have such port clashes. If possible, communicate with other users to avoid such clashes in future. If the vncserver appears to start correctly, but the processes within the Xvnc window never get started, check your vncserver command line, in particular the :nn operand should come first, otherwise the vncserver setup and the Xvnc process can have a different idea of the port numbers to use; check the $HOME/.vnc/*log file for error messages like Can't open display.

If the vncserver Xvnc process is running correctly on the server, double-click your previously-installed VNCviewer, and enter localhost as the server to call. You will be prompted for your VNC password as known to the server. Then your VNC viewer will be able to see your VNC session on the server. Notice that this is not a login to a session: the session started when you started vncserver, not the viewer, and so when your viewer connects, the session is already there.

If you get the message unable to connect to host: Connection refused then your ssh tunnel has not been setup correctly. If you get The connection closed unexpectedly then possibly you have forgotten to start vncserver on the server, or started it with the wrong port number or on a different server, or the server was rebooted since you started it. If you get connected and see the VNC Authentication window but you get Authentication failure and your password is repeatedly refused, the chances are that you are trying to connect to a session belonging to another user on the server.

If when you connect successfully you get a blank window, touch a shift key to see if the screensaver kicked in. If you get just a root window (usually a black screen), then you probably logged out from your last vncserver session, but this did not terminate the vncserver. Terminate the old session as in the next but one section and start from the top. (Or, if you're a bit of a linux hacker, enter on the server: DISPLAY=localhost:nn  $HOME/.vnc/xstartup &). Consider tweaking your setup or use my vncdesktop command to set things up.

Ceasing viewing and Resuming viewing of a VNC session

To cease viewing a VNC session, simply stop your VNC viewer on your desktop PC or laptop by closing its window (using the X button at top right of the window). The session itself will continue to run within the vnc server, ready for you to connect to the same session in the future.

Sometimes of course this happens involuntarily: your local laptop connection to the network may fail, which may result in your VNC viewer stopping functioning and the putty window going inactive. You have no alternative but to close both those windows. But your VNC session on the vnc server itself will have continued: it's just your view of it that's been broken.

To resume viewing a VNC session, start a fresh putty session as you set it up with the VNC forwarding, then leave that putty session alone for the moment, and restart the VNC viewer on your PC or laptop as before. You should find that you resume exactly where you left off.

Stopping a VNC session

To simply cease viewing a VNC session, see the previous section.

To terminate a VNC session, rather than simply ceasing to view it, logout from the session in the normal way. If you previously used the vncdesktop script (above), then the logout should also terminate the vnc server, which in turn should terminate any vnc viewer(s) using it, so that your vnc viewer window disappears. Otherwise, you will need to enter vncserver -kill :nn on the server to kill the vncserver/Xvnc process.

Turning off a Screen Saver

If you have selected a GUI like KDE or Gnome for your VNC session, then the system will have set up a default screen saver for you. This may run after some small number of minutes of inactivity, and often is set-up to choose a screen-saver at random, many of which are quite cpu-intensive.

Since there is no point in running a screen saver within a VNC session on a remote server, it will be beneficial to all users of the system if you turn this off. In KDE, this is done easily: right-click on the background, choose Configure Desktop, choose Screen Saver (on the left), and then either turn off Start screen saver automatically, or choose Blank Screen from the list.

Starting VNC with forwarding - from a Linux desktop - using via option

If your desktop machine runs Linux, then first make sure you have a ssh command and a vncviewer command installed, perhaps as part of the openssh-clients package and vnc or tigervnc packages respectively.

If you haven't used VNC before,  then type the following on your desktop machine to set the session type of your VNC session to KDE, gnome, or icewm, and to set your VNC password. If the server doesn't have a vncdesktop command, substitute vncpasswd and set up the session type separately by hand:
            mydesktop$ ssh -t userid@my.remote.server  vncdesktop KDE
Then, if your vncserver session is not yet running, issue this command from your desktop machine to start it on your your server:
            mydesktop$ ssh userid@my.remote.server  vncserver :nn

where nn is your chosen VNC display number (up to 99). This command will start the vncserver session and then exit back to your local desktop.  (If you get the error message vncserver: couldn't find "xauth" on your PATH, ask your server's administrator to put a soft-link to the location of xauth into a directory in the default ssh path, or set a PATH in the remote command explicitly. This error is known to happen on RHEL4 / CentOS4 / SL4 systems, and earlier. It shouldn't occur in RHEL5/SL5 Linux onwards as the X utilities are in /usr/bin and not in /usr/bin/X11 or /usr/X11R6/bin).

Then whenever you want to connect to that vncserver session, simply issue from your desktop machine:
            mydesktop$ vncviewer -via userid@my.remote.server :nn

You could reasonably put each of these commands into scripts to save typing in the future. The via option causes vncviewer to use ssh internally to tunnel the VNC session to the remote server, but you don't need to know the details of that (see man vncviewer if you want). Observe that the internal ssh does not need the -X or -Y option, explicitly or defaulted, as X protocol is not used between your desktop and the remote server for the purposes of the VNC session.

Starting VNC with forwarding - from a Linux desktop - without using via option

If your desktop machine runs Linux, then first make sure you have a ssh command and a vncviewer command installed, perhaps as part of the openssh-clients package and vnc or tigervnc packages respectively. Then follow the steps in the previous section to set up your session type and VNC password.

To start your session to your server, your ssh command line will look something like this:
            mydesktop$ ssh -L 5900:localhost:59nn  userid@my.remote.server
where nn is your chosen VNC display number. As when using Windows, if your vncserver session is not yet running, then you can start it using vncserver :nn as described. Then as a new command on your desktop machine (not in your server ssh session), start your VNC viewer:
            mydesktop$ vncviewer localhost

You could reasonably put each of these commands into scripts to save typing in the future. Observe that the ssh command does not need the -X or -Y option, explicitly or defaulted, as X protocol is not used between your desktop and the remote server for the purposes of the VNC session.

Notes on using XFCE4

The user profile does not seem to get run for XFCE.

The following files are checked/run, starting from /usr/bin/startxfce4: $HOME/.xserverrc, /etc/X11/xinit/xserverrc, $HOME/.config/xfce4//xinitrc, $HOME/.xfce4/xinitrc, /bin/sh invoking /etc/xdg/xfce4/xinitrc, /usr/bin/xdg-user-dirs-update, /usr/bin/xdg-user-dirs-update, $HOME/.config/user-dirs.dirs /etc/xdg/xfce4/Xft.xrdb, $HOME/.Xdefaults, $HOME/.config/xfce4/Xft.xrdb /Xft.xrdb (because XFCE4HOME is not set), $HOME/.config/xfce4/Xcursor.xrdb $HOME/.Xresources, $HOME/.Xmodmap,

Miscellaneous Notes

To simplify the description, port 5900 has been used as the desktop local port, which is the default port for the VNCviewer (unless using the via option). If you want or need to use a different port, like 59pp, then of course do so; then you will need to specify localhost:pp when your VNCviewer starts, where pp is a number from 01 and 99. The only likely reason for you to do this would be if your desktop machine was actually a session on a Windows server with a number of VNC-users working on it, or if you yourself are doing several VNCviewer sessions at the same time.

If the system administrator wants to make it less likely that different users of the server get the same default VNC port number, which can result in future clashes, then the following patch to /usr/bin/vncserver may help:
-    foreach $n (1..99) {
+ foreach $ntemp (11..99) { $n = ($ntemp + $>) % 89 + 11; # make n depend on user's uid

Note that the session set up as described in this web page is permitted even if your desktop and server machines are strongly-firewalled: there should be no need to alter the Windows XP firewall, or the Linux server's iptables firewall, for it to work. The Linux server does of course need to accept ssh connections from your desktop, but all other connections are to the internal localhost on desktop or server, which is normally permitted without special action.

If you want to avoid typing in your VNC password when you connect, then for Linux you can add an extra option to the vncviewer command of -passwd $HOME/.vnc/passwd for example, where the file you specify is a copy of the file of that name on the server (or the identical file if client and server share the same file-systems). Make sure the copied file is unreadable by others, like the original, to avoid local compromise of your VNC password.

Please let me know of any other information which might be useful to others.


info counter