Requirements

You must have an OpenNebula site properly configured and running to use OpenNebula Sunstone, be sure to check the OpenNebula Installation and Configuration Guides to set up your private cloud first. This guide also assumes that you are familiar with the configuration and use of OpenNebula.

OpenNebula Sunstone was installed during the OpenNebula installation, so you just need to install the following ruby gems to meet the runtime dependencies:

json

rack

sinatra

thin

Typically you can do this by typing:

$ sudo gem install <name_of_gem>

The Sunstone Operation Center offers the possibility of starting a VNC session to a Virtual Machine. This is done by using a VNC websocket-based client (noVNC) on the client side and a VNC proxy translating and redirecting the connections on the server-side.

It is quite straightforward to set up the VNC console, as the install_novnc.sh script does most of the job. However, be aware that this feature is sustained over the following extra requirements:

Phyton >= 2.5: Required by the VNC proxy (included with noVNC). This proxy is used to connect the server to the hosts and make the translation between websockets and regular sockets. The proxy does not work with older versions of Python.

Websockets-enabled browser (optional): Firefox and Chrome support websockets. In some versions of Firefox manual activation is required. If websockets are not enabled, flash emulation will be used.

Considerations & Limitations

OpenNebula Sunstone supports Firefox (> 3.5) and Chrome browsers. Internet Explorer, Opera and others are not supported and may not work well.

Configuration

noVNC Installation

noVNC is not included by default within Sunstone, and its installation is completely optional. In order to install it, please run the install_novnc.sh script. For system-wide installations:

$> cd /usr/share/one
$> sudo ./install_novnc.sh

The script will download and copy the noVNC files into the right place. It will also configure the Sunstone server accordingly. If you run into problems, you can checkout the related community FAQ question.

sunstone-server.conf

Sunstone configuration file can be found at /etc/one/sunstone-server.conf. It uses YAML syntax to define some options:

Available options are:

Option

Descripction

:host:

IP address on which the server will listen on. 0.0.0.0 for everyone. 127.0.0.1 by default.

:port:

Port on which the server will listen. 9869 by default.

:vnc_proxy_base_port:

Local base port for the VNC proxy. The final port for the proxy is calculated adding the base port and the VNC port of the host. 29876 by default.

:novnc_path:

Path to the folder of noVNC. Set by the VNC installation script. Check vnc console for more details

:auth:

Authorization system to be used. Possible values are basic and x509. Check authorization methods for more info

In order to access Sunstone from other place than localhost you need to set the server's public IP in the HOST option. Otherwise it will not be reachable from the outside.

Monitoring and plots

From Sunstone 3.0, graphical monitoring information has been included in the dashboard and in the extended information of hosts and virtual machines. In order to visualize the plots, it is necessary to run the oneacctd daemon:

The dashboard plots are refreshed every minute. However, the level of detail and length of the time frame depends on the ''oneacctd'' configuration.

Usage

Starting Sunstone

To start Sunstone just issue the following command as oneadmin

$ sunstone-server start

You can find the Sunstone server log file in /var/log/one/sunstone.log.

To stop the Sunstone service:

$ sunstone-server stop

Login

If you want to interact with Sunstone you have to open a new browser and go to the url where your Sunstone server is deployed. You will find the login screen where the username and password correspond to the OpenNebula credentials.

If you login as oneadmin (or the user with uid=0), or any other user belonging to the oneadmin group, you will have access to all resources and operations, including list and creation of users, groups, chown and chgrp operations. Regular users (belonging to the default group users) have a limited view according to the default ACLs. Special groups and ACLs may require additional Plugins Configuration.

Using the noVNC Console

In order to use this feature, make sure that:

The VM template has a graphics section defined, that the type attribute in it is set to VNC.

The specified VNC port on the host on which the VM is deployed is accessible from the Sunstone server host.

The VM is in running state.

If the VM supports VNC and is running, then the VNC icon on the Virtual Machines view should be enabled and clickable. Otherwise it just looks gray:

When clicking the VNC icon, the process of starting a session begins:

Sunstone server starts a VNC proxy to the desired host and port and returns the connection parameters to the client.

The client pops up noVNC web client in a dialog.

