- What is VirtualBox?
- What is phpVirtualBox?
- Getting started
- Getting Help
- Upgrading phpVirtualBox
- Translating phpVirtualBox
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."
What is phpVirtualBox?
phpVirtualBox is a web-based front-end to VirtualBox that allows you to control your VirtualBox environment.
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.
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.
If your web server and your VirtualBox installation are on 2 different hosts, you may need to add:
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:
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 users should use the instructions for vboxweb-service found at vboxweb-service Configuration in Linux
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.
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 Windows 7 2008 + Service.
In OS X, start Terminal (usually located in Applications -> Utilities) and enter the following commands:
./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
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, Web server and PHP Installation may help you get started.
Download and Installation
- Download the latest version of phpVirtualBox here.
- Unzip the downloaded file and copy the resulting files / folders to a folder accessible by your web server.
- For Linux users, the downloaded zip file contains a configuration file named "phpvirtualbox.conf", which can be included in your apache configuration. It suppose that phpvirtualbox is installed in /usr/share/phpvirtualbox.
Note : If you want to test the phpvirtualbox develop branch, you can download it here.
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
Note that, as of December 2017, the FreeBSD port is forked from the release 5.0-5 of phpvirtualbox, waiting for a new upstream release.
Thanks to Sergej Pupykin for his time and effort in maintaining the Arch Linux package in the Community repository.
To install the package:
pacman -S phpvirtualbox
Note that, as of March 2018, the Arch Linux package is based on the github tag 5.2-0.
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).
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. On Windows and OS X, this simply means the same user that you log into your machine as when you run VirtualBox.
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.
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
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.
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:
Before entering the VBoxManage commands.
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:
If your VirtualBox host is running Linux, please see: vboxweb-service Configuration in Linux 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:
If you are not, you may start vboxwebsrv using the same method you had been using for VirtualBox 3.x.
It is always a good idea to clear your web browser's cache after upgrading.
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
- Dansk da
- Ελληνικά el
- Euskara eu
- Suomi (Suomi) fi
- 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
- Slovenčina sk
- Српски sr
- Svenska sv
- Türkçe tr
- Українська uk
简体中文 (中国) zh_CN 正體中文 (臺灣) zh_TW
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.