1. Getting Started
    1. Why Hyperbox?
    2. What is Hyperbox?
    3. Global Architecture
    4. Requirements
    5. Features
  2. Installation and Launch
    1. Linux
      1. Debian-based
      2. RedHat-based
    2. Windows
    3. Others
    4. First Launch
  3. Hypervisors
    1. Overview
    2. VirtualBox
    3. Managing Hypervisors
  4. Console Viewers
    1. Overview
    2. Managing Console Viewers
  5. Advanced Topics
    1. Data location
    2. Logs
    3. Advanced configuration
  6. Credits and Special Thanks

Getting started

Why Hyperbox?

Many Enterprise-grade management solutions exist out there: VMware vCenter, Citrix XenServer/Center, Microsoft Hyper-V to name a few.
Regardless of that, none of these solutions were fitting to solve a very simple problem: manage a dedicated server for virtualization, under the OS of our choice, in a free and open way.
Also, being big fans of VirtualBox, we could only find products that emulated the VirtualBox behaviour/interface, but did not provide easy remote access to an admin console or any enterprise-grade features.
That's when Hyperbox was born: to provide a management gateway to VirtualBox with advanced features, but open to any hypervisor and extensions via modules.

The name "Hyperbox" is made of "hyper", denoting its "up" nature, and "box" for VirtualBox, its favourite hypervisor.
The Hyperbox logo is inspired by an Hypercube, building on top of the VirtualBox logo, just like it does for the software.

What is Hyperbox?

Hyperbox is a Virtual Enterprise Management tool written in Java so it can be ported to virtually any platform using the same code.

Hyperbox is:
  • Meant to be a solution that allow IT amateurs and professionals alike to manage virtualized infrastructures, ranging from a single dedicated server to a multi-cluster multi-site design.
  • Meant to be a free, open and simple alternative to VMware vCenter, Citrix XenServer/XenCenter, Microsoft Hyper-V.
  • Especially targeted for Enterprise with its access and permissions systems, its store management, log of all activities and audit of sensitive actions.
  • A Client-Server software, not meant to be used alongside another management tool (like vboxmanage).
  • Aimed to individuals that already have knowledge and concepts about virtualization. Hyperbox does not reinvent the wheel, only implements existing concepts.
Hyperbox is not:
  • Meant to run without an hypervisor to manage. Nothing would be achieved then...
  • Be another <insert protocol> front-end implementation of the VirtualBox user interface. Many already exist like phpVirtualBox.
  • Meant to run on desktops environment where user interaction is required with the Virtual Machine console. It radically changes the use cases of VirtualBox by running headless-only VMs.
  • An Hypervisor like VirtualBox or ESXi. Hyperbox does NOT run Virtual machines but only connects to an hypervisor that does to manage it.

Global Architecture

Hyperbox is made of three main components :
  • The Client, processing user inputs, sending them to the client and displaying the results or data change.
  • The Server, managing the Hypervisor, abstracting out its details and presenting a common management layer to the clients and proving a series of features that would normally not be present in the hypervisor itself.
  • The Hypervisor, running the actual virtualized entities.

The Client

The Client is a standalone Java program running on the server administrator's computer and is used to connected to an Hyperbox server. It comes as a GUI application by default.
It connects by mean of a "connector" which is a network module that read and write the data from/to the server. The default connector implements the Kryonet protocol.
The Client can connect to several servers at once.

The Server

The Server is the cornerstone of an Hyperbox infrastructure, by being the bridge between different hypervisors, their management, extra features and the client.
It will abstract out all the specific implementations between the hypervisors and only keep the generic concepts, making it pluggable with virtually anything.
Finally, most free hypervisor products don't provide any kind of advanced enterprise features, focusing on the virtual side of things. The Server is meant to fill that gap.

The Server runs as a background process, as a Daemon or Service, but can also be run interactively. More details in the Installation and Launch chapter.

The Hypervisor

The Hypervisor is the 3rd party software that the Hyperbox server manages by use of a module.
The module is a hot-pluggable Java package that can be dynamically used to directly connect to the hypervisor.
The Server can only connect to a single Hypervisor at the time by design, and it is strongly discourage to change it once in use.

