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. If you followed the installation guide then you already have all ruby gem requirements. Otherwise, run the install_gem script as root:

<xterm> # /usr/share/one/install_gems sunstone </xterm>

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:

• noVNC: websocket-based VNC client. It includes a VNC proxy (see noVNC Installation).
• 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.

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

noVNC allows to open a VNC session from your webserver to a desired Virtual Machine. When we speak of noVNC itself, we normally refer to both the noVNC websockets client and the proxy translates and forward the VNC connections, websockify. 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:

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

The script will download and copy the noVNC and websockify files into the right place. It will also configure the Sunstone server accordingly. For self-conained installations, just run the script with oneadmin making sure your $ONE_LOCATION is defined (be careful with the sudo command, make sure that the ONE_LOCATION is kept in the sudoers file). If you run into problems, you can checkout the related section down below.

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

Available options are:

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.

When running Sunstone Server on a different host than the OpenNebula Frontend, check this section.

Sunstone offers two types of monitoring information. The first one is global information, as presented in the main dashboard and the cluster dashboards. This information represents the current state of the cloud. It is refreshed regularly around every minute. Manual refresh is possible clicking on the refresh icons.

The second type is historical monitoring information for individual Hosts and Virtual Machines. This information is obtained from the accounting records. The monitoringi interval and the size of the time window that is returned is defined in oned.conf (*_MONITORING_INTERVAL and *_MONITORING_EXPIRATION_TIME).

Sunstone users can configure several options from the configuration tab:

• Language: select the language that they want to use for the UI.
• Use secure websockets for VNC: Try to connect using secure websockets when starting VNC sessions.

This options are saved in the user template. If not defined, defaults from sunstone-server.conf are taken.

To start Sunstone just issue the following command as oneadmin <xterm> $ sunstone-server start </xterm>

You can find the Sunstone server log file in /var/log/one/sunstone.log. Errors are logged in /var/log/one/sunstone.error.

To stop the Sunstone service: <xterm> $ sunstone-server stop </xterm>

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

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:

• A request is made and if a VNC session is possible, Sunstone server will add the VM Host to the list of allowed vnc session targets and create a random token associated to it.

• The server responds with the session token, then a noVNC dialog pops up.

• The VNC console embedded in this dialog will try to connect to the proxy either using websockets (default) or emulating them using Flash. Only connections providing the right token will be successful. Websockets are supported from Firefox 4.0 (manual activation required in this version) and Chrome. The token expires and cannot be reused.

In order to close the VNC session just close the console dialog.

From Sunstone 3.8, a single instance of the VNC proxy is launched when Sunstone server starts. This instance will listen on a single port and proxy all connections from there.

There can be multiple reasons that may prevent noVNC from correctly connecting to the machines. Here's a checklist of common problems:

• Check that noVNC is correctly installed. After the installation, have a look to /etc/one/sunstone-server.conf (or occi-server.conf if using Self-Service) and see if the websockify path is set correctly (:vnc_proxy_path).

• noVNC requires Python >= 2.5 for the websockets proxy to work. You may also need additional modules as python2<version>-numpy. The sunstone.log and or sunstone.error logs will record the proxy start command and any errors. You can use the command to fire the proxy manually and make tests.

• You must have a GRAPHICS section in the VM template enabling VNC, as stated in the documentation. Make sure the attribute IP is set correctly (0.0.0.0 to allow connections from everywhere), otherwise, no connections will be allowed from the outside.

• Your browser must support websockets, and have them enabled. This is the default in latest Chrome and Firefox, but former versions of Firefox (i.e. 3.5) required manual activation. Otherwise Flash emulation will be used.

• Make sure there are not firewalls blocking the connections. The proxy will redirect the websocket data from the VNC proxy port to the VNC port stated in the template of the VM. The value of the proxy port is defined in sunstone-server.conf or occi-server.conf for Self-Service UI.

• Make sure that you can connect directly from Sunstone frontend to the VM using a normal VNC client tools such as vncviewer.

• When using secure websockets, make sure that your certificate and key (if not included in certificate), are correctly set in Sunstone (or Self-Service) configuration files. Note that your certificate must be valid and trusted for the wss connection to work. If you are working with a certicificate that it is not accepted by the browser, you can manually add it to the browser trust-list visiting https://sunstone.server.address:vnc_proxy_port. The browser will warn that the certificate is not secure and prompt you to manually trust it.

• Make sure that you have not checked the Secure websockets connection in Sunstone → System → Configuration tab if you're proxy has not been configured to support them. Connection will fail if so.

• If your connection is very, very, very slow, there might be a token expiration issue. Please to the manual proxy launch as described below to check it.

• Doesn't work yet? Try launching Sunstone, killing the websockify proxy and relaunching the proxy manually in a console window with the command that is logged at the beginning of sunstone.log. Leave it running and click on the VNC icon on Sunstone for the same VM again. You should see some output from the proxy in the console and hopefully the cause of why the connection does not work.

