If you have not done so already, you may wish to read the section About RemoteBox first.

This section describes some basic principles of using RemoteBox, with emphasis on where RemoteBox differs significantly from VirtualBox. It does not go into great detail because using RemoteBox should be familiar to anyone who has used VirtualBox. VirtualBox's own manual is quite extensive and largely applicable to RemoteBox, so you should consider consulting that where appropriate also. RemoteBox makes heavy use of tool-tips to describe the interface and it's options, so you're highly encouraged to make use of them.

RemoteBox is a client application which frequently communicates with the server. Almost every action instigates a conversation with the server. If your network is poorly configured, unreliable or slow, then RemoteBox will not perform as it should. When launching RemoteBox for the first time, it's recommended that you configure and set the preferences to your needs.

Menu:File → Connection Profiles

You can define connection parameters to any number of VirtualBox servers so that can be selected at connection time, rather than typing in the connection parameters manually each time. You can also mark a specific profile to Auto-Connect on Start which means RemoteBox will attempt to automatically connect using this profile when it's launched.

Menu: File → RemoteBox Preferences

These preferences are specific to the RemoteBox client and should not be confused with VirtualBox's preferences.

Tab: General → Default Stop Action

This defines what action RemoteBox takes when the Stop button is pressed on the main toolbar. Whatever default you choose, all other options are still available in the drop-down menu next to the Stop button. You can of course shutdown the guest from within the OS as you normally would.

• Instant Power Off: This will instantly stop the guest without making any attempt to shut it down cleanly. This is equivalent to switching off the power on a real machine.
• ACPI Shutdown: An ACPI request is sent to the guest to power it off cleanly. Note, the actual behaviour here is entirely OS dependent.
• Save Guest State: Saves the execution state of the guest, which will be restored whhen the guest is started again.

Tab: General → Automatically Add Guest Additions to VMM

If enabled, RemoteBox will automatically add the guest additions ISO to the Virtual Media Manager so that it's available for attaching to guests. The default is enabled.

Tab: Guest Display → RDP Client

Configures the RDP client that RemoteBox will use when showing the display of a guest on a server which supports the RDP protocol. Some pre-defined options are available under the presets button, but the options are entirely customisable.

Tab: Guest Display → VNC Client

Configures the VNC client that RemoteBox will use when showing the display of a guest on a server which supports the VNC display protocol. Some pre-defined options are available under the presets button, but the options are entirely customisable. Some VirtualBox builds that use the VNC protocol, require a password to be used every time the display is opened. This is the case with the FreeBSD builds for example. As it is not possible to set this password from within RemoteBox, it must be configured on the server using the vboxmanage command, so get prompted for the password when showing the guest's display. For example:

vboxmanage modifyvm <guestname> --vrdeproperty VNCPassword=<vncpassword>

RDP/VNC Client Variables

RemoteBox uses special variables which are substituted as command parameters when the RDP/VNC client is launched. These should be used wherever your RDP/VNC client expects to see options such as the hostname or port number. The supported variables are:

%h	Will be substituted with the hostname of the VirtualBox server
%n	Will be substituted with the guest's name (useful for setting the window title for example)
%o	Will be substituted with the guest's operating system
%p	Will be substituted with the RDP/VNC port number
%P	Will be substituted with the user's password that was used to connect to VirtualBox
%U	Will be substituted with the username that was used to connect to VirtualBox
%X	Will be substituted with the Auto-Hint Resolution width
%Y	Will be substituted with the Auto-Hint Resolution height
%D	Will be substituted with the Auto-Hint Resolution depth

Tab: Guest Display → Open Guest's Display at Power On

If enabled, RemoteBox will automatically show the guest's display when it is started. If disabled, you will need to manually show the display by using the Guest Display button on the toolbar.

Tab: Guest Display → Auto-Hint Resolution

When a guest's display is shown, it automatically sends the requested display resolution hint. A display hint tries to keep the guest's display at the specified resolution. In addition, if your RDP/VNC client uses any of the %X, %Y or %D substitutions, the corresponding display values will be inserted as parameters. The exact behaviour is entirely dependent on your RDP/VNC client, the guest operating system and whether you have guest additions installed or not.

