A new version of this series has been published. Please refer to the new index for updated articles and ordering. This article is kept for historical reference, but should be considered out of date.
Note: This article is part of a series. See the Index for more information.
Self-promotion: I’ve recorded this series as a screencast for Pluralsight:
If you have a Pluralsight subscription, please consider watching it. Thanks!
Update – 2016/10/04
The newest release of Raspbian (the one with the “Pixel” desktop) already has RealVNC built it. I was using x11VNC in this article, and I had good reasons for that, but with RealVNC built directly into the Raspbian image now, there’s no reason to not use it. All you have to do is go to the “Interfaces” tab on the system preferences dialog, and enable VNC.
I was also using UltraVNC as my viewer before, and I’m sure it can be made to work with RealVNC, but it’s much simpler to just download the RealVNC viewer. It’s a portable application, and doesn’t need to be installed. You just download it, point it at your Pi’s address, and you can connect in no time.
Basically, this article is no longer needed. I’m leaving it here for posterity, but there’s no need to do any of this by hand anymore.
Other Updates: Since the Jessie release of Raspbian initially booted straight to the desktop, you won’t need to manually run the desktop once using “startx” just to create the “Desktop” directory. It should already be there.
I have noticed one other configuration change under Jessie that you’ll have to deal with. You’ll need to edit the /etc/X11/Xwrapper.config file and change allowd_users from “console” to “anybody” in order to start the desktop from an SSH session.
Other than that, nothing changes under Jessie.
So far in this series, we’ve set up the Raspberry Pi for remote login via SSH, and for web administration through Webmin. Sometimes, though, you just want to see a desktop, and that’s not easy when the computer you’re trying to see has no monitor, keyboard, or mouse.
You can easily add remote desktop ability to the Raspberry Pi pretty at this point through a program call X11VNC. There are other VNC (Virtual Network Computing) packages out there, but this one has worked pretty painlessly in my experience.
Type the following to install the X11VNC package.
sudo apt-get install x11vnc
That’s it, a single apt package, and X11VNC is installed.
There’s a bit of configuration to be done before your remote desktop will be usable. Firstly, if you haven’t run the desktop while logged in as “pi” already, you’ll want to do that now. You’re about to need a certain folder that gets created automatically by the X desktop when it is first run. So, if you haven’t run the desktop yet, make sure your Raspberry Pi is hooked up to a monitor and go to the desktop by typing the following:
Give the desktop a minute or so to complete whatever startup tasks it has, and then exit the desktop by clicking on the red “power” icon in the lower-right corner, and clicking “Logout”.
You’ll need to establish a password used to secure the remote desktop connection itself. Type the following command to do this:
You will be prompted to assign a VNC password. This doesn’t have to be the same password as your regular password, but you may want to keep the passwords in sync so you’ll have fewer to remember. When prompted whether to store the password, you can just hit enter to accept the default answer of “yes”.
Next, create a folder to hold the X11VNC desktop configuration file.
Note: If you get an error that a folder doesn’t exist, it’s probably because you didn’t run the desktop at least once while logged in as “pi”. See the first configuration step above and try again after having started the desktop at least once.
Create and edit a new desktop configuration file by typing the following:
Copy the following lines into the new file. Without going into too much detail, you are specifying that x11vnc should start running whenever the x desktop is shown.
[Desktop Entry] Encoding=UTF-8 Type=Application Name=X11VNC Exec=x11vnc -forever -usepw -display :0 -ultrafilexfer StartupNotify=false Terminal=false Hidden=false
Close nano, saving your changes (ctrl-x,y,enter), and reboot the Raspberry Pi to force it to pick up on the changes.
To test this out, log back in as “pi”, and start up the desktop by typing “startx” at the command prompt. The desktop should start up the same as it did before.
Open your favorite VNC viewer application. I have used both TightVNC and UltraVNC. Which one you prefer is a personal choice. Connect to the Raspberry Pi by IP address or by name (RPHS), and you should be prompted for the password you created above. Type in the password, and you should be looking at a remote desktop that mirrors what’s currently on your monitor.
The real magic is that you can start the desktop remotely via SSH. This is how you’ll get to a remote desktop once the Raspberry Pi goes “headless” (loses its monitor). There’s a slight hiccup, though. If you unplug the Raspberry Pi from any kind of monitor, it won’t know how to pick a resolution. In fact, it won’t even know if it’s supposed to be using an HDMI monitor, or composite. As a result, you’ll get a uselessly tiny screen when you connect via VNC.
By editing the boot configuration file, we can take the choice of resolution and output off autopilot an tell the Raspberry Pi what resolution to use.
sudo nano /boot/config.txt
Look for the line that says “hdmi_force_hotplug=1”, and uncomment it by removing the pound sign from the beginning of the line. Do the same for the “hdmi_group” and “hdmi_mode” lines. You’ll need to provide values for them, though. You can find a pretty exhaustive list on the eLinux site. Pick something that fits comfortable on your primary computer’s monitor.
Log in via SSH and start up the desktop by typing “startx”. The command prompt will show something like this:
Don’t worry about that “fatal” error. It does that to everybody. It’s not important.
Connect your VNC viewer, and you’re all set to go.
Remember to log out of the desktop when you are done so the server doesn’t waste CPU cycles running a desktop that no-one is looking at. At that point, the command prompt in the SSH window will wake back up, and you can log out of the Raspberry Pi completely.
I’ve sometimes had problems with the remote desktop only working once per reboot. Once I’ve logged out of the desktop, it doesn’t seem to want to connect again until I reboot. I’m not sure why, but if I figure it out, I’ll update this post. For now, I just reboot the pi when the remote desktop doesn’t work. I’m not running a fortune 500 company’s critical infrastructure on the thing, just some simple tasks around the house, so the occasional reboot doesn’t bother me.
If you want to log on to a remote desktop session as a user other than “pi”, you’ll need to repeat the configuration steps (starting the desktop once, creating the autostart file, etc.) while logged in as the user you want to have remote desktop abilities. Make sure to SSH in as the user whose desktop you want to see, and manually start up the desktop in the same way as you did for “pi”.
I have not personally done this, since the only reason I would want to see the remote desktop would be to do administrative tasks, which I always perform as “pi” anyway.
You’ve reached another milestone, and I strongly recommend politely shutting down the Raspberry Pi (sudo shutdown –h now), and taking another backup of the SD card.
That’s it for all the different ways we can remotely connect and administer the server. In the next post, we’ll add a hard drive, and get the Raspberry Pi to boot from it (mostly).