• Please contact the user list only when you have gone through the suggestion above and provide full sunstone logs, shown errors and any relevant information of your infraestructure (if there are Firewalls etc)

From Sunstone 3.4, image file upload to the server via the client browser is possible with the help of a vendor library. The process is as follow:

• Step 1: The client uploads the whole image to the server in a temporal file in the tpmdir folder specified in the configuration.
• Step 2: OpenNebula registers an image setting the PATH to that temporal file.
• Step 3: OpenNebula copies the images to the datastore.
• Step 4: The temporal file is deleted and the request returns successfully to the user (a message pops up indicating that image was uploaded correctly).

Note that when file sizes become big (normally over 1GB), and depending on your hardware, it may take long to complete the copying in step 3. Since the upload request needs to stay pending until copying is sucessful (so it can delete the temp file safely), there might be Ajax timeouts and/or lack of response from the server. This may cause errors, or trigger re-uploads (which reinitiate the loading progress bar).

As of Firefox 11 and previous versions, uploads seem to be limited to 2GB. Chrome seems to work well with images > 4 GB.

If you are running sunstone on top of Webrick, uploads will fail. Installing another server such as thin (gem install thin) will fix the problem.

This applies to SelfService UI as well.

Both Sunstone javascript client files and Sunstone server are plugin-oriented.

Client plugins can be enabled/disabled for certain users and groups. Information about configuration and development of client plugins can be found at the:

• Sunstone Plugin Guide
• Sunstone Plugin Reference

Server plugins allow to add custom routes to Sunstone server. Information about configuration and development of server plugins can be found at:

• Sunstone Server Plugin Guide

Sunstone and Self-Service support multiple languages. If you want to contribute a new language, make corrections or complete a translation, you can visit our:

• Transifex poject page

Translating through Transifex is easy and quick. All translations should be submitted via Transifex.

Users can update or contribute translations anytime. Prior to every release, normally after the beta release, a call for translations will be made in the user list. Then the source strings will be updated in Transifex so all the translations can be updated to the latest OpenNebula version. Translation with an acceptable level of completeness will be added to the final OpenNebula release.

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

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.

To enable this login method, set the :auth: option of /etc/one/sunstone-server.conf to sunstone:

    :auth: sunstone

Using this method the credentials included in the header will be sent to the OpenNebula core and the authentication will be delegated to the OpenNebula auth system, using the specified driver for that user. Therefore any OpenNebula auth driver can be used through this method to authenticate the user (i.e: LDAP)

    :auth: opennebula

This method performs the login to OpenNebula based on a x509 certificate 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).

The user password has to be changed running one of the following commands <xterm> oneuser chauth new_user x509 “/C=ES/O=ONE/OU=DEV/CN=clouduser” oneuser chauth new_user –x509 –cert /tmp/my_cert.pem </xterm> or create a new user: <xterm> oneuser create new_user “/C=ES/O=ONE/OU=DEV/CN=clouduser” –driver x509 oneuser create new_user –x509 –cert /tmp/my_cert.pem </xterm>

To enable this login method, set the :auth: option of /etc/one/sunstone-server.conf to x509:

    :auth: x509

The 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 authentication of the user at the time of login. Authentication of the user certificate is a complementary setup, which can rely on Apache.

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.

<xterm> # ./install.sh -s </xterm>

• Define the following environment variables:

• Make sure :one_xmlprc: variable in sunstone-server.conf points to the right place where OpenNebula frontend is running, You can also leave it undefined and export ONE_XMLRPC environment variable.

• Provide the serveradmin credentials in the following file /var/lib/one/.one/sunstone_auth. If you changed the serveradmin password please check the following section

<xterm> $ cat /var/lib/one/.one/sunstone_auth serveradmin:1612b78a4843647a4b541346f678f9e1b43bbcf9 </xterm>

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:

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

<xterm> $ sudo apt-get install ssl-cert </xterm>

• Generate the certificate

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

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

<xterm> $ sudo cat /etc/ssl/private/ssl-cert-snakeoil.key /etc/ssl/certs/ssl-cert-snakeoil.pem > /etc/lighttpd/server.pem </xterm>

You will need to edit the /etc/lighttpd/lighttpd.conf configuration file and

• Add the following modules (if not present already)
  • mod_access
  • mod_alias
  • mod_proxy
  • mod_accesslog
  • mod_compress
• Change the server port to 443 if you are going to run lighttpd as root, or any number above 1024 otherwise:

server.port               = 8443

• Add the proxy module section:

#### proxy module
## read proxy.txt for more info
proxy.server               = ( "" =>
                                ("" =>
                                 (
                                   "host" => "127.0.0.1",
                                   "port" => 9869
                                 )
                                 )
                             )


#### SSL engine
ssl.engine                 = "enable"
ssl.pemfile                = "/etc/lighttpd/server.pem"

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.

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

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 9869, satisfied (hopefully), encrypted again and then passed back to the client.