RemoteBox

Version 0.2

Documentation

1 Introduction

RemoteBox is a tool which lets you administer guests or virtual machines running under VirtualBox on a remote server or local machine. VirtualBox is traditionally a desktop-side virtualisation solution. Whilst it does have tools such as VboxManage which allow a form of remote administration, it is command line based and somewhat cumbersome to use. The goal of RemoteBox is to provide a GUI that should be familiar to VirtualBox users whist allowing them to administer a remote installation of VirtualBox. It does this via the VirtualBox API and SOAP interface which are exposed when running the VirtualBox web service (i.e. vboxwebsrv).

2 RemoteBox Requirements

This section provides an overview of the general requirements of RemoteBox. Additional information specific to your operating system or distribution may be found below.

• Perl – v5.8 or newer is recommended

• gtk2-perl – v1.203 or newer is recommended

• SOAP::Lite perl module – v0.710.10 or newer is recommended.

• An RDP client if you want to connect to the remote display of Guests. I recommend 'rdesktop' if your OS supports it.

• VirtualBox 3.2.x (not OSE version)

  • You DO NOT need VirtualBox installed on the machine running RemoteBox, unless the same machine is also acting as the VirtualBox server.

2.1 Fedora

Fedora is primary testing and development platform for RemoteBox, so in general the requirements of RemoteBox will be closely aligned. Ensure the required RPM packages are installed by using one of the various graphical package managers or from the command line with root privileges by typing:

yum -y install perl-Gtk2 perl-SOAP-Lite perl-libwww-perl rdesktop

2.2 Mandriva

Ensure the required RPM packages are installed, either by using the graphical tool RPMDrake or from the command line with root privileges by typing:

urpmi perl-Gtk2 perl-SOAP-Lite rdesktop

2.3 OpenSUSE

Ensure the required RPM packages are installed, either by using the graphical tool Yast or from the command line with root privileges, by typing:

zypper install perl-Gtk2 perl-SOAP-Lite rdesktop

2.4 Ubuntu

Ensure the required DEB packages are installed, either by using the graphical tool Synaptic package manager or from the command like by typing:

sudo apt-get install libgtk2-perl libsoap-lite-perl rdesktop

2.5 Mac OS X

Mac OS X typically does not come with the vast majority of dependencies for running complex UNIX graphical apps, so usually a 3^rd party repository system is required. MacPorts is known to provide everything you need to get RemoteBox up and running.

Follow the instructions for getting MacPorts setup and installed on your Mac at http://www.macports.org. You should ensure that X11 and the XCode developer suite are installed. If they are not, they can be found on your operating system CD or downloaded from Apple. Once MacPorts is installed, you should install the following ports (note, this will take considerable time as MacPorts downloads and installs many dependencies) .

sudo port install p5-gtk2 p5-soap-lite rdesktop

Next, you will need to modify the very first line in the remotebox.pl file so that it uses the MacPorts version of Perl. Open the file in a text editor and replace the first line as follows:

#!/usr/bin/perl

replace with

#!/opt/local/bin/perl

2.6 NetBSD

Ensure the required packages are installed by using pkg_add, pkgin etc. For example:

pkgin install p5-gtk2 p5-SOAP-Lite rdesktop

Next, you will need to modify the very first line in the remotebox.pl file so that it uses NetBSD's perl. Open the file in a text editor and replace the first line as follows:

#!/usr/bin/perl

replace with

#!/usr/pkg/bin/perl

2.7 FreeBSD

Ensure the required packages are installed by using pkg_add etc. For example:

pkg_add -r p5-Gtk2 p5-SOAP-Lite rdesktop

2.8 OpenBSD

Ensure the following packages are installed by typing the following on the command line:

sudo pkg_add p5-Gtk2 p5-SOAP-Lite rdesktop

3 Setting up the VirtualBox Web Service

3.1 Overview

