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

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 as oneadmin:

<xterm>$ oneacctd start</xterm>

oneacctd requires additional setup and gems. Make sure you read the monitoring daemon documentation first.

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

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.

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:

• 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 from Firefox 4.0 (manual activation required in this version) and Chrome.

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

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

• Make sure there are not firewalls blocking the connections. The proxy will redirect the websocket data from a specific port –which is calculated as VNC_PROXY_BASE_PORT + VNC_PORT– to the VNC port stated in the template. The value of the base port is defined in sunstone-server.conf or occi-server.conf for Self-Service UI.

• It may be helpful to use tools such as vncviewer to test if the VNC direct connection to the VM actually works.

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

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

Make sure that your ruby gems (Sinatra, thin, rack) are updated to their latest versions.

This applies to SelfService UI as well.

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:

• Sunstone Plugin Guide
• Sunstone Plugin Reference

Todo

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:

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