Modules for VirtualBox are included by default in the Hyperbox releases - see the Hypervisors section for requirements and limitations.

Requirements

  • Java 1.6 64 bits or newer (Oracle JRE/JDK or OpenJDK JRE/JDK alike)
  • Hypervisor to connect to and its connector module. More on this in the Hypervisors chapter
  • TCP port 45612 open on the server

Features

  • Client-Server design, allowing local and remote access
  • Easy installer for both Client and Server
  • Daemon/Service support for the Server
  • Access control and Permissions
    • Users Authentication
    • Simple Permissions
      • Server (Full/None)
      • Virtual Machines (Full/None)
  • Stores (same concept as Datastores for VMware)
  • Tasks
    • See what is the server doing
    • See the task history, with details about each task
  • Modules
    • Can be added at runtime
    • Isolated environment

Installation and Launch

  1. Linux
    1. Debian-based
    2. RedHat-based
  2. Windows
  3. Others
  4. First Launch

Linux

Debian

VirtualBox

Install the latest VirtualBox from VirtualBox website - any other version/build are not tested and might break.

Java

Install :
$ sudo apt-get install default-jre-headless
Check that you get a successful version info:
$ java -version
java version "1.6.0_27"
OpenJDK Runtime Environment (IcedTea6 1.12.6) (6b27-1.12.6-1~deb7u1)
OpenJDK 64-Bit Server VM (build 20.0-b12, mixed mode)

Hyperbox

Server
Download the latest Hyperbox server installer
$ wget https://kamax.io/hbox/download/hbox_server-latest-linux_amd64.run
Run the installer and following the instructions. The Hyperbox daemon will start automatically - Output and errors are logged to <INSTALL_DIR>/log/hboxd.log by default.
$ sudo sh hbox_server-latest-linux_amd64.run
You can start/stop/restart/see status of the Hyperbox server using the init.d script as root :
# /etc/init.d/hboxd status
Client
Download the latest Hyperbox client installer
$ wget https://kamax.io/hbox/download/hbox_client-latest-linux_amd64.run
Run the installer
$ sudo sh hbox_client-latest-linux_amd64.run
The Client can then be launched via the main menu or by creating a shortcut pointing to <INSTALL_DIR>/hyperbox and setting the working dir to <INSTALL_DIR>

RedHat

VirtualBox

Install the latest VirtualBox from VirtualBox website - any other version/build are not tested and might break.

Java

Install :
$ sudo yum install java-1.6.0-openjdk.x86_64
Check that you get a successful version info:
$ java -version
java version "1.6.0_27"
OpenJDK Runtime Environment (IcedTea6 1.12.6) (6b27-1.12.6-1~deb7u1)
OpenJDK 64-Bit Server VM (build 20.0-b12, mixed mode)

Hyperbox

Server
Download the latest Hyperbox server installer
$ curl -O https://kamax.io/hbox/download/hbox_server-latest-linux_amd64.run
Run the installer and following the instructions. The Hyperbox daemon will start automatically - Output and errors are logged to <INSTALL_DIR>/log/hboxd.log by default.
$ sudo sh hbox_server-latest-linux_amd64.run
You can start/stop/restart/see status of the Hyperbox server using the init.d script as root :
# /etc/init.d/hboxd status
Client
Download the latest Hyperbox client installer
$ curl -O https://kamax.io/hbox/download/hbox_client-latest-linux_amd64.run
Run the installer
$ sudo sh hbox_client-latest-linux_amd64.run
The Client can then be launched via the main menu or by creating a shortcut pointing to <INSTALL_DIR>/hyperbox and setting the working dir to <INSTALL_DIR>

Windows

Server

Download the latest installer and run it. No up-to-date info is available here. If you have tried and got a nice step-by-step, please post on the forums or the mailing list.

Client

Download the latest installer and run it. You will be able to change the install directory.
You can then start it from the Start Menu under the Hyperbox folder.

Others