The web service is required in order for RemoteBox to communicate with VirtualBox via the network. Most of the information is available in the VirtualBox manual, however some additional guidelines are provided here.

Starting the web service is as simple as running the command 'vboxwebsrv -t0', which should already be installed as part of the VirtualBox installation on the server. Depending on your operating system, this will already be in your command path, otherwise it will be in the location in which you installed VirtualBox. This will start up a small web service running on port 18083 by default. The web service is not intended to be accessed using a web browser, but by clients that use the SOAP protocol over http, for example RemoteBox. Once the web service is running, you should be able to connect to it with the RemoteBox client and administer the virtual machines.

3.2 Authentication

It's not strictly required, but for the purposes of this documentation, it is recommended that you start the web service as the same user that you intend to create or administer the virtual machines under. For example, if you had an account on the server called 'joebloggs', then you should start the web service as the same user. In addition, when connecting with the RemoteBox client, you would specify 'joebloggs' as the user and use the corresponding password.

3.2.1 Disabling Authentication

Disabling authentication is not recommended because it will leave your guests vulnerable, however it may be useful for debugging purposes if you are experiencing issues logging in. To disable authentication, execute the following command on the server:

VBoxManage setproperty websrvauthlibrary null

Then, when connecting with RemoteBox, simply leave the username and password options blank.

3.3 Disabling Timeouts

RemoteBox cannot yet detect that the web service has timed out it's connection, which occurs when RemoteBox is left idle for a period time, approximately 5 minutes by default. This tends to manifest itself by things disappearing, for example pressing 'refresh' no longer shows your guests but an empty list. Simply connecting again will allow RemoteBox to continue as normal but this can be a real irritation. However this can be avoided by starting the web service with timeouts disabled using the '-t 0' parameter. For example:

vboxwebsrv -t 0

3.4 Automatic Starting of the Web Service on Boot Up.

This is not required in order to use RemoteBox, but may be convenient, particularly if your server is rebooted regularly. VirtualBox provides no mechanism for doing this by default (except for Solaris), so it is up to the end user to implement for other operating systems.

3.4.1 Linux Simple Start-up

Ideally vboxwebsrv should be integrated as a proper service within your Linux distribution, but as a quick hack you can try the following to have it running on boot up:

Edit the file /etc/rc.d/rc.local and add the following:

/bin/su -c "/usr/bin/vboxwebsrv -b" “<username>”

