updated 2015-12-16: added section on how to start x11vnc in Systemd.
In many situations it is quite handy to have a working graphical environment for testing out websites, or doing other sorts of things in which a GUI is more suitable than the command line. When running in a headless situation, accessing the GUI on a remote host is relatively easy: you can forward X11 (given that bandwidth is not a real issue) or you can use remote-desktop like functionality, like VNC. One of the main issues with the latter is that you need to be logged in prior to opening the connection, quite unhandy if your remote host is actually a virtualised machine on a box somewhere where you cannot easily reach it (let aside being able to connect it to a real display). Instead, I’d like to be able to connect to a remote host and login as I would do normally in a non-virtualised world with a real display. This post walks you through the necessary steps to set up such an environment. I use Debian as my preferred distribution, but it should be trivial to convert the steps to the distribution of your choice.
The basic idea behind running a headless X11 instance this way is that you install a dummy video driver for X11 and let X11VNC use this dummy driver instead. In order to complete the setup we start the X11VNC server once the X11 server is up and running.
Install the additional prerequisites:
jawi@localhost:~ $ sudo apt-get install xserver-xorg-video-dummy x11vnc ...
Once installed, we need to modify the X11 configuration in order to make use of the dummy video driver. If your machine does not yet have a X11 configuration, you can create one by invoking
sudo X -configure and move the
/root/xorg.conf.new file to
/etc/X11/xorg.conf. Edit the file
- change the
Deviceoption in the default screen section from
- add a new dummy device section:
Section "Device" Identifier "Dummy" Driver "dummy" Option "IgnoreEDID" "true" Option "NoDDC" "true" EndSection
If you do not have a graphics card at all, you can use the following template as a starter, which should give you resolutions up to 1280×1024:
Section "Device" Identifier "Dummy" Driver "dummy" VideoRam 256000 Option "IgnoreEDID" "true" Option "NoDDC" "true" EndSection Section "Monitor" Identifier "Monitor" HorizSync 15.0-100.0 VertRefresh 15.0-200.0 EndSection Section "Screen" Identifier "Screen" Monitor "Monitor" Device "Dummy" DefaultDepth 24 SubSection "Display" Depth 24 Modes "1920x1080" "1280x1024" EndSubSection EndSection
Next, we need to ensure that x11vnc is properly configured: we need to create a password file in order to get in:
jawi@localhost:~ $ sudo mkdir /etc/x11vnc jawi@localhost:~ $ sudo x11vnc -storepasswd /etc/x11vnc/passwd Enter VNC password: (enter a password)
Now, depending on the exact version of Debian you’re running, you need to start
x11vnc once the X11 server is started.
If your distribution happens to use Systemd (the recent versions of Debian and Ubuntu do), you can create the following unit file in
[Unit] Description=VNC server for X11 Requires=display-manager.service After=display-manager.service [Service] Type=forking ExecStart=/usr/bin/x11vnc -forever -bg -o /var/log/x11vnc.log -auth guess -rfbauth /etc/x11vnc/passwd -rfbport 5900 -xkb -noxrecord -noxfixes -noxdamage -shared -norc [Install] WantedBy=multi-user.target
Be aware that the
ExecStart line should be a single line!
After creating the unit file, you need to reload your Systemd daemon, enable and start the new service:
jawi@localhost:~ $ sudo systemd daemon-reload jawi@localhost:~ $ sudo systemd enable x11vnc.service jawi@localhost:~ $ sudo systemd start x11vnc.service
For GDM3-based distributions, like Debian Wheezy, you need to edit
/etc/gdm3/Init/Default and add the following line right before the last line stating
/usr/bin/x11vnc -forever -bg \ -o /var/log/x11vnc.log \ -auth guess \ -rfbauth /etc/x11vnc/passwd \ -rfbport 5900 \ -xkb -noxrecord -noxfixes -noxdamage
Note that x11vnc is smart enough to “guess” which form of authentication it should use to connect to X11, making it unnecessary to specify the exact path to the authority file (which is highly dependent on the used display manager).
If your distribution is using upstart, like Ubuntu, you need to create a file
/etc/init/x11vnc.conf with the following contents:
start on login-session-start script /usr/bin/x11vnc -forever -bg \ -o /var/log/x11vnc.log \ -auth guess \ -rfbauth /etc/x11vnc/passwd \ -rfbport 5900 \ -xkb -noxrecord -noxfixes -noxdamage end script
When done, you can reboot your machine and if all is well, you should be able to use your favourite VNC client (e.g. ⌘+K on OSX) to connect to this machine and be presented with a login screen. The VNC client will ask for a password, which is the same one as you defined earlier when creating
If you are running Ubuntu, chances are that you are running light-locker instead of Xscreensaver. In this case, it might occur that once the screen is locked, you no longer can unlock it through your VNC connection. It appears that this is due to the fact that light-locker does some magic with the
DISPLAY environment variable thereby confusing x11vnc. A workaround for this is to replace light-locker with Xscreensaver:
jawi@localhost:~ $ sudo apt-get purge light-locker && sudo apt-get install xscreensaver