Contents

What is VirtualBox?

If you are new to VirtualBox, simply put - it is virtualization software that allows one to run multiple virtual machine instances (guests) on a single physical machine (host).

"VirtualBox is a powerful x86 and AMD64/Intel64 virtualization product for enterprise as well as home use. Not only is VirtualBox an extremely feature rich, high performance product for enterprise customers, it is also the only professional solution that is freely available as Open Source Software under the terms of the GNU General Public License (GPL) version 2."

http://www.virtualbox.org

What is phpVirtualBox?

phpVirtualBox is a web-based front-end to VirtualBox that allows you to control your VirtualBox environment.

Getting started

phpVirtualBox is a PHP application, so like all PHP applications, it needs to be run under a PHP-capable web server. It manages your VirtualBox installation by communicating with VirtualBox's API server (vboxwebsrv - distributed with VirtualBox) over a network connection.

 -----------------------------------------------------
 | Web Server                                        |
 |    phpVirtualBox (config.php contains VirtualBox  |
 |     |              access information)            |
 ------|----------------------------------------------
       |
   Authentication and VirtualBox communication
       |
       |  -----------------------------------------------
       |  | VirtualBox Installation                     |
       |  |                                             |
       '---- vboxwebsrv (running as user X)             |
          |    |                                        |
          |    '--- User X's VirtualBox configuration   |
          |         and virtual machines                |
          |                                             |
          -----------------------------------------------

Since communication is performed over the network, phpVirtualBox and VirtualBox do not HAVE to reside on the same physical machine. Though, in most cases, they do. phpVirtualBox can even control multiple VirtualBox installations running on multiple hosts.

Installing VirtualBox

First you will need to install VirtualBox from http://www.virtualbox.org. Any questions regarding VirtualBox or its installation should be raised at the support forums on the VirtualBox web site.

VirtualBox >= 4.0 - Remote Console Access Note

In order to access a VM's console over RDP (via phpVirtualBox's console tab, or other RDP client) you must install the Oracle VM VirtualBox Extension Pack from: http://www.virtualbox.org/wiki/Downloads

Please refer to VirtualBox's documentation for instructions on installing extension packs.

Setting up VirtualBox

phpVirtualBox requires that vboxwebsrv (a program distributed with VirtualBox) is running on your VirtualBox host. On *nix hosts, this is typically found in /usr/bin. On Windows, it is typically found in C:\Program Files\Oracle\VirtualBox. This program MUST be run as the same user that administers your VirtualBox virtual machines. On Windows and OS X, this simply means the same user that you log into your machine as when you run VirtualBox.

NOTE

If your web server and your VirtualBox installation are on 2 different hosts, you may need to add:

-H IP.ADDRESS.OF.HOST

to the command line of vboxwebsrv. Where IP.ADDRESS.OF.HOST is the IP address of your VirtualBox host, accessible by your web server. If this is not specified, vboxwebsrv will listen on localhost, which is not accessible outside of itself.

VirtualBox 3.x OSE Note

For VirtualBox 3.x OSE users, you must execute the following command:

   VBoxManage setproperty websrvauthlibrary null

This disables authentication for vboxwebsrv. At the moment, this is the only way for an application to communicate with the OSE version of vboxwebsrv. Taking security into consideration, only run vboxwebsrv OSE on a non-public network.

If you are not sure whether or not you are running the OSE version of VirtualBox, you can run:

vboxwebsrv -h

If the first line contains "OSE" (e.g. Oracle VM VirtualBox web service version x.x.x_OSE), you are running the OSE version of VirtualBox.

Linux

Linux users should use the instructions for vboxweb-service found at https://sourceforge.net/p/phpvirtualbox/wiki/vboxweb-service%20Configuration%20in%20Linux/

Solaris

Assuming your VirtualBox installation is run by the user vbox and vboxwebsrv is located in /opt/VirtualBox, you may start vboxwebsrv by running the following command as vbox:

 /opt/VirtualBox/vboxwebsrv -H 127.0.0.1 -b --logfile /dev/null >/dev/null

