Raspberry Pi Home Server: Part 5, Remote Desktop

Article Obsolete

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.

Installing X11VNC

Type the following to install the X11VNC package.

sudo apt-get install x11vnc

That’s it, a single apt package, and X11VNC is installed.

Configuring X11VNC

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:

x11vnc -storepasswd

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.

mkdir /home/pi/.config/autostart

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:

nano /home/pi/.config/autostart/x11vnc.desktop

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]
Exec=x11vnc -forever -usepw -display :0 -ultrafilexfer

Close nano, saving your changes (ctrl-x,y,enter), and reboot the Raspberry Pi to force it to pick up on the changes.

sudo reboot

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.

Other users?

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.

Wrapping up

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.

What’s next?

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).

This entry was posted in Computers and Internet, Home Server, Raspberry Pi and tagged . Bookmark the permalink.

42 Responses to Raspberry Pi Home Server: Part 5, Remote Desktop

  1. Pingback: Raspberry Pi Home Server: Index | MelGrubb.ToBlog()

  2. Pingback: Raspberry Pi Home Server: Part 4, Web Administration | MelGrubb.ToBlog()

  3. Rasql says:

    Is there any way that I can see if X11VNC is running, as when I try to connect using UltraVNC I get a failed to connect to server error? Originally I thought my problem might have had something to do with the .config/autostart/x11vnc.desktop file, but have checked both its location and content and it appears correct. Up to now everything has worked like a charm and I have been able to connect using PuTTy and WebMin without any issues, I’m hoping you or someone else can point me in the right direction with this, as I would really like to see this through to the end.

    • Mel Grubb says:

      If you’re trying to connect from anywhere other than the local network, then you’ll need to make sure that your router is forwarding the appropriate ports. If you’re having trouble connecting from the local LAN, then maybe double check the Pi’s own firewall, and make sure you followed the steps from the article, including any restarts it mentions. Unfortunately, you can’t just check that VNC is running like other services. You can see if there’s a VNC process running by typing “ps aux | grep vnc”, though. You might also check the firewall on the computer you’re connecting FROM, just in case it’s being blocked there.

  4. mancony says:

    I’m trying to connect from the LAN, both my computer and the Pi’s firewall are disabled and i’m still not getting through. It seems like there are connections being made on the Pi because X11 keeps going from 5900, to 5901 and so when it prompts for a port to be listened in on. Any ideas?

    • Mel Grubb says:

      It’s hard to say without observing it in person. I know that I personally have a problem where I only seem to be able to connect once per reboot. I mentioned it in the article, but I’ve not had any luck finding a way around it. I’m considering writing instructions for alternative VNC packages and see if that works any better. As for your particular problem, if it’s not the once-per-boot trouble I’ve seen, then I’d have to rebuild up to that step to check whether something has changed in either the compatibility with the current Raspbian, or in the contents of the apt-get installer. The CrashPlan instructions had to be updated recently because of a breaking change in their installer. This is the first report I’ve had of a problem like that, though, so unless a bunch of others start pouring in, I’m going to guess that it’s some small step that got skipped, or something off in one of the configs. Double-check the steps, and see if you can uncover anything. I may rebuild this weekend just to double-check all of the articles with the new Raspbian image.

  5. Having difficulties connecting with the TightVNC viewer. It isn’t allowing access.
    I suspect a port number problem. What is the default port on install? Where is the port number configured?
    Also, your instructions for creating the various directories and files should be done as the ‘pi’ user, or at least using ‘sudo’ (although you do have to be ‘pi’ when you do the ‘startx’ part).

    • Further experimentation led to this additional knowledge, which wasn’t fully clear in this post:
      Once you get everything all set up, you use this process to get the GUI remotely:
      – connect via Putty to the Pi’s terminal, log in
      – enter the ‘startx’ command at the terminal
      – then use the TightVNC Viewer to connect to the IP address or device name at port 5900, such as ‘’ or ‘myraspberry::5900’ . The two colons are required.
      – Now you have the Pi’s GUI visible.
      To exit the GUI:
      – use the ‘Shutdown, Logoff’ command (don’t exit or restart)
      – in the Putty terminal window, do a ‘logoff’ to exit the Putty connection.

      To access remotely (outside your LAN), you will need to enable Port Forwarding on your LAN router. And you will need to know your router’s IP address (which may change on you). And there are security issues with that outside connection, so be careful. Remote access from ‘outside’ is not within the scope of this article, though.

      • Mel Grubb says:

        I’ll try to make the post a little more detailed if I get a chance tomorrow, but those are pretty much the steps from the article. Remote in through SSH, fire up the desktop, connect via VNC, remember to turn the lights off on your way out. Maybe I should go into a little more depth in this area. To be honest, I’ve never really liked it much myself, but since I rarely actually need to see the desktop on the server, it doesn’t really come up much. There were other VNC solutions I found when researching for this article, but X11VNC seemed to go the smoothest for me. Maybe things have changed since I wrote it.

      • Bo Herrmannsen says:

        +1 for this one

        thou i have to type sudo or it will not start

  6. Hi Mel !
    First of all I would like to thank you very much for providing this awesome guide !
    I am however having a small problem with the VNC server.
    After setting the hdmi_force_hotplug=1 and setting hdmi_group and hdmi_mode to match my Samsung tv’s resolution (1080p), I cannot access the desktop over internet anymmore.
    When I run tightvnc, I do get to the authentication screen and can input my password,
    but after that I ‘Failed to send data to socket’ error.
    I tried it from home this morning, and it DID work. Any idea what could be the issue ?

    • Mel Grubb says:

      If it works from home but not remotely, then it almost has to be something with the port forwarding on your router. But you say it stopped working after you changed the resolution. Was it working remotely before? I didn’t go into the port forwarding setup in the article because there are simply too many different brands and types of routers. I was just seeing it up to use locally but headless. portforward.com might be a good place to start.

  7. Thanks for your quick reply.

    Yes, it stopped working after changing resolution. But when I tried to login from work I did get as far as the password dialog, so the forwarding should be okay, as it has always been.

    When I get home I will revert the changes in config.txt and see what happens.
    I agree that it looks like a port forwarding issue, but
    my settings should be okay, because it has worked before.

    Strange thing is, I just tried again, and now I’m not able to get to the password dialog.
    It looks like the PI has powered down (which it has done before this week, very strange).

    • Mel Grubb says:

      Now it starts to sound like the problem I mentioned in the article. I only get one good connection per reboot, but since I only use it for maintenance operations, it hasn’t been an issue for me. It sounds like you’re wanting to use it on a more regular basis, though. I’ll have to look into it this weekend and see if I can solve the one-shot problem.

      • As an alternative I installed XRDP, which runs perfectly out of the box.
        It even autostarts automatically and I can use even use it while the pi is in console mode.

        just a simple:
        sudo apt-get install xrdp
        and a reboot, voila !

        and then portforward port 3389 to the PI’s IP.

      • Mel Grubb says:

        I’ll have to give that a try. I was considering branching some of the articles out in case people have their own favorites they just can’t leave. I was only setting it up for those times when you really need a desktop. In all the time I’ve been running this server, though, I haven’t actually needed the desktop once. In some ways it’s less convenient and powerful, since you can’t “sudo” things easily from the GUI, which you need when editing most config files.

  8. Hmm. I just asked my wife to turn on our pc, and I connected through teamviewer.
    After SSH-ing to the PI, and running startx, it works again. No idea what the problem was.

    However I do have another question regarding VNC. Is it also possible to somehow vnc into the PI when the gui has not been loaded up ?

    • Mel Grubb says:

      Not that I know of, but even if it worked, it would just be a slower version of simply connecting via SSH.

    • Mel Grubb says:

      Sorry. I don’t think I read that question right. No, you couldn’t vnc in without the desktop running. If this is something you expect to do a lot, you could tell the Pi to boot straight to the desktop using raspi-config. Since this series was about building a server, I intended it to be hands off and headless. You can still get to a desktop if you HAVE to, but I haven’t come across a situation where I’ve needed it yet.

  9. Yes, but how would I securly connect to the PI over the internet using SSH.
    I know I could forward port 22, but I wouldn’t like hackers hammering the port.
    I’ve read a lot about it, but it’s a little to technical for me.
    Maybe an idea for a new topic 🙂 !

    • Mel Grubb says:

      It’s more depth than I wanted to go into for my purposes, but that’s one of the things SSH is supposed to be good at. You could also connect to your home network via VPN, as I cover later in the series, and then SSH from “inside” your home network.

  10. Pingback: How to control Raspberry 2 Raspbian desktop remotely in headless mode with X11VNC | Linux Circle

  11. Rick H says:

    Here’s something new that might help others. Sometimes adding a new user to a system will cause the X-Window (startx) screen to display only the ‘trash’ icon, with the menu bar at the top flashing.

    While not sure of the exact reason, I finally found (via the googles) that the new user needs to be added to the ‘video’ and ‘audio’ groups. Use this command, substituting the new username

    sudo usermod -aG video usernamehere
    sudo usermod -ag audio usernamehere

    This needs to be done without ‘startx’ running. But it cleared up the above problem on my system.

    Now I need to figure out why starting Minecrafter in xWindow doesn’t work….(nothing happens, even if I wait a very long time). The googles are not helpful on this subject…

  12. Pingback: Running Raspberry Pi in Headless Mode and Graphical interface | rpiarduinomusings

  13. Paulo Gomes says:

    I followed all the steps, with all the reboots and shutdowns needed.
    All good until this point. When I login and run startx, the last log line states: “modprobe: FATAL: Module g2d_23 not found.”, and when I try VNC I get “…target machine actively refused it.”
    Please advise on what is wrong and how to fix it.

    • Mel Grubb says:

      The “Module g2d_23 not found” message is normal. It says that to everyone. As for the connection error, there’s not quite enough information to go on. It’s not saying that the computer couldn’t be found, or that there’s nothing there, so I assume the IP address or name got resolved correctly, and that there’s not some kind of firewall problem. If you’ve followed all of the steps, it should work at this point. I do know that if you type startx, and then immediately try to connect VNC, sometimes it isn’t quite ready yet, and you’ll get this error. Give it a few seconds to finish setting up and try again. Otherwise, carefully retrace the steps. I just ran through this whole thing two weeks ago from scratch, and the VNC instructions still worked for me. In fact, I just remoted in to that system not five minutes ago.

      • Paulo Gomes says:

        Hi Mel, thanks for answering so quickly. Since I’m not going to need to access the desktop that often, I decided to continue onwards and I’l get back at this once everything else is done.
        Maybe it was just that, me being too rushed in!

  14. Pingback: CrashPi – An off-Site backup for the whole family | MelGrubb.ToBlog()

  15. Jonty W says:

    I’m getting “the target machine actively refused connection” as well. I also got an error when using startx through ssh – I had to use sudo startx. If I use startx on the pi itself then VNC works fine – if I start it through ssh then no luck. Any advice – I presume its got something to do with sudo startx ? I’m using the latest Jessie image.

    • Mel Grubb says:

      Those sound like two very different errors. The first is usually when you’re trying to connect remotely to the computer, but you say you’re getting it WHILE connected through SSH. I’m not sure I’m following you there.

      The second error is really simple. Jessie seems to have changed the rules about WHO is allowed to run startx. Instead of everybody being able to run it, only the user directly at the physical device can. This is an easy fix, though.

      sudo nano /etc/X11/Xwrapper.config

      Change “console” to “anybody”. That should get you back in business.

  16. Steven says:

    Hi. Thank you for this tutorial. It was no small feat for a Rpi newbie. I have a question that I hope you could answer. I’m running x11vnc through ssh to play videos on the Rpi. Unfortunately, the playback is very choppy. My question is how much of a security risk would it be to running x11vnc without ssh?

    I run both computers from the same home network. I don’t transmit personal data such as creditcard no. and banking details during the vnc sessions. Thank you all in advance.

    • Mel Grubb says:

      If both computers are on your own private network, and assuming you have either wired connections our decent wifi security enabled, then I’d say you’re fine.

  17. Tim C. says:

    Hey Mel,

    Very good write up! I found a few other x11vnc guides, but yours was the first to yield immediate results (especially in regards to the auto-start on boot feature).

    Firstly, I’m not running this via SSH, my application requires not being headless. The end goal is to have dual inputs both at my pi and on my VNC client. Essentially creating a TeamView experience. That being sade, the pi seems to be crashing at random times after I connect with my VNC client. Sometimes it will be within 30 seconds of connecting and trying to launch my python program while other times it can be after 5-30 minutes of just idling dragging the mouse around (from either device) for testing. The Rpi’s hdmi monitor drops and I get a default monitor error in regards to the Hz being slightly out of range (eg. 553.5hz/553hz) and then the VNC client locks up. Any attempt at reconnecting (with the HDMI screen still being down) yields the typical “the device port you’re looking for is in use” sort of thing.

    I know it’s hard to say exactly what could be happening without seeing it first hand, but does any of this sound familiar?

    Also, this happens across 2 android devices’ VNC clients and TightVNC on my windows 10 PC.

    • Mel Grubb says:

      I’ve never left the Pi running in “two-headed” mode longer than it took to prove that the remote desktop was working. Going headless is one of the first things I do when building a server. I don’t really have any advice for you there. Maybe I’ll leave one running this way for a while and see what happens. There are other VNC solutions for the Pi that you could look into. TightVncServer comes to mind, although the last time I tried using it, it wasn’t my favorite. Adafruit has a tutorial on it here: https://learn.adafruit.com/adafruit-raspberry-pi-lesson-7-remote-control-with-vnc/installing-vnc

      • Tim C. says:

        Thanks for the prompt reply! As you know, tightvnc doesn’t emulate or forward the x session, it turns out this a deal breaker for our intended application. For the time being it runs just perfectly in a headless scenario (after commenting out the HDMI hot-plug line in /boot/config.txt and generating a crontab task to set the default output to the native resolution of the galaxy tablet on reboot. All in all, this is going to work just fine for the time being.

        Thanks again!

  18. Hamir Mahal says:

    Hello Mel,

    I was watching your course on PluralSight and I’ve been thoroughly enjoying it, but I hit a bit of a roadblock at this step. In the Going Headless module of your Raspberry Pi Home Server course, at the beginning of the SSH Demo, I get an error when typing in “sudo apt-get install x11vnc” into the console. Here’s what the pi responds with,

    “Reading package lists… Done
    Building dependency tree
    Reading state information… Done
    E: Unable to locate package x11vnc”

    Did I do something wrong during installation of Raspbian Jessie? I just installed the OS maybe a week ago and installed all of the updates already. Rebooting doesn’t fix the problem. I also edited the Xwrapper.config file and changed the allowed users from console to anybody, but that didn’t fix the problem. If you could offer any help, I would really appreciate.

    Thank you in advance.


    Hamir Mahal

    • Mel Grubb says:

      That is exactly the error message I would expect if I were to tell apt to install some bogus or misspelled package name. What you’ve quoted above looks exactly right, though. It’s possible that the package has gone missing from the repository, in which case we just have to hope it returns soon. Usually, the most likely thing is that the name of the package is incorrect. Have you made changes to your sources.list file by any chance?

      • Hamir Mahal says:

        I’m pretty sure I left sources.list exactly the same. Here are its contents,

        “deb http://mirrordirector.raspbian.org/raspbian/ jessie main contrib non-free rpi
        # Uncomment line below then ‘apt-get update’ to enable ‘apt-get source’
        #deb-src http://archive.raspbian.org/raspbian/ jessie main contrib non-free rpi”

        There was a discrepancy that I noticed earlier in the Webmin Demo lesson in the Going Headless module, but I don’t know if that has anything to do with the error here. When I’m in the /etc/apt/sources.list.d directory and list the contents of the directory, all I see is raspi.list and webmin.list, whereas I think I’m also supposed to being seeing collabora.list, unless the developers of Raspbian Jessie intentionally removed that file for this version of the OS.

        Actually, I tried copying and pasting the command from my first reply, ““sudo apt-get install x11vnc”, just now and now the install is working properly. I’m not sure what was going on yesterday, but I’m glad to see that the pi is working now.

        I ran into a different error message, “E: IO Error to output – fwrite (28: No space left on device)”, but I’m assuming that can be easily fixed by getting a memory card with a larger capacity. I’m using a Kingston MicroSD adapter with a 4GB Lexar MicroSD inside, but I guess with Raspbian Jessie’s slightly larger OS size and all of the package updates I ran over the 4GB capacity. This shouldn’t be too bad, since a 64 GB Micro SD card goes for around $14 these days, so I think I should be fine.

        Thank you for the help. I appreciate the prompt reply.

      • Mel Grubb says:

        Yeah. Newer Raspbian images take a bit more than 4GB. You can get yourself some space back by using apt-get remove to get rid of some things like LibreOffice, Wolfram, and Scratch if you’re not using it. That’ll buy you some time and space, but a bigger card is a pretty easy fix, and will pay off better in the long run.

  19. Pingback: Raspberry Pi Home Server v2: Remote Desktop | MelGrubb.ToBlog()

  20. oedelinc says:

    Thanks for sharing such beautiful information with us.
    I hope you will share some more info about Remote Desktop Services Remote .
    Web Development and Web Hosting
    company in Los Angeles

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s