A ZIP package is available for the server and the client at the Downloads page.
Hyperbox doesn't require anything except for Java to be available. All the data, log file and configuration are stored within the install directory.
Therefore, to run Hyperbox in any other system, simply unzip the file in the location of your choice and run Hyperbox by taking example from the Linux bash script.

First launch

Fire up the client. You will start in an empty window

In the menu bar, click on Server > Add...

You will be prompted to enter the host name/IP address of the server you want to connect to. The Hyperbox Server default listener is available on all interfaces by default.
The default username / password are : admin / hyperbox
Click on Save once finished.

You can now right click > Connect or double-click on the server address to initiate the connection.
If successful, the icon will change to a stopped server icon, and the tabs on the right panel should activate. You should also see the Hyperbox Server detailed and that is it disconnected of the hypervisor.

Right click on the server: Select Hypervisor > Connect

Hyperbox comes by default with several connectors. Select the one matching your installation.
You can leave the "Connector Options" field blank for now, it is used for advanced configuration.
Click on Connect.

You should now see a new task in the bottom list showing you that Hyperbox is currently connecting and initializing the connection with the hypervisor.

If successful, the server icon will change as well as the hypervisor status in the detail panel.

You can now then manage your machines or create new ones by right clicking on the server list item in the left panel!

Hypervisors

Overview

Hyperbox itself is only a manager of a virtualized infrastructure, but does not provide any virtualization features.
To provide these features, Hyperbox will rely on 3rd party products that will provide these features.
Hyperbox is mainly aimed to work with VirtualBox, an open-source product from Oracle. But given the modular structure of Hyperbox, any other hypervisor could be ported, as long as they provided a compatible API with Java.
One of the long-term goal is Hyperbox is also to allow management of an hybrid infrastructure (VirtualBox and VMware per example) and also allow to transfer VM between the two.

VirtualBox

