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."
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 vboxweb-service Configuration in Linux
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
Using Windows Native Installation
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.
Using Windows Services for Linux (WSL)
**As yet currently untested**
See issue #293 for current discussion.
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, 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.
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
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.
ArchLinux Note
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.
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).
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. 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.
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
FAQs
Why does the Flash console no longer work?
Because most (all?) web browsers decided that:
- Macromedia (Adobe) Flash was very old, and a security risk, and removed support for it (and rightly so, as it's been replaced with a very useful HTML5 element "canvas").
- web applications shouldn't be using ports other than 80 and 443 (The RDP protocol that flash used is TCP port 3389).
Can't the project just use an HTML5 web canvas instead of Flash?
No, because the problem isn't just about the front-end, it's about maintaining a connection between your browser and the RDP server. Since port 3389 is also blocked, the only solution to this is to provide a relay through port 443 or 80, both of which are already in use.
Why not just use RDP proxy websockets like Proxmox or Apache Guacamole?
Because that requires a long-running server-side process which is not PHP and won't work unless you have root access to your server. (At which point I'd recommend Guacamole or Proxmox anyway as they're both great products.) Not being PHP puts it outside the scope of PHPVirtualBox.
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: 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:
/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 plPortuguê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.