Where <username> is the account you're using to run VirtualBox. If you're using the root account (you probably shouldn't be), then you don't need to use su and specify a username.

This method will only take care of starting the VirtualBox web service on boot. It will not automatically start guests, nor automatically stop guests.

3.4.2 OpenSolaris Automatic Start-up

Quoting from the VirtualBox SDK:

“On Solaris hosts, the VirtualBox web service daemon is integrated into the SMF frame-

work. You can change the parameters, but don’t have to if the defaults below already

match your needs:

svccfg -s svc:/application/virtualbox/webservice:default setprop config/host=localhost

svccfg -s svc:/application/virtualbox/webservice:default setprop config/port=18083

svccfg -s svc:/application/virtualbox/webservice:default setprop config/user=root

If you made any change, don’t forget to run the following command to put the

changes into effect immediately:

svcadm refresh svc:/application/virtualbox/webservice:default

If you forget the above command then the previous settings will be used when

enabling the service. Check the current property settings with:

svcprop -p config svc:/application/virtualbox/webservice:default

When everything is configured correctly you can start the VirtualBox webservice

with the following command:

svcadm enable svc:/application/virtualbox/webservice:default

For more information about SMF, please refer to the Solaris documentation.”

4 Using RemoteBox

This section describes some basic principles of using RemoteBox, with particular emphasis on where RemoteBox differs from VirtualBox. It does not go into great depth because hopefully using RemoteBox should be reasonably familiar to anybody that has used the VirtualBox interface.

RemoteBox is essentially a web client application. In other words, almost everything you do with RemoteBox, requires communicating over the network to the server, even simply clicking a button. This means that the speed of your network is very important to the responsiveness of RemoteBox itself. It also means that certain aspects of RemoteBox might have slightly unusual behaviour when compared to a standard desktop application.

4.1 What's missing?

RemoteBox is very much work in progress but over time it should improve and become more mature. It already implements a significant proportion of what can be done with the standard VirtualBox GUI, however there are some notable things missing, including:

• USB Device Filters (although controllers can be enabled / disabled)

• Serial Port Management

• Shared Folder Management

• System Snapshot Management (snapshot details can be shown, but not manipulated.)

• Changing removable media whilst the guest is running

4.2 Launching RemoteBox

Unpack the RemoteBox archive, open a command line window and change to the directory where RemoteBox is located. To launch RemoteBox, type:

./remotebox.pl

If RemoteBox does not launch but instead displays some error information, you probably have not fulfilled RemoteBox's requirements. Please see the requirements section of this manual.

The next step is to connect to the server, which should already be running the VirtualBox web service.

4.3 Connecting to Server

In order to administer the virtual machines and guests, you should connect to the server running the VirtualBox web service. If you experience problems logging on, consider disabling authentication to the web server for testing purposes, see Chapter 3. Pressing the “Connect” button will open a dialog window, where the following information should be supplied:

4.3.1 URL

The URL of the server to connect to. This is generally of the form 'http://<server>:<port>'. If the port number is omitted it will assume the default of 18083.

4.3.2 Username

This is usually the username that the VirtualBox web service is running as. If you have authentication disabled, then leave it empty.

4.3.3 Password

This is usually the password of the user that the VirtualBox web service is running as. If you have authentication disabled, then leave it empty.

4.4 Remote Display

RemoteBox makes use of the RDP feature of VirtualBox in order to show the guest's display. To use this option, each guest should be configured with the RDP server enabled. If you intend to run multiple guests simultaneously, then each guest's RDP server should be configured to run on a separate port number. For guests created directly with RemoteBox, the RDP server is automatically enabled and a random port assigned. See section 4.5 Creating New Guests for further information.

By default, RemoteBox uses an RDP client called rdesktop. However, you can configure RemoteBox to use your preferred client, providing it accepts command line parameters. In the preferences window of RemoteBox you should enter the path to your RDP client and include any desired options. RemoteBox uses special values which are substituted when the client is launched and these should be used where your client expects to see things such as the host-name. For example, the default is:

rdesktop %h:%p -T "RemoteBox - %n"

The supported special values are:

4.5 Creating New Guests

Creating guests is similar to VirtualBox except that RemoteBox will automatically enable the RDP server of the guest and pick a random port between 50000 and 65000 for it to run on. The reason being that each guest should use a different RDP port, particularly if you plan on running more than one simultaneously. This also allows the 'Remote Display' option to work without requiring additional input from the user. If you're unhappy with the chosen port, or with the RDP server being enabled, these can be changed in the guest's settings.

4.6 Virtual Media Manager

All media is from the reference point of the server and not the RemoteBox client. When adding new media you must type the full path and it must be accessible by the server. At this point in time there's no mechanism by which a file browser can be implemented. Please also remember that the path follows the conventions of the server's operating system and not that of the client's.

5 FAQ & Troubleshooting

If you experience problems when using RemoteBox, the output from RemoteBox when run from the command line may provide a clue. In addition, the web logs from the VirtualBox web service are also a useful source of information. Restarting the web service may also help.

5.1.1 Does RemoteBox need to be running on the same operating system as VirtualBox?

No, the RemoteBox client and VirtualBox installation can reside on different operating systems. For example, one can install it on Linux but admin a Windows installation of VirtualBox.

5.1.2 Can I use RemoteBox to administer VirtualBox on the same machine?

Yes. Just ensure the VirtualBox web service is running on the same machine and by default connect to http://localhost:18083

5.1.3 I don't see any menu or button icons?

Many distributions of the Gnome desktop these days, come with menu icons disabled by default. Try the following commands, then restart RemoteBox:

gconftool-2 --type bool --set /desktop/gnome/interface/menus_have_icons true

gconftool-2 --set /desktop/gnome/interface/buttons_have_icons --type bool true

5.1.4 Does RemoteBox run on Windows?

Maybe, however I've been unsuccessful so far. I've always hit problems whereby no Perl distribution for Windows provides all the required Perl modules and I'm not inclined enough to begin rolling my own. However, if you find a reasonably straight-forward method, please let me know. I'll also be happy to implement any reasonable changes to RemoteBox to make it run on Windows.

5.1.5 Does RemoteBox run on my favourite flavour of UNIX?

Most likely, however most flavours of UNIX do not have the prerequisites for RemoteBox, nor provide a repository or similar method for the easy installation of them. If you're willing to compile the required software then there's a good chance it'll work. Please do share any successes. OpenSolaris / Solaris falls into this category for example.

5.1.6 How can I set the display size for the guest?

Not really a feature of RemoteBox but it may be added in the future. Ensure the guest has the VirtualBox guest additions installed and on the server run the following as the same user VirtualBox is running as:

VboxManage controlvm <guestname> setvideomodehint <w> <h> <d>

For example:

VBoxManage controlvm MyGuest setvideomodehint 1024 768 32

5.1.7 I connect with RemoteBox but it doesn't show any guests?

Ensure you are using the correct authentication credentials. If in doubt, see the section on disabling authentication to the web service. You may also need to ensure that the web service is running as the user you're connecting as.

5.1.8 Does RemoteBox support VirtualBox OSE?

RemoteBox at this point in time does not officially support the Open Source Edition of VirtualBox. There are several reasons for this, including:

• The API differs slightly

• The OSE version supplied with most distributions tends to lag behind

• Variations in different builds of the OSE version complicates support

• The OSE version only very recently has support for Remote Display (via VNC)

The goal is support the OSE version however RemoteBox needs to become a little more mature first.

5.1.9 Why is RemoteBox restricted to certain versions of VirtualBox?

VirtualBox versions are generally of the form Major.Minor.Micro (e.g. 3.2.2). VirtualBox only guarantees API compatibility between versions if it is the Micro suffix which has changed. For example 3.1.6 is compatible with 3.1.8, but 3.1.8 is not entirely compatible with 3.2.0. In order to reduce code complexity RemoteBox only targets the latest version of the API at the time of release. It will warn you, if you use an incompatible version but you may experience problems if you choose to continue.

5.1.10 RemoteBox feels sluggish to use.

RemoteBox is heavily dependent on the speed and latency of the network between your client and the server. A faster network will result in a more responsive interface. A wireless connection is very usable and with a 100Mbit or above wired connection RemoteBox feels as responsive as the native GUI. Your mileage may vary.

5.1.11 Why are the mouse pointers are out of sync when using Remote Desktop?

Ensure guest additions are installed in the virtual machine, after which the mouse pointers should be synchronised.

6 Licence

RemoteBox itself, is published under the terms of the “GNU GENERAL PUBLIC LICENSE, v2” or any later version. The use of RemoteBox in whole or in part constitutes acceptance of these terms. For further information, please see http://www.gnu.org/licenses/gpl-2.0.html

RemoteBox is shipped with icons that are © Copyright Sun Microsystems and originate from the VirtualBox Open Source Edition, released under the GPL.

7 Disclaimer

For the full details, please see the “NO WARRANTY” section of the GPL. In short, you are entirely and wholly responsible for all consequences resulting from your use, or misuse of RemoteBox. Including but not limited to, loss of or damage to data, hardware, money and any consequences that arise as a result. In other words, if RemoteBox breaks something, you get to keep the pieces! ☺

RemoteBox is not affiliated with Sun Microsystems or Oracle. All trademarks belong to their respective owners.