Solaris users will also have to follow the same instructions outlined in the VirtualBox OSE section above, or vboxwebsrv will fail to authenticate.

Windows

On Windows (assuming your VirtualBox installation is located in C:\Program Files\Oracle\VirtualBox), the following command will start vboxwebsrv:

   "%ProgramFiles%\Oracle\VirtualBox\vboxwebsrv.exe" -H 127.0.0.1 >nul

Note that >nul is needed so that vboxwebsrv does not send its output to the command prompt window. Without it, performance will be severely degraded.

User-contributed documentation on setting up vboxwebsrv.exe to start when your computer boots can be found here.

OS X

In OS X, start Terminal (usually located in Applications -> Utilities) and enter the following commands:

  cd /Applications/VirtualBox.app/Contents/MacOS

  ./vboxwebsrv -H 127.0.0.1 >/dev/null

Running /usr/bin/vboxwebsrv or not running the command from within /Applications/VirtualBox.app/Contents/MacOS seems to crash vboxwebsrv

Installing phpVirtualBox

phpVirtualBox requires a web server with PHP >= 5.1.0 installed in order to run. If you do not already have a PHP-capable web server running, this may help you get started.

Download and Installation

FreeBSD Note

Thanks to Bernhard Fröhlich for his time and effort in creating the FreeBSD port.

To install the port:

cd /usr/ports/www/phpvirtualbox/ && make install clean

To add the package:

pkg_add -r phpvirtualbox

Other OSs

• Download the latest version of phpVirtualBox from the Files tab
• Unzip the downloaded file and copy the resulting files / folders to a folder accessible by your web server

SELinux Considerations

If SELinux is installed and you would like to keep it enabled, you may have to add a rule for vboxwebsrv.

Install semanage (yum install policycoreutils-python) and run the command below:

semanage port -a -t http_port_t -p tcp 18083

This will add the VirtualBox's web service port (18083) to be accessible by a service running in an http context (eg. apache).

Arch Linux Considerations

In Arch Linux, be sure to edit /etc/php/php.ini, and uncomment the following lines:

;extension=json.so
;extension=soap.so

by removing the ';' at the beginning of each. Then restart apache.

Basic configuration

config.php in phpVirtualBox's folder on your web server tells phpVirtualBox how to communicate with your VirtualBox installation. To get started, rename config.php-example to config.php and edit it to reflect your settings. The minimal amount of configuration you will need is to specify the username and password needed, as well as the location of vboxwebsrv.

/* Username / Password for system user that runs VirtualBox */
var $username = 'vbox';
var $password = 'pass';

/* SOAP URL of vboxwebsrv (not phpVirtualBox's URL) */
var $location = 'http://127.0.0.1:18083/';

The username and password must be the username and password of the user that vboxwebsrv is running as. If VirtualBox and phpVirtualBox are on the same physical host, you may leave the $location setting alone. Once this is configured:

• Navigate to the resulting folder in your web browser. Typically http://your.web.server.ip/phpvirtualbox
• Default login is admin / admin. See Authentication in phpVirtualBox for more information on controlling users and passwords within phpVirtualBox.

If you have any trouble, see the Common Errors and Issues wiki page.

Advanced configuration

Other configuration options and settings are well documented in config.php itself. More help can be found at:

• Using External Authentication
• Enabling Custom VM Icons
• Enabling Advanced Settings in phpVirtualBox
• Multiple Server Configuration

Getting Help

Please see the Common Errors and Issues wiki page first!

If your error or issue is not listed, please use the Forums.

Please do not open a Bug report unless it is identified as a bug by a project member.

Upgrading phpVirtualBox

phpVirtualBox can be "upgraded" by copying the downloaded files over your existing phpVirtualBox installation. Choose to overwrite existing files if prompted.

You may wish to create an entirely new folder for a new version of phpVirtualBox and that is fine too.