Currently, Hyperbox is shipped with connectors for several versions of VirtualBox, as well as different connection protocols.
VirtualBox supports the following kind of connectors :
  • WebServices: Compatible with all systems but may require some configuration in VirtualBox.
    The connector is slower than XPCOM/COM and come with several limitations. It is the recommended connector for all platforms due to bugs in the others.
  • XPCOM: Only compatible with systems supporting XPCOM, which is basically any UNIX-based system. This is a native connector that supports every feature of VirtualBox and should be preferred over WebServices.
  • MSCOM: Only compatible with Windows systems. Due to build limitation in the VirtualBox SDK and a known bug (Ticket #13483), this kind of connector is not currently implemented in Hyperbox. Only WebServices can be used on Windows.
Hyperbox is shipped with the following connectors for the given versions:
  • 4.2.x
    • XPCOM
    • WebServices
  • 4.3.x
    • XPCOM
    • WebServices
A known bug prevents XPCOM to work on all versions. XPCOM only works from 4.2.24 and 4.3.8. Fix was not back-ported to any previous versions and therefore will never work.
You can find detailed info on Ticket #11232 of the VirtualBox BugTracker.
XPCOM has a severe bug which produces a memory leak, preventing resources to be released once connected to VirtualBox, including TCP sockets.
Is it highly recommended to use WebServices connector on all platforms and all versions of VirtualBox for the time being.
You can find detailed info on Ticket #13647 of the VirtualBox BugTracker.

Managing Hypervisors

Hypervisor connectors are shipped with modules loaded in Hyperbox.

Once the modules are ready, you can connect to an hypervisor by right-clicking on the server > Hypervisor > Connect.
You will be prompted by dialogue to choose which hypervisor connector you want to use, and optional options for the connector.

The options are implementation specific, so syntax/values will normally be provided by the author of the Hypervisor connector module.
For the VirtualBox modules shipped with Hyperbox, the following options are available (anything in square brackets [ ] are optional) :

  • WebServices: [http[s]://][user:password@]host[:port]
    Default value is http://localhost:18083 and expects VirtualBox to be configured with null authentication for the WebServices - See the webservauthlibrary property
     
  • XPCOM: full base path to the VirtualBox XPCOM native code.
    Default value is /usr/lib/VirtualBox

Console Viewers

Overview

Since Hyperbox will start VMs in headless mode (or equivalent), it is indispensable to be able to connect to the console of the VM, being like the physical screen of a real computer.
That is an essential step to perform OS installs, start rescue modes, or simply access the console for debugging purposes.
Hyperbox already provides the Console module and address in the VM summary panel if available, but also implements the concept of "Console Viewers".
Console Viewers are programs that can be launched to connect to and display the VM console by the simple press of a button. Console viewers are meant to map to a specific protocol.
VirtualBox provides a RDP implementation in the Extension pack and a non-supported VNC implementation built from SVN, both which can be used with standard programs like :
  • Windows: Remote Desktop native Client (mstsc.exe) and UltraVNC
  • UNIX-Like: rdesktop and UltraVNC
Hyperbox can (and should) pass parameters using variables like the console IP and port, server hostname, VM name, etc.
Hyperbox will use two values to map a given console viewer to a VM: the Hypervisor Type ID and the Console Module.
The Hypervisor type can be found on the Server Summary panel and the Console module in each VM Summary panel.

Managing Console Viewers

Default Console Viewers

Connect to a VM console

Variables

Add Console Viewer(s)

Edit a Console Viewer

Remove Console Viewer(s)

Advanced Topics

Data location

Client

The client stores all the configuration files in the following location, depending on the system :
  • Unix-based: $HOME/.hbox
  • Windows: %APPDATA%/Hyperbox
The location cannot currently be changed.

Server

The server relies on Persistor modules to store its data. Therefore, the location will depend on the configuration of the used module.
The default Persistor module is based on an H2 database on disk, located at <INSTALL_DIR>/data/global.h2.db

Logs

Advanced Configuration

Common

Name Daemon Config File Command-Line option Environment Variable Purpose
Log File log.file -Dlog.file HBOX_LOG_FILE Define where Hyperbox will log messages. Relative paths will start from the installation directory.
Log Output Level log.level -Dlog.level HBOX_LOG_LEVEL Define the maximum logging level for Hyperbox. A level include all the levels above (in terms of verbosity). The following levels are available in increasing verbosity order :
FatalException - Only log exceptions stack traces that caused the server to stop. This is currently not used.
Exception - Log exceptions stack traces that are not fatal. This is tightly linked to Error level as each error will also produce an exception entry.
Error - Log errors that occurred. This is tightly linked to Exception level as the message will be the exception message.
Warning - Log warnings.
Info - Log regular info messages. This is the default level.
Verbose - Log precise info messages.
Debug - Log debug info for each server activity, task and client request: This can be quite verbose and should not be kept on in live environment due to the performance penalty.
Tracking - Log code tracking info: This is very verbose and WILL inflict a high performance penalty but will provide very detailed info for debugging.

Server

Name Daemon Config File Command-Line option Environment Variable Purpose
Server Name server.name -Dserver.name HBOX_SERVER_NAME Configure a name for the server that will be display in the client.
The hostname will be used as default value.
Kryonet Connector Port kryonet.net.tcp.port -Dkryonet.net.tcp.port HBOX_KRYONET_NET_TCP_PORT Define the listening port for the default client connector using Kryonet.
Default value is 45612
Kryonet Write Buffer size kryonet.net.buffer.write -Dkryonet.net.buffer.write HBOX_KRYONET_NET_BUFFER_WRITE Define the Kryonet write buffer size for output write.
Default value is 1838400
Kryonet Object Buffer size kryonet.net.buffer.object -Dkryonet.net.buffer.object HBOX_KRYONET_NET_BUFFER_OBJECT Define the Kryonet object buffer size for output write..
Default value is 456121638400

Credits and Third Parties

Credits

The current Hyperbox release relies on several open-sources libraries and media. NOTICE and LICENSE files can be found for each of these under <INSTALL_DIR>/doc/legal of your Hyperbox installation.

Special Thanks

The Hyperbox team would like to give their special thanks to those who dedicated their time to make this project come true and making it better by their continuous support and their kind words in the hardships.
  • Perryg
  • klaus-vb