Table of Contents

1 Introduction 2

2 RemoteBox Requirements 4

2.1 Fedora 4

2.2 Mandriva 4

2.3 OpenSUSE 4

2.4 Ubuntu 4

2.5 Mac OS X 4

2.6 NetBSD 5

2.7 FreeBSD 5

2.8 OpenBSD 5

3 Configuring the Server 5

3.1 Setting up the Web Service 5

3.2 Running as a Standard System Service on Linux 6

3.3 Running as a Standard System Service on Solaris 6

3.4 Disabling Authentication to the Web Service 6

4 Using RemoteBox 6

4.1 What's missing? 6

4.2 Launching RemoteBox 7

4.3 Connecting to Server 7

4.3.1 URL 7

4.3.2 Username 7

4.3.3 Password 7

4.4 The Main Window 7

4.5 Remote Display 7

4.6 Creating New Guests 8

4.7 Virtual Media Manager 8

5 FAQ & Troubleshooting 8

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

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

5.1.3 Does RemoteBox run on Windows? 8

5.1.4 Does RemoteBox run on my favourite flavour of “UNIX”? 9

5.1.5 How can I set the display size for the guest? 9

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

5.1.7 Does RemoteBox support VirtualBox OSE? 9

5.1.8 Why is RemoteBox restricted to certain versions of VirtualBox? 9

5.1.9 RemoteBox feels sluggish to use. 9

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

5.1.11 How do I install Guest Additions? 10

6 Licence 10

7 Disclaimer 10

8 Contact 10

1 Introduction

RemoteBox is a graphical (GTK) VirtualBox client, which lets you administer guests or virtual machines which reside on a remote server or even your local machine if desired. You may for example have a root server on the internet, a server at home or a server at work running VirtualBox but want to have the convenience of managing the guests easily from your local machine. The virtual machines run in headless mode which means you don't need an active graphical display on the server but you can still connect and view the displays of the guests. 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). You can also use RemoteBox simply as an 'alternative' interface for managing VirtualBox on your local machine. RemoteBox runs on a variety of operating systems including Linux, *BSD and MacOS X and the server can run any operating system supported by VirtualBox.

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.

2.1 Fedora

Fedora is the 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:

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:

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:

2.4 Ubuntu

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

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) .

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

2.6 NetBSD

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

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

2.7 FreeBSD

2.8 OpenBSD

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

3 Configuring the Server

VirtualBox should be installed on the system acting as the server. You do not need VirtualBox installed on the client system, unless the same machine is both the client and the server. Also note, that the client and server do not have to run the same operating system. RemoteBox for example could be running under Linux whilst connecting to VirtualBox on a server running Windows.

3.1 Setting up the Web Service

Most of the information is available in the VirtualBox manual, however some additional guidelines are provided here.

The web service is not intended to be accessed using a web browser, but by clients that use SOAP over HTTP, such as RemoteBox. The web service needs to be running in order for RemoteBox to communicate with VirtualBox over the network. The vboxwebsrv command is used to start the web service, which should have been installed by default as part of the VirtualBox installation. If this command is not in your path, you will need to change to the directory where it's installed and run it from there. The command vboxwebsrv is usually installed within the same directory as VirtualBox itself.

The web service should be started as the same user whose VirtualBox guests you intend to administer. Starting the web service is as simple as running the command 'vboxwebsrv -t0' on the server. This will start the web service running on port 18083 by default, with timeouts disabled. RemoteBox cannot yet detect that the web service has timed out it's connection, so it's highly recommended that you disable timeouts.

For certain operating systems, the VirtualBox web service is integrated into the standard system services, which means it can be stopped and started in the same fashion as any other service as well as being started automatically on boot up.

3.2 Running as a Standard System Service on Linux

Starting with VirtualBox 3.2.10, an init script for starting and stopping the web service is automatically installed and is probably located in '/etc/init.d/vboxweb-service', depending on your Linux distribution. This can be used instead of manually launching the web service. Before you start the web service, you must edit or create it's configuration file:'/etc/vbox/vbox.cfg'.

The configuration file supports several options but should contain at least the following:

Where <myuser> is the user that you want to start the web service as. Starting, stopping and enabling the automatic start up of services on boot up, varies between Linux distributions so you should consult your distribution's documentation if you are not sure how to do this.

3.3 Running as a Standard System Service on Solaris

On Solaris, the web service is automatically integrated into the SMF (Solaris Management Framework), which can be used instead of manually starting the web service. You should configure the service to start as the user whose guests you want to administer and ensure the service starts up with timeouts disabled. This can be done as follows:

svccfg -s svc:/application/virtualbox/webservice:default setprop config/user=<myuser>

svccfg -s svc:/application/virtualbox/webservice:default setprop config/timeout=0

3.4 Disabling Authentication to the Web Service

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

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

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's native graphical 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, such as:

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:

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 as described earlier.

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 The Main Window

The main window should be familiar to users of VirtualBox. It's worth mentioning however that the status of the guests are not updated in real-time. This is because there is no mechanism available for the web service to notify RemoteBox of status changes in the guests. To explicitly see changes which have occurred outside of RemoteBox (e.g. another process powered on a guest) you can use the Refresh button. The details for a guest are not automatically displayed when selecting a guest. This is intentional as it avoids retrieving large amounts of information from the server, ultimately slowing down the selection of the guest. Instead, the details information for a guest can be displayed by double clicking the guest or by explicitly pressing the 'Details' button.

4.5 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.6 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 RDP client is launched and these should be used where your RDP client expects to see things such as the host-name. For example, the default is:

4.6 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 ideally use a different RDP port, particularly if you plan on running more than one simultaneously. This also allows the 'Remote Display' option to work in RemoteBox. If you're unhappy with the chosen port, or with the RDP server being enabled, these can be changed in the guest's settings but of course you won't be able to access the display from RemoteBox.

4.7 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. 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, viewing the web service logs or the guest logs on the server may provide an additional source of information. Sometimes, restarting the web service may 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 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.4 Does RemoteBox run on my favourite flavour of “UNIX”?

Most likely, however many 'commercial' flavours of UNIX do not ship with the prerequisites for RemoteBox, nor provide a repository 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.5 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:

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

5.1.7 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 goal is to support the OSE version however RemoteBox needs to become a little more mature first.

5.1.8 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.9 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.10 Why are the mouse pointers are out of sync when using Remote Desktop?

To enable mouse synchronisation, guest additions should be installed and running within the Virtual Machine. If there are no guest additions for your operating system, then using a VESA display driver should also synchronise the mouse.

5.1.11 How do I install Guest Additions?

You need to make the VBoxGuestAdditions.iso available in the virtual media manager, just as you would any other CD-ROM image. It's usually installed as part of VirtualBox. Once it's available in the VMM, you can attach it to the CD/DVD drive of the guest and install the Guest Additions.

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 all 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.

%h	The hostname of the server running VirtualBox, that RemoteBox is connected to.
%n	The name of the guest
%o	The operating system of the guest
%p	The port number to use when connecting with RDP
%P	The password used to connect to VirtualBox
%U	The username used to connect to VirtualBox