Upgrading from VirtualBox 3.x to 4.x

If you have upgraded from VirtualBox 3.2.x, you will have to run the following commands on your VirtualBox host as the same user that runs vboxwebsrv:
VBoxManage setproperty vrdeauthlibrary default

    VBoxManage setproperty websrvauthlibrary default

NOTE: On windows, start a command prompt and type:

    cd "%ProgramFiles%\Oracle\VirtualBox"

Before entering the VBoxManage commands.

vboxwebsrv

After upgrading, it is a good idea to stop vboxwebsrv for the time being. If you are using the startup script distributed on this site, you may run the following command:

/etc/init.d/vboxwebsrv stop

If your VirtualBox host is running Linux, please see: http://sourceforge.net/p/phpvirtualbox/wiki/vboxweb-service%20Configuration%20in%20Linux/ for a new-and-improved startup script configuration.

Then, start vboxwebsrv. If you are now using the vboxweb-service script described in the above link, you may run:

/etc/init.d/vboxweb-service start

If you are not, you may start vboxwebsrv using the same method you had been using for VirtualBox 3.x.

Post Upgrade

It is always a good idea to clear your web browser's cache after upgrading.

Translating phpVirtualBox

phpVirtualBox uses VirtualBox's translations for most of its text. This reduces the amount of text one must translate for phpVirtualBox to less than 60 items. As a result, only languages available to VirtualBox may be translated for phpVirtualBox:

• ﺎﻠﻋﺮﺒﻳﺓ ar
• Български (България) bg
• Català ca
• Català (valencià) ca_VA
• Čeština cs
• Dansk da
• Deutsch de
• Ελληνικά el
• Español es
• Euskara eu
• Suomi (Suomi) fi
• Français fr
• Galego (España) gl_ES
• Magyar hu
• Bahasa Indonesia id
• Italiano it
• 日本語 ja
• ខ្មែរ km_KH
• 한국어 ko
• Lietuvių lt
• Nederlands nl
• Polski pl
• Português (Brasil) pt_BR
• Português pt
• Română ro
• Русский ru
• Slovenčina sk
• Српски sr
• Svenska sv
• Türkçe tr
• Українська uk
• 简体中文 (中国) zh_CN
• 正體中文 (臺灣) zh_TW

Languages crossed out above have already been translated for phpVirtualBox.

To translate phpVirtualBox, locate a language XML file in phpVirtualBox's languages folder. For instance, de.xml. The file will have entries that look similar to:

<?xml version="1.0" encoding="utf-8"?>
<language>
    <context>
        <name>phpVirtualBox</name>
        <message>
            <source>Warning: A VirtualBox internal operation is in progress. Closing this window or navigating away from this web page may cause unexpected and undesirable results. Please wait for the operation to complete.</source>
            <translation>Warnung: Interne Aktion läuft. Wenn Sie dieses Fenster schließen oder diese Seite verlassen, kann das zu unerwünschten oder unbeabsichtigten Effekten führen. Bitte warten Sie bis die Aktion abgeschlossen ist.</translation>
        </message>
        <message>
            <source>Operation Canceled</source>
            <translation>Aktion abgebrochen</translation>
        </message>
                 ......

You will see translation messages such as:

    <message>
       <source>Operation Canceled</source>
       <translation>Aktion abgebrochen</translation>
    </message>

Text within the <source> tag is the text that is to be translated. The translated text goes in the <translation> tag. E.g.

<message>
   <source>Operation Canceled</source>
   <translation>Your translation of "Operation Canceled" goes here...</translation>
</message>

Translate the file, then send it to the mailing list. It should appear in the next version of phpVirtualBox.

Character Encoding Note

All translations should use UTF-8 encoding.

• Using Notepad in Windows, you may select UTF-8 encoding in the Save as... dialog.
• Using vi, you may enter the command :set enc=utf-8

Other text editors should have some way to change / set the encoding used.