The VNC console embedded in this dialog will try to connect to the proxy either using websockets (default) or emulating them using Flash. Websockets are supported in Firefox 4.0 (manual activation required) and Chrome.

In order to close the VNC session just close the console dialog. The proxy will be then shutdown by Sunstone server.

Tuning & Extending

Plugins

Sunstone javascript client files are plugin-oriented. Plugins can be enabled/disabled for certain users and groups. Information about configuration and development of plugins can be found at the:

Authorization methods

Sunstone supports two authorization methods in order to log in. The method can be set in the sunstone-server.conf, as explained above. These two methods are:

Basic Auth

In the basic mode, username and password are matched to those in OpenNebula's database in order to authorize the user at the time of login. Rack cookie-based sessions are then used to authenticate and authorize the requests.

x509 Auth

This method performs the login to OpenNebula based on a x509 certicate DN (Distinguished Name). The DN is extracted from the certificate and matched to the password value in the user database (remember spaces are removed from DNs).

In order to use this method, OpenNebula must be configured with the x509 for Sunstone settings. Login screen will not display the username and password fields anymore, as all information is fetched from the user certificate:

Note that OpenNebula will not verify that the user is holding a valid certificate at the time of login: this is expected to be done by the external container of the Sunstone server (normally Apache), whose job is to tell the user's browser that the site requires a user certificate and to check that the certificate is consistently signed by the chosen Certificate Authority (CA).

Sunstone x509 auth method only handles the authorization of the user at the time of login. Authentication of the user certificate is a complementary setup, which can rely on Apache.

Once the login has been successful, OpenNebula creates a token for that user, which is signed with the private key which has been configured in /etc/one/auth/server_auth.conf. Subsequent requests are authenticated against the public certificate defined as well in server_auth_conf.

Deploying Sunstone in a different machine

By default the Sunstone server is configured to run in the frontend, but you are able to install the Sunstone server in a machine different from the frontend.

Use the -s option when installing from the source in the machine that will be running the server.

$ ./install.sh -s

Define the following environment variables:

ONE_AUTH

Needs to point to a file containing just a single line stating the oneadmin's credentials, “username:password”. If ONE_AUTH is not defined, $HOME/.one/one_auth will be used instead. If no auth file is present, OpenNebula Sunstone cannot work properly, as this is needed by the server to authenticate users.

ONE_LOCATION

If OpenNebula was installed in self-contained mode, this variable must be set to <destination_folder>. Otherwise, in system wide mode, this variable must be unset. More info on installation modes can be found here

ONE_XMLRPC

The endpoint where the OpenNebula core is waiting for the XMLRPC requests

Using this setup the VirtualMachine logs will not be available. If you need to retrieve this information you must deploy the server in the frontend

Configuring a SSL Proxy

OpenNebula Sunstone runs natively just on normal HTTP connections. If the extra security provided by SSL is needed, a proxy can be set up to handle the SSL connection that forwards the petition to the Sunstone server and takes back the answer to the client.

This set up needs:

A server certificate for the SSL connections

An HTTP proxy that understands SSL

OpenNebula Sunstone configuration to accept petitions from the proxy

If you want to try out the SSL setup easily, you can find in the following lines an example to set a self-signed certificate to be used by a lighttpd configured to act as an HTTP proxy to a correctly configured OpenNebula Sunstone.

Let's assume the server were the lighttpd proxy is going to be started is called cloudserver.org. Therefore, the steps are:

1. Snakeoil Server Certificate

We are going to generate a snakeoil certificate. If using an Ubuntu system follow the next steps (otherwise your milleage may vary, but not a lot):

Install the ssl-cert package

$ sudo apt-get install ssl-cert

Generate the certificate

$ sudo /usr/sbin/make-ssl-cert generate-default-snakeoil

As we are using lighttpd, we need to append the private key with the certificate to obtain a server certificate valid to lighttpd

The host must be the server hostname of the computer running the Sunstone server, and the port the one that the Sunstone Server is running on.

3. OpenNebula Sunstone Configuration

Start the Sunstone server using the default values, this way the server will be listening at localhost:4567

Once the lighttpd server is started, OpenNebula Sunstone requests using HTTPS URIs can be directed to https://cloudserver.org:8443, that will then be unencrypted, passed to localhost, port 4567, satisfied (hopefully), encrypted again and then passed back to the client.