VBoxHeadless - Running Virtual Machines With VirtualBox 4.0 On A Headless CentOS 5.6 Server

Version 1.0
Author: Falko Timme
Follow me on Twitter

This guide explains how you can run virtual machines with VirtualBox 4.0 on a headless CentOS 5.6 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 a CentOS 5.6 server (host system) with the IP address where I'm logged in as a normal user (user name admin in this example) instead of as root.

If you only have a root account, but no normal user account, create one as follows (user admin, group admin)...

# groupadd admin
# useradd -d /home/admin -m -g admin -s /bin/bash admin

... create a password for the new user...

# passwd admin

... and log in as that user.


2 Installing VirtualBox

To install VirtualBox 4.0 on our CentOS 5.6 server, we need root privileges, therefore we run

$ su

Now we enable the RPMforge repository on our CentOS system as the dkms package (Dynamic Kernel Module Support Framework- this package is needed to build the VirtualBox kernel module) that we are going to install is not available in the official CentOS 5.6 repositories:

# rpm --import http://apt.sw.be/RPM-GPG-KEY.dag.txt

# cd /tmp
# wget http://packages.sw.be/rpmforge-release/rpmforge-release-0.5.2-2.el5.rf.x86_64.rpm
# rpm -ivh rpmforge-release-0.5.2-2.el5.rf.x86_64.rpm

(If the above link doesn't work anymore, you can find the current version of rpmforge-release here: http://packages.sw.be/rpmforge-release/)

Then we install the dependencies for VirtualBox 4.0 as follows:

# yum groupinstall 'Development Tools'
# yum groupinstall 'Development Libraries'
# yum install SDL kernel-devel kernel-headers dkms

With the last command we have installed the kernel headers of our currently used kernel. The headers are located in the /usr/src/kernels/ directory, but it is likely that its directory is not named <kernel_version>-<architecture>, but has a different name so that the Virtualbox kernel module cannot be built later on because the expected kernel headers directory cannot be found. We are going to correct that now:

Check your kernel version...

# uname -r

[[email protected] kernels]# uname -r
[[email protected] kernels]#

... and architecture:

# uname -m

[[email protected] 2.6.18-238.el5]# uname -m
[[email protected] 2.6.18-238.el5]#

This means that there should be a directory called 2.6.18-238.el5-x86_64 in the /usr/src/kernels/ directory. We can check this now:

# cd /usr/src/kernels/
# ls -l

[[email protected] kernels]# ls -l
total 4
drwxr-xr-x 19 root root 4096 May 19 14:26 2.6.18-238.9.1.el5-x86_64
[[email protected] kernels]#

As you see, I have the directory 2.6.18-238.9.1.el5-x86_64, but not 2.6.18-238.el5-x86_64. Therefore we create a symlink called 2.6.18-238.el5-x86_64 that points to 2.6.18-238.9.1.el5-x86_64:

# ln -s 2.6.18-238.9.1.el5-x86_64 `uname -r`-`uname -m`

Next download and register the VirtualBox public rpm key:

# wget -q http://download.virtualbox.org/virtualbox/debian/oracle_vbox.asc
# rpm --import oracle_vbox.asc
# rm -f oracle_vbox.asc

Now we enable the VirtualBox CentOS repository on our system:

# cd /etc/yum.repos.d/
# wget http://download.virtualbox.org/virtualbox/rpm/rhel/virtualbox.repo

We can now simply install VirtualBox 4.0 as follows:

# yum install VirtualBox-4.0

If the installation is successful, the output should end as follows:

Running Transaction
  Installing     : VirtualBox-4.0                        1/1

Creating group 'vboxusers'. VM users must be member of that group!

No precompiled module for this kernel found -- trying to build one. Messages
emitted during module compilation will be logged to /var/log/vbox-install.log.

Stopping VirtualBox kernel modules [  OK  ]
Uninstalling old VirtualBox DKMS kernel modules [  OK  ]
Trying to register the VirtualBox kernel modules using DKMS [  OK  ]
Starting VirtualBox kernel modules [  OK  ]

  VirtualBox-4.0.x86_64 0:4.0.8_71778_rhel5-1

[[email protected] kernels]#

(If the installation fails because the correct kernel headers directory cannot be found, output will end as follows:

Creating group 'vboxusers'. VM users must be member of that group!

No precompiled module for this kernel found -- trying to build one. Messages
emitted during module compilation will be logged to /var/log/vbox-install.log.

Stopping VirtualBox kernel modules [  OK  ]
Uninstalling old VirtualBox DKMS kernel modules [  OK  ]
Trying to register the VirtualBox kernel modules using DKMS
Error! Your kernel headers for kernel 2.6.18-238.el5 cannot be found at
/lib/modules/2.6.18-238.el5/build or /lib/modules/2.6.18-238.el5/source.
  (Failed, trying without DKMS)
Recompiling VirtualBox kernel modules [FAILED]
  (Look at /var/log/vbox-install.log to find out what went wrong)

  VirtualBox-4.0.x86_64 0:4.0.8_71778_rhel5-1

[[email protected] yum.repos.d]#

In this case, try to create the correct kernel symlink (as shown before) and then run

# /etc/init.d/vboxdrv setup

to create the VirtualBox kernel module.)

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

# /usr/sbin/usermod -G vboxusers admin

VirtualBox is now installed and ready to be used.


# exit

to leave the root account and become a normal user (admin) again.


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 11.04 Server VM with 512MB memory and a 10GB hard drive from the Ubuntu 11.04 Server iso image (which I have stored in /home/ubuntu-11.04-server-amd64.iso):

$ VBoxManage createvm --name "Ubuntu 11.04 Server" --register
$ VBoxManage modifyvm "Ubuntu 11.04 Server" --memory 512 --acpi on --boot1 dvd --nic1 bridged --bridgeadapter1 eth0
$ VBoxManage createhd --filename Ubuntu_11_04_Server.vdi --size 10000
$ VBoxManage storagectl "Ubuntu 11.04 Server" --name "IDE Controller" --add ide
$ VBoxManage storageattach "Ubuntu 11.04 Server" --storagectl "IDE Controller" --port 0 --device 0 --type hdd --medium Ubuntu_11_04_Server.vdi
$ VBoxManage storageattach "Ubuntu 11.04 Server" --storagectl "IDE Controller" --port 1 --device 0 --type dvddrive --medium /home/ubuntu-11.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 admin, this is /home/admin/.VirtualBox/Machines - the result should be /home/admin/.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/admin/.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 11.04 Server"

(Replace Ubuntu 11.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 11.04 Server" poweroff

To pause a VM, run

$ VBoxManage controlvm "Ubuntu 11.04 Server" pause

To reset a VM, run

$ VBoxManage controlvm "Ubuntu 11.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: David

If you have a webserver and PHP running then phpvitualbox is a great addition to a headless VirtualBox.


It's an open source, AJAX implementation of the VirtualBox user interface written in PHP. As a modern web interface, it allows you to access and control remote VirtualBox instances. It uses VirtualBox' vboxwebsrv service. I have been using it for a couple of years now and it has all but replaced VMware Server on a remote build and testing machine.


I found that you also need to install the virtualbox extension pack.

once downloaded the pack install with the following  as root:

VBoxManage extpack install <file_name>

also add the following line when creating VM :

BoxManage modifyvm "Virtual_Machine_Name" --vrde on

Hope this helps