In order to use VirtualBox and the guests, you need to connect to a server running the VirtualBox web service. Documentation on setting up the server is published elsewhere on this site. Pressing the Connect button open the connection dialogue.

Connection Profile

Choose a pre-defined connection profile to automatically fill in the connection details.

URL

The connection URL for the server. This is generally of the form http://<server>:<port>. If no port is specified, the default of 18083 is used. If no protocol prefix is specified then http is used. If you have configured the server to use SSL, then you will need to specify https:// as the prefix. General example:

http://myserver.example.com:18083

Username

The username of any valid user on the server. If you have authentication disabled, you can leave it empty.

Password

The corresponding password of the user. If you have authentication disabled, you can leave it empty.

The status of the guests are not updated in real time. To see any changes to guests which have occurred outside or RemoteBox such as another process starting a guest, you can use the Refresh button

Guest Display

RemoteBox uses the RDP/VNC feature of VirtualBox to show the guest's display. To use this option effectively, each guest must be configured with the RDP/VNC server as enabled. When a guest is created through RemoteBox, this is enabled by default. This option can be set in the guest's settings under Display → Remote Display → Enable Remote Display Server (RDP/VNC). You should also ensure that the range of Server Ports specified for use with RDP/VNC are open to connections if your server has a firewall.

Guest Display with Sound

Sound support is also possible and is enabled by default in most cases where the RDP display protocol is used. In other words, whenever you show guest's display, you will also hear its audio. The guest must have audio support enabled in its settings and the guest operating system must also have drivers installed and running for the virtual sound card. When enabling audio support in the guest, it's recommended that you set the Host Audio Driver to be the Dummy Audio Driver. Otherwise, the guest will try to output the sound through the server's own sound device, which is probably not what you want.

Guest Display with Clipboard Sharing

Clipboard sharing, that is, copy and paste between the guest and the client machine is also possible wherever the RDP display protocol is used. The guest must have Shared Clipboard set to Bidirectional in its settings and the Guest Additions must be installed and operational.

Creating guests is a very similar process to VirtualBox. RemoteBox also enables additional defaults on a new guest which are useful for this operating model. This includes enabling the RDP/VNC server for guests so that their display can be used, including support for sound and clipboard sharing. All options can be changed after a guest is created if so desired.

By default, RemoteBox will automatically add the VBoxGuestAdditions.iso to the Virtual Media Manager (VMM) when connecting to a server. To install the guest additions, simply attach this ISO to the virtual CD/DVD drive of the guest and install as normal.

RemoteBox has the ability to hot plug and unplug vCPUs from a guest, even while it is running. This is considered an experimental feature and there are a number of prerequisites which must be met in order for this to work correctly.

• The guest must have CPU hot plugging enabled in its settings. System → Processor → Allow CPU Hot Plugging
• The guest should have I/O APIC enabled. System → Motherboard → Enable IO APIC
• The guest operating system itself must support CPU hot plugging or hot unplugging.

The exact process for hot plugging and unplugging a CPU is operating system dependant. Many versions of UNIX and Linux support hot plugging and unplugging CPUs. Most versions of Windows however, have very limited support CPU hot plugging and unplugging. You should consult the documentation for the operating system to determine the correct procedure and its support. Some general guidelines are:

Hot Plugging:
• Enable the vCPU in RemoteBox
• Some operating systems may automatically detect it and bring it online. Others will require you to bring the CPU online manually.

Hot Unplugging:
• Disable and offline the CPU in the guest first.
• Disable the corresponding vCPU in RemoteBox

RemoteBox supports some optional command line parameters.

remotebox [-h]
remotebox [-H <host>] [-u <user>] [-p <pass>]

-h : Help
-H <host> : Automatically connect to this virtualbox host
-u <user> : Connect using this username. If omitted an empty username is assumed. Only useful with -H
-p <pass> : Connect using this password. If omitted an empty password is assumed. Only useful with -H

./remotebox -H myserver.example.com -u myusername -p password123