VBoxHeadless - Running Virtual Machines With VirtualBox 4.1 On A Headless Ubuntu 12.04 Server

Version 1.0
Author: Falko Timme
Follow me on Twitter

This guide explains how you can run virtual machines with VirtualBox 4.1 on a headless Ubuntu 12.04 server. Normally you use the VirtualBox GUI to manage your virtual machines, but a server does not have a desktop environment. Fortunately, VirtualBox comes with a tool called VBoxHeadless that allows you to connect to the virtual machines over a remote desktop connection, so there's no need for the VirtualBox GUI.

I do not issue any guarantee that this will work for you!


1 Preliminary Note

I have tested this on an Ubuntu 12.04 server (host system) with the IP address where I'm logged in as a normal user (user name administrator in this example) instead of as root.


2 Installing VirtualBox

To install VirtualBox 4.1 on our Ubuntu 12.04 server, we open /etc/apt/sources.list...

sudo vi /etc/apt/sources.list

... and add the following line to it:

deb http://download.virtualbox.org/virtualbox/debian precise contrib

Then we download the VirtualBox public key...

 wget -q http://download.virtualbox.org/virtualbox/debian/oracle_vbox.asc -O- | sudo apt-key add -

... and update our package database:

sudo apt-get update

Afterwards, we install VirtualBox 4.1 as follows:

sudo apt-get install linux-headers-$(uname -r) build-essential virtualbox-4.1 dkms

(The dkms package ensures that the VirtualBox host kernel modules are properly updated if the Linux kernel version changes.)

Starting with version 4.0, VirtualBox has introduced so called "extension packs" and has outsourced some functionality like remote desktop connection support (VRDP) that was part of VirtualBox packages before version 4.0 into these extension packs. Because we need remote desktop connections to control our virtual machines, we need to install the appropriate extension pack now. Go to http://www.virtualbox.org/wiki/Downloads, and you will find a link to the following extension pack:

VirtualBox 4.1.18 Oracle VM VirtualBox Extension Pack
Support for USB 2.0 devices, VirtualBox RDP and PXE boot for Intel cards.

Download and install the extension pack as follows:

cd /tmp
wget http://download.virtualbox.org/virtualbox/4.1.18/Oracle_VM_VirtualBox_Extension_Pack-4.1.18-78361.vbox-extpack
sudo VBoxManage extpack install Oracle_VM_VirtualBox_Extension_Pack-4.1.18-78361.vbox-extpack

(Make sure you grab the latest version from the VirtualBox web site.)

