Pages Menu
Categories Menu

Posted by on Nov 5, 2011 in Linux | 0 comments

Running Headless VirtualBox over RDP

VirtualBox allows you to use multiple interfaces to control the same virtual machine. You can, for example, start a virtual machine with the VirtualBox Manager window and then stop it from the command line. With VirtualBox’s support for Remote Desktop Protocol (RDP), you can run virtual machines remotely on a headless server and have all the graphical output redirected over the network.

VRDP is a backwards-compatible extension to Microsoft’s Remote Desktop Protocol (RDP). Typically graphics updates and audio are sent from the remote machine to the client, while keyboard and mouse events are sent back. Since VRDP is backwards-compatible to RDP, you can use any standard RDP client to connect to such a remote virtual machine (examples follow below). For this to work, you must specify the IP address of your host system (not of the virtual machine!) as the server address to connect to, as well as the port number that the RDP server is using.

By default, VRDP uses TCP port 3389. You will need to change the default port if you run more than one VRDP server, since the port can only be used by one server at a time; you might also need to change it on Windows hosts since the default port might already be used by the RDP server that is built into Windows itself.

To connect from a Windows client, you can use the Microsoft Terminal Services Connector (mstsc.exe) that ships with Windows. If you use the “Run” dialog, you can type in options directly (of course your IP address and port number may be different):


Configuring VirtualBox for VRDP Support

You will need to have the VirtualBox Extension Pack installed in order to enable support for the Remote Desktop Protocol. VirtualBox extension packages have a .vbox-extpack file name extension. To install an extension, simply double-click on the package file, and the VirtualBox Manager will guide you through the required steps.

From the CLI, do the following. The instructions below are based on version 4.1.6. adjust as necessary.

# To determine if you have the extpack installed:
VBoxManage list extpacks

# To install the extpack.
# Ensure that the extpack matches your installed version of VirtualBox
cd /tmp
VBoxManage extpack install ./Oracle_VM_VirtualBox_Extension_Pack-4.1.6-74713.vbox-extpack

Even when the extension is installed, the VRDP server is disabled by default. It can easily be enabled on a per-VM basis either in the VirtualBox Manager in the “Display” settings (see the section called “Display settings”) or with VBoxManage:

VBoxManage modifyvm "VM name" --vrde on

If you use VBoxHeadless, VRDP support will be automatically enabled since VBoxHeadless has no other means of output.


While any VM started from the VirtualBox Manager is capable of running virtual machines remotely, it is not convenient to have to run the full-fledged GUI if you never want to have VMs displayed locally in the first place. In particular, if you are running server hardware whose only purpose is to host VMs, and all your VMs are supposed to run remotely over VRDP, then it is pointless to have a graphical user interface on the server at all — especially since, on a Linux or Solaris host, the VirtualBox manager comes with dependencies on the Qt and SDL libraries. This is inconvenient if you would rather not have the X Window system on your server at all.

VirtualBox comes with another front-end called VBoxHeadless, which produces no visible output on the host at all, but instead only delivers VRDP data. This front-end has no dependencies on the X Window system on Linux and Solaris hosts.

To start a virtual machine with VBoxHeadless, use the VBoxHeadless command, as follows:

VBoxHeadless --startvm 

There are other methods but this way of starting the VM is preferred because you can see more detailed error messages, especially for early failures before the VM execution is started. If you have trouble with VBoxManage startvm, it can help to start VBoxHeadless directly to diagnose the problem.



  1. Tunnelling a Headless VM Through an SSH Tunnel | - [...] I setup the machine to run as a Headless VM but, because of the security restrictions, I needed to…