Managing A Headless VirtualBox Installation With phpvirtualbox On nginx (Ubuntu 12.04)

Version 1.0
Author: Falko Timme
Follow me on Twitter

phpvirtualbox is a web-based VirtualBox front-end written in PHP that allows you to access and control remote VirtualBox instances. It tries to resemble the VirtualBox GUI as much as possible to make work with it as easy as possible. It is a nice replacement for the VirtualBox GUI if you run VirtualBox in headless servers (like in the tutorial VBoxHeadless - Running Virtual Machines With VirtualBox 4.1 On A Headless Ubuntu 12.04 Server). This tutorial explains how to install phpvirtualbox with nginx on an Ubuntu 12.04 server to manage a locally installed, headless VirtualBox.

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


1 Preliminary Note

I'm assuming that a headless VirtualBox is already installed on the local Ubuntu 12.04 server, e.g. as described in the tutorial VBoxHeadless - Running Virtual Machines With VirtualBox 4.1 On A Headless Ubuntu 12.04 Server.

I'm running all the steps in this tutorial with root privileges, so make sure you're logged in as root:

sudo su 


2 Installing phpvirtualbox

First create a system user called vbox and add it to the vboxusers group:

useradd -m vbox -G vboxusers  

Create a password for the vbox user:

passwd vbox

Create the file /etc/default/virtualbox and put the line VBOXWEB_USER=vbox in it (so that the VirtualBox SOAP API which is called vboxwebsrv runs as the user vbox):

vi /etc/default/virtualbox

Next create the system startup links for vboxwebsrv and start it:

update-rc.d vboxweb-service defaults
/etc/init.d/vboxweb-service start

We need a web server with PHP support to serve phpvirtualbox - I'm using nginx here. Install nginx and PHP5 as follows:

apt-get install nginx php5-common php5-mysql php5-suhosin php5-fpm php-pear wget

Start nginx:

/etc/init.d/nginx start

The virtual hosts are defined in server {} containers. The default vhost is defined in the file /etc/nginx/sites-available/default - let's modify it as follows so that it can server PHP files:

 vi /etc/nginx/sites-available/default
server {
        listen   80; ## listen for ipv4; this line is default and implied
        listen   [::]:80 default ipv6only=on; ## listen for ipv6

        root /usr/share/nginx/www;
        index index.php index.html index.htm;

        # Make site accessible from http://localhost/
        server_name _;

        location / {
                # First attempt to serve request as file, then
                # as directory, then fall back to index.html
                try_files $uri $uri/ /index.html;
                # Uncomment to enable naxsi on this location
                # include /etc/nginx/naxsi.rules

        location /doc/ {
                alias /usr/share/doc/;
                autoindex on;
                deny all;

        # Only for nginx-naxsi : process denied requests
        #location /RequestDenied {
                # For example, return an error code
                #return 418;

        #error_page 404 /404.html;

        # redirect server error pages to the static page /50x.html
        error_page 500 502 503 504 /50x.html;
        location = /50x.html {
                root /usr/share/nginx/www;

        # pass the PHP scripts to FastCGI server listening on
        location ~ \.php$ {
                try_files $uri =404;
                fastcgi_split_path_info ^(.+\.php)(/.+)$;
                fastcgi_index index.php;
                include fastcgi_params;

        # deny access to .htaccess files, if Apache's document root
        # concurs with nginx's one
        location ~ /\.ht {
                deny all;

Uncomment both listen lines to make nginx listen on port 80 IPv4 and IPv6.

server_name _; makes this a default catchall vhost (of course, you can as well specify a hostname here like

I've added index.php to the index line. root /usr/share/nginx/www; means that the document root is the directory /usr/share/nginx/www.

The important part for PHP is the location ~ \.php$ {} stanza. Uncomment it to enable it. Please note that I've added the line try_files $uri =404; to prevent zero-day exploits (see and,88845,page=3). Alternatively, if you don't want to use the try_files $uri =404; line, you can set cgi.fix_pathinfo = 0; in /etc/php5/fpm/php.ini (don't forget to reload PHP-FPM afterwards).

Now save the file and reload nginx:

/etc/init.d/nginx reload

I want to serve phpvirtualbox from the nginx default virtual host with the document root /usr/share/nginx/www (I will install it in /usr/share/nginx/www/phpvirtualbox) - if you have a different document root, you must adjust the following steps:

cd /usr/share/nginx/www

Make sure unzip is installed:

apt-get install unzip

Unzip phpvirtualbox and rename the phpvirtualbox-4.1-8 to phpvirtualbox for ease of use:

mv phpvirtualbox-4.1-8 phpvirtualbox

Next go to the /var/www/phpvirtualbox/ directory...

cd /usr/share/nginx/www/phpvirtualbox/

... and create the file config.php by copying it from config.php-example:

cp config.php-example config.php

Open config.php and fill in the password you created earlier for the vbox system user:

  vi config.php
/* Username / Password for system user that runs VirtualBox */
var $username = 'vbox';
var $password = 'secret';

That's it already - you can now open a browser and access phpvirtualbox as follows:

The default username is admin, the password is admin as well:

This is how phpvirtualbox looks - much like the native VirtualBox GUI:

The first thing you should do is change the admin password. Go to File > Change Password:

Type in the old password and specify a new one:

If you know the native VirtualBox GUI, it's now very easy to use phpvirtualbox. For example, if you want to create a new virtual machine, you have the same wizard as you have in the VirtualBox GUI:

(I'm leaving a few sceenshots out so you don't feel bored...)

Share this page:

5 Comment(s)

Add comment

Please register in our forum first to comment.


By: Waters

Help .. I can't get the above steps to work on Ubuntu 12.10 .... always get a host can't connect error ...



By: Anonymous

If you're only getting sort of a blank grey page with a white stripe at the bottom and two thinner white stripes at the top and errors in nginx error log like
"[error] #0: *# connect() failed (111: Connection refused)"
this might be your issue:
Debian's default install of php5-fpm and nginx.
fastcgi_pass   unix:/var/run/php5-fpm.sock;
Head banging on wall occurred.

By: the beaver

That just made my day. thx for the hint 

By: Jan Faix

I was getting grey page with few frames and error "Resource interpreted as Script but transferred with MIME type text/html" on a Ubuntu 12.04 server.

nginx v1.6.2
php5-fpm v5.3.10
phpvirtualbox v4.3-1

The problem was, my Nginx virtual server configuration file was missing following line:

fastcgi_param   SCRIPT_FILENAME  $document_root$fastcgi_script_name;


--- cut ---
    location ~ \.php$ {
            try_files $uri =404;
            fastcgi_split_path_info ^(.+\.php)(/.+)$;
            fastcgi_index index.php;
            fastcgi_param   SCRIPT_FILENAME  $document_root$fastcgi_script_name;
            include fastcgi_params;
--- cut ---

I found this parameter on page:

By: Iman

Vielen Danke Herr Timme! Besten Grüße aus unserem Lüneburg :)