(Make sure you run the last command with sudo - sudo VBoxManage extpack install ... - because otherwise you will get an error like this:

[email protected]:/tmp$ VBoxManage extpack install Oracle_VM_VirtualBox_Extension_Pack-4.1.18-78361.vbox-extpack
Progress state: NS_ERROR_FAILURE
VBoxManage: error: Failed to install "/tmp/Oracle_VM_VirtualBox_Extension_Pack-4.1.18-78361.vbox-extpack": The installer failed with exit code 127: Error creating textual authentication agent: Error opening current controlling terminal for the process (`/dev/tty'): No such device or address
[email protected]:/tmp$


Now we must add the user that will run VirtualBox (administrator in this example) to the vboxusers group:

sudo adduser administrator vboxusers

VirtualBox is now installed and ready to be used.


3 Using VirtualBox On The Command Line

3.1 Creating A VM

To create a VM on the command line, we can use the VBoxManage command. See

VBoxManage --help

for a list of available switches and (highly recommended!) take a look at http://www.virtualbox.org/manual/ch08.html.

I will now create an Ubuntu 12.04 Server VM with 512MB memory and a 10GB hard drive from the Ubuntu 12.04 Server iso image (which I have stored in /home/ubuntu-12.04-server-amd64.iso):

VBoxManage createvm --name "Ubuntu 12.04 Server" --register
VBoxManage modifyvm "Ubuntu 12.04 Server" --memory 512 --acpi on --boot1 dvd --nic1 bridged --bridgeadapter1 eth0
VBoxManage createhd --filename Ubuntu_12_04_Server.vdi --size 10000
VBoxManage storagectl "Ubuntu 12.04 Server" --name "IDE Controller" --add ide
VBoxManage storageattach "Ubuntu 12.04 Server" --storagectl "IDE Controller" --port 0 --device 0 --type hdd --medium Ubuntu_12_04_Server.vdi
VBoxManage storageattach "Ubuntu 12.04 Server" --storagectl "IDE Controller" --port 1 --device 0 --type dvddrive --medium /home/ubuntu-12.04-server-amd64.iso


3.2 Importing An Existing VM

Let's assume you have a VM called examplevm that you want to reuse on this host. On the old host, you should have a directory Machines/examplevm in the VirtualBox directory; Machines/examplevm should contain the examplevm.xml file. Copy the examplevm directory (including the examplevm.xml file) to your new Machines directory (if your user name is administrator, this is /home/administrator/.VirtualBox/Machines - the result should be /home/administrator/.VirtualBox/Machines/examplevm/examplevm.xml).

In addition to that copy the examplevm.vdi file from the old VDI directory to the new one (e.g. /home/administrator/.VirtualBox/VDI/examplevm.vdi).

Afterwards, you must register the imported VM:

VBoxManage registervm Machines/examplevm/examplevm.xml


3.3 Starting A VM With VBoxHeadless

Regardless of if you create a new VM or import an old one, you can start it with the command:

VBoxHeadless --startvm "Ubuntu 12.04 Server"

(Replace Ubuntu 12.04 Server with the name of your VM.)

VBoxHeadless will start the VM and a VRDP (VirtualBox Remote Desktop Protocol) server which allows you to see the VM's output remotely on another machine.

To stop a VM, run

VBoxManage controlvm "Ubuntu 12.04 Server" poweroff

To pause a VM, run

VBoxManage controlvm "Ubuntu 12.04 Server" pause

To reset a VM, run

VBoxManage controlvm "Ubuntu 12.04 Server" reset

To learn more about VBoxHeadless, take a look at

VBoxHeadless --help

and at http://www.virtualbox.org/manual/ch07.html#vboxheadless.

Share this page:

Suggested articles

2 Comment(s)

Add comment


By: Steve

Thanks for this. It worked perfectly for me, using Ubuntu 12.04 Server. Previously I had tried this myself (using the "virtual box" Aptitude package that comes with Ubuntu, and got an old version of VirtualBox without VRDE (VNC only, which has mouse pointer offset issues). This gave me the latest VirtualBox with the extension pack and VRDE. Thank-you so much. -- Steve.

By: Ace Suares

 Great guide!

But it leave the VM open to anyone who connects to your public facing IP on the RDP port.

That's why I added this before I start the machine:

VBoxManage modifyvm "$VM_NAME" --vrdeaddress --vrdeport 23771

(any port wil do)

So now the RDP is only on and no one can enter it.
If the host is remote, then the next thing to do is from you development/office/home machine do:


ssh -N -f -L localhost:23771:localhost:23771 [email protected]
This wil open a port 23771 on YOUR localhost connected to port 23771 on the remote hosts localhost, so to say

After that you can instruct you RDP viewer to connect to and you will have a secure connection with your VM.

By the way, after installing, I do this:

VBoxManage modifyvm "$VM_NAME" --natpf1 "guestssh,tcp,,12222,,22"
VBoxManage modifyvm "$VM_NAME" --boot1 disk

The second line makes the vm boot from disk or else it will always start with the installer !

The first line does portforwarding from the host to the vm's secure shell server (only if you had NAT as network card)

So  after install you can do
ssh -p 12222 [email protected]
where remotehost is the IP address of the host,

but user is the user on the VM.