VBoxHeadless - Running Virtual Machines With VirtualBox 3.1 On A Headless Ubuntu 9.10 Server

Version 1.0
Author: Falko Timme
Follow me on Twitter
Last edited 01/25/2010

This guide explains how you can run virtual machines with Sun VirtualBox 3.1 on a headless Ubuntu 9.10 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 9.10 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 3.1 on our Ubuntu 9.10 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 karmic non-free

Then we download Sun's public key...

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

... and update our package database:

sudo aptitude update

Afterwards, we install VirtualBox 3.1 as follows:

sudo aptitude install linux-headers-$(uname -r) build-essential virtualbox-3.1 dkms

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

Creating group 'vboxusers'
Users of VirtualBox must be members of that group. Host network interfaces will be assigned to that group.
<-- Ok

Should the vboxdrv kernel module be compiled now? <-- Yes

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/UserManual.html#vboxmanage.

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

VBoxManage createvm --name "Ubuntu 9.10 Server" --register
VBoxManage modifyvm "Ubuntu 9.10 Server" --memory 256 --acpi on --boot1 dvd --nic1 bridged --bridgeadapter1 eth0
VBoxManage createhd --filename Ubuntu_9_10_Server.vdi --size 10000 --register
VBoxManage storagectl "Ubuntu 9.10 Server" --name "IDE Controller" --add ide
VBoxManage storageattach "Ubuntu 9.10 Server" --storagectl "IDE Controller" --port 0 --device 0 --type hdd --medium Ubuntu_9_10_Server.vdi
VBoxManage storageattach "Ubuntu 9.10 Server" --storagectl "IDE Controller" --port 1 --device 0 --type dvddrive --medium /home/ubuntu-9.10-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 and old one, you can start it with the command:

VBoxHeadless --startvm "Ubuntu 9.10 Server"

(Replace Ubuntu 9.10 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 9.10 Server" poweroff

To pause a VM, run

VBoxManage controlvm "Ubuntu 9.10 Server" pause

To reset a VM, run

VBoxManage controlvm "Ubuntu 9.10 Server" reset

To learn more about VBoxHeadless, take a look at

VBoxHeadless --help

and at http://www.virtualbox.org/manual/UserManual.html#id2515738.

Share this page:

6 Comment(s)

Add comment


From: amldc at: 2010-02-06 22:58:18

I can't install virtualbox 3.1 with karmic repository but it's fine with jauny one (on Ubuntu 9.10 64bit):

deb http://download.virtualbox.org/virtualbox/debian jaunty non-free

From: Anonymous at: 2010-02-03 01:03:47

I recommend a little bit change, from the line:

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

To something like:

"You can copy the virtual hard disk (.vdi file) by using: VBoxManage clonevdi [source] [dest]"

As explained in:

+ http://sendderek.wordpress.com/2007/11/18/how-to-properly-backup-a-virtualbox-machine-vdi/
+ http://ubuntuforums.org/archive/index.php/t-553326.html

Just for less headache for you :)

From: Charley at: 2010-02-04 07:48:39

Wouldn't it be easier to install X and do this graphically, then set Ubuntu not to run X on startup? When you need to make changes, just start x and go into the gui. Otherwise, the gui doesn't run.

From: at: 2010-02-12 18:47:08

Even better: when running Linux as desktop or have a X Window server available: ssh -X to the server and then run the GUI. This way, you don't have to have full X on the server.

From: Fredrik at: 2010-02-03 09:58:44

Thanks for the guide!

 One questions springs to mind: if I have a host running several guests at once, how do I control which of them to connect to via RDP?



From: dahas at: 2010-02-14 19:31:50

Easy just type:

VBoxHeadless --help
VirtualBox Headless Interface 3.1.2
(C) 2008-2009 Sun Microsystems, Inc.
All rights reserved.

Unknown option: --help

   -s, -startvm, --startvm <name|uuid>   Start given VM (required argument)
   -v, -vrdp, --vrdp on|off|config       Enable (default) or disable the VRDP
                                         server or don't change the setting
   -p, -vrdpport, --vrdpport <ports>     Comma-separated list of ports the VRDP
                                         server can bind to. Use a dash between
                                         two port numbers to specify a range
   -a, -vrdpaddress, --vrdpaddress <ip>  Interface IP the VRDP will bind to
   -c, -capture, --capture               Record the VM screen output to a file
   -w, --width                           Frame width when recording
   -h, --height                          Frame height when recording
   -r, --bitrate                         Recording bit rate when recording
   -f, --filename                        File name when recording.  The codec
                                         used will be chosen based on the
                                         file extension


VBoxHeadless --startvm <VM> -p 2222

on windows remote desktop type ip followd by port number like this