rOCCI:ROCCI-server Admin Guide
Introduction
OCCI (the Open Cloud Computing Interface) is a standard by the Open Grid Forum, specifying a protocol and API to perform various remote management tasks in clouds. The rOCCI-server extends cloud managers, which are not OCCI-compliant natively, with its own OCCI interface. It is based on the rOCCI (Ruby OCCI) Framework.
Architecture
In a typical installation, shown in Figure 1, the rOCCI-server is accessed through the Apache HTTP Server. Since the OpenNebula backend is the flagship of rOCCI-server backend development, you will typically find it paired with the OpenNebula Cloud Manager.
Fig. 1: rOCCI-server in a typical setup |
The following differences from Figure 1, which shows a typical set-up as envisioned by rOCCI-server developers, may appear in production if the site so prefers:
|
For reference, you may also see Figure 2, showing the essentials of rOCCI-server's internal structure. Understanding the architecture at that depth is not necessary for administration, but can be useful in case troubleshooting is required.
Deployment Scenarios
The rOCCI-server was designed with 1:1 deployment in mind, i.e., one rOCCI-server instance per cloud manager. It is also possible to use multiple rOCCI-server instances to access a single cloud manager. However, it is impossible to use a single rOCCI-server to access multiple cloud managers, even should they all be running the same application – see Figure 3.
|
Fig. 3: Supported / unsupported deployment scenarios
Unless there is specific reason to do otherwise, install rOCCI-server instances with your cloud managers 1:1. Collocation is mildly recommended, but by no means necessary.
Installation and Configuration
rOCCI-server installation consists of two discrete steps—installing the server and choosing/configuring the backend to use, followed by setting up user access.
Be aware that command-line instructions are given separately for APT-based and YAIM-based distributions. You may need to use the horizontal scrollbar to view the right YAIM column in most cases.
Note that the instructions are prepared in such a way that they may be copied & pasted into your command line. However, make sure that you are copying the commands in their entirety. Forgotten newlines (enters) are especially easy to overlook and difficult to debug.
Installing rOCCI-server
You can install release versions from repositories if packages are available for your distribution, or install any release or development version from source.
Prerequisites
Regardless of the installation method or source, rOCCI-server requires certain preparation before you can run it, or even install it.
- Make sure the host certificate and key are already in place where
mod_ssl
expects them and that the certificate will be readable to theapache
account (or whatever service account you are using) once you install the Web Server! Examples used throughout this Guide expect certificates in/etc/grid-security
.
Once these conditions are satisfied, you may proceed with the installation.
From Repository
Note: Packages are, for now, experimental. Be sure to report issues, and come back here for updates on repository location.
APT-based distributions (Debian, Ubuntu, …) | RPM-based distributions (Scientific Linux, CentOS, …) |
---|---|
Add official Phusion Passenger repository. gpg --keyserver keyserver.ubuntu.com --recv-keys 561F9B9CAC40B2F7 gpg --armor --export 561F9B9CAC40B2F7 | apt-key add - apt-get install -y apt-transport-https echo 'deb https://oss-binaries.phusionpassenger.com/apt/passenger wheezy main' >\ /etc/apt/sources.list.d/passenger-wheezy.list Install Apache, Memcache, Phusion Passenger and git. apt-get update apt-get install -y apache2 libapache2-mod-passenger\ libapache2-modsecurity memcached git Add rOCCI-server repository. apt-key adv --fetch-keys http://repository.egi.eu/community/keys/APPDBCOMM-DEB-PGP-KEY.asc cd /etc/apt/sources.list.d wget http://repository.egi.eu/community/software/rocci.server/1.0.x/releases/repofiles/debian-wheezy-amd64.list Install rOCCI-server. apt-get update apt-get install -y occi-server Unless already configured, make Apache listen on port 11443 echo Listen 11443 >> /etc/apache2/ports.conf Enable required modules and the a2enmod ssl a2enmod passenger a2enmod mod-security a2ensite occi-ssl service apache2 reload |
Enable EPEL, Install Apache with required modules, Passenger dependencies, and Memcache: rpm -ivh http://dl.fedoraproject.org/pub/epel/6/x86_64/epel-release-6-8.noarch.rpm yum install -y gcc-c++ curl-devel httpd \ httpd-devel apr-devel apr-util-devel mod_ssl \ policycoreutils-python mod_security memcached \ openssl-devel zlib-devel git Add rOCCI-server repository. cd /etc/yum.repos.d wget http://repository.egi.eu/community/software/rocci.server/1.0.x/releases/repofiles/sl-6-x86_64.repo Install rOCCI-server. yum install -y occi-server Install Phusion Passenger (follow instructions given to you by the installation script). /opt/occi-server/embedded/bin/passenger-install-apache2-module --auto --languages ruby /opt/occi-server/embedded/bin/passenger-install-apache2-module --snippet \ > /etc/httpd/conf.d/passenger.conf Make sure Apache listens on selected port (11443 by default). Bear in mind that multiple echo Listen 11443 >> /etc/httpd/conf/httpd.conf At this point you need to deal with SELinux. Although disabling it altogether is not recommended, it was the only way the authors were demonstrably able to make rOCCI-server accessible. Contributions are welcome. sed -i 's/SELINUX\s*=\s*enforcing/SELINUX=permissive/' /etc/selinux/config setenforce 0 Make sure required modules service httpd restart |
Tested in Debian 7 Wheezy | Tested in SL 6.5 Carbon |
You are now ready to continue by configuring your backend.
From Source
Note: These instructions are given for the 1.0.x branch (STABLE).
- Make sure Ruby version at least 1.9.3 is available to you – either already installed, or present in the repository.
Tip for SL6: rOCCI-server packages available from the EGI AppDB contain an embedded Ruby 1.9.3, consider installing From Repository - Install system prerequisites:
APT-based distributions (Debian, Ubuntu, …) RPM-based distributions (Scientific Linux, CentOS, …) apt-get install -y git ruby-dev libssl-dev memcached
yum install -y git openssl-devel memcached
Tested in Debian 7 Wheezy Tested in SL 6.5 Carbon - If you plan to access rOCCI-server through Passenger/apache (recommended), continue by installing and configuring the Apache Web Server.
APT-based distributions (Debian, Ubuntu, …) RPM-based distributions (Scientific Linux, CentOS, …) apt-get install -y libcurl4-openssl-dev \ apache2-mpm-worker libapr1-dev \ libaprutil1-dev apache2-prefork-dev \ build-essential libapache2-modsecurity
yum install -y gcc-c++ curl-devel httpd \ httpd-devel apr-devel apr-util-devel mod_ssl \ policycoreutils-python mod_security
Tested in Debian 7 Wheezy Tested in SL 6.5 Carbon Note: You do not need to restart Apache at this point. There will be another configuration change in the final step.
- Install Ruby-specific prerequisites. 'Be sure to install them as gems rather than repository packages! gem install bundler
- Create
rocci
service account, create installation directory and change identity:APT-based distributions (Debian, Ubuntu, …) RPM-based distributions (Scientific Linux, CentOS, …) mkdir /var/lib/rocci adduser --system --disabled-password --group \ --shell /bin/sh --home /var/lib/rocci rocci mkdir -p /opt/rOCCI-server chown rocci:rocci /opt/rOCCI-server
mkdir /var/lib/rocci adduser --system --shell /bin/sh --home /var/lib/rocci rocci mkdir -p /opt/rOCCI-server chown rocci:rocci /opt/rOCCI-server
Tested in Debian 7 Wheezy Tested in SL 6.5 Carbon - Clone code from GitHub. Make sure you are using the 1.0.x branch: git clone https://github.com/EGI-FCTF/rOCCI-server.git /opt/rOCCI-server cd /opt/rOCCI-server git checkout 1.0.x
- Create links to system directories (as root): ln -sf /opt/rOCCI-server/log /var/log/rocci-server ln -sf /opt/rOCCI-server/etc /etc/rocci-server
- Install Ruby dependencies and the Passenger Apache module. bundle install --deployment --without development test bundle exec passenger-install-apache2-module --auto bundle exec passenger-install-apache2-module --snippet > passenger.load
- Finalize Web Server configuration as
root
and restart. This step relies on example config files, which may be modified to your needs. Consult the maintenance section for more. Whatever you do, make sure the VirtualHost config file is not publicly readable as it typically contains passwords (thechmod
snippet bellow takes care of that, for instance).APT-based distributions (Debian, Ubuntu, …) RPM-based distributions (Scientific Linux, CentOS, …) cp /opt/rOCCI-server/examples/etc/apache2/sites-available/occi-ssl\ /etc/apache2/sites-available/ chmod o-rwx /etc/apache2/sites-available/occi-ssl echo Listen 11443 >> /etc/apache2/ports.conf cp /opt/rOCCI-server/examples/etc/apache2/conf.d/security\ /etc/apache2/conf.d/ cp /opt/rOCCI-server/passenger.load /etc/apache2/mods-available/ a2enmod passenger a2enmod ssl a2enmod mod-security a2ensite occi-ssl service apache2 restart
cp /opt/rOCCI-server/examples/etc/apache2/sites-available/occi-ssl\ /etc/httpd/conf.d/occi-ssl.conf chmod o-rwx /etc/httpd/conf.d/occi-ssl.conf echo Listen 11443 >> /etc/httpd/conf/httpd.conf cp /opt/rOCCI-server/examples/etc/apache2/conf.d/security\ /etc/httpd/conf.d/ cp /opt/rOCCI-server/passenger.load /etc/httpd/conf.d/passenger.conf
At this point you need to deal with SELinux. Although disabling it altogether is not recommended, it was the only way the authors were demonstrably able to make rOCCI-server accessible. Contributions are welcome.
service httpd restart
Tested in Debian 7 Wheezy Tested in SL 6.5 Carbon
Configuring Backends
rOCCI-server comes bundled with supported backends. In case you have followed this guide to install the rOCCI-sever, you will find backend configuration in Apache2 Virtual Host configuration file. Currently (Spring 2014) there are two backends bundled: OpenNebula and the Dummy backend.
Unless you plan to use the Dummy backend only, your cloud manager should already be installed at this point.
OpenNebula Backend
The OpenNebula backend is bundled with rOCCI-server. Follow these steps to configure and activate it:
- Make sure OpenNebula is already installed and running in your environment. Otherwise it is highest time to install it. Note that installation of OpenNebula is beyond the scope of this Admin Guide. You may find useful some of the available OpenNebula Tutorials.
- Create a
rocci
account for the rOCCI-server backend in OpenNebula and make it a member of theoneadmin
group: su - oneadmin oneuser create rocci '<actual_password_edited_out>' --driver server_cipher oneuser chgrp rocci oneadmin exit - Edit Virtual Host configuration file
/etc/apache2/sites-available/occi-ssl
or/etc/httpd/conf.d/occi-ssl.conf
, respectively, and change the following:- attribute
ROCCI_SERVER_BACKEND
must be set toopennebula
as shown: SetEnv ROCCI_SERVER_BACKEND opennebula Note: Do not confuse with attributeROCCI_SERVER_BACKEND
; that has another purpose. - attribute
ROCCI_SERVER_ONE_PASSWD
must be set to give the password for therocci
user set up in the previous step: SetEnv ROCCI_SERVER_ONE_PASSWD <actual_password_edited_out> - Server name attributes must be set to the rOCCI server's fully qualified domain name. Set
ROCCI_SERVER_HOSTNAME
andServerName
accordingly: ServerName rocci-server.example.com and SetEnv ROCCI_SERVER_HOSTNAME rocci-server.example.com Note: In case your rOCCI-server is not collocated with OpenNebula, these both need to point to the rOCCI-server. A different attribute is used to indicate the OpenNebula server.
- attribute
- Restart the WebServer. You may skip this step if you are going to configure GridSite next.
APT-based distributions (Debian, Ubuntu, …) RPM-based distributions (Scientific Linux, CentOS, …) service apache2 restart
service httpd restart
Tested in Debian 7 Wheezy Tested in SL 6.5 Carbon
Use with GridSite and VOMS (optional)
As long as your site is a part of the EGI Federated Cloud infrastructure, or another infrastructure relying on Virtual Organization Management Services (VOMS), you also need to install the GridSite module for Apache.
-
Choose repository to install from. GridSite is available from standard distribution repositories (EPEL, Debian) but not always in its most recent versions. EGI's UMD repository may be a better source, especially if you are a part of EGI.
- Installing from standard distro repositories:
APT-based distributions (Debian, Ubuntu, …) RPM-based distributions (Scientific Linux, CentOS, …) apt-get install -y gridsite
rpm -ivh http://dl.fedoraproject.org/pub/epel/6/i386/epel-release-6-8.noarch.rpm yum install -y gridsite
Tested in Debian 7 Wheezy Tested in SL 6.5 Carbon - Installing from UMD:
APT-based distributions (Debian, Ubuntu, …) RPM-based distributions (Scientific Linux, CentOS, …) UMD is currently only available for Debian 6 Squeeze. If you cannot use the current GridSite version in Wheezy, and want a new one, contact GridSite developers.
rpm -ivh http://dl.fedoraproject.org/pub/epel/6/i386/epel-release-6-8.noarch.rpm yum install -y yum-priorities yum-protectbase rpm -ivh http://emisoft.web.cern.ch/emisoft/dist/EMI/3/sl6/x86_64/base/emi-release-3.0.0-2.el6.noarch.rpm yum install -y gridsite
Tested in Debian 7 Wheezy Tested in SL 6.5 Carbon
- Installing from standard distro repositories:
- Make sure
mod_gridsite
is loaded when WebServer starts. If you are installing in accordance with the previous step, it is already OK. Otherwise, you may need to add a config file (see example in/opt/rOCCI-server/examples/etc/apache2/mods-available/zgridsite.load
) and enable the module. - Activate GridSite in you Virtual Host's configuration file—
/etc/apache2/sites-available/occi-ssl
or/etc/httpd/conf.d/occi-ssl.conf
, respectively.- Add the following directives:
## variables (and is needed for gridsite-admin.cgi to work.) GridSiteEnvs on ## Nice GridSite directory listings (without truncating file names!) GridSiteIndexes off ## If this is greater than zero, we will accept GSI Proxies for clients ## (full client certificates - eg inside web browsers - are always ok) GridSiteGSIProxyLimit 4 ## This directive allows authorized people to write/delete files ## from non-browser clients - eg with htcp(1) GridSiteMethods ""
- And change the value of the
SSLVerifyClient
attribute torequire
SSLVerifyClient require - Extend
SSLOptions
attribute with optionExportCertData
: SSLOptions +StdEnvVars +ExportCertData
- Add the following directives:
- Make sure your VOMS settings are present, either in
/etc/vomses
or as.lsc
files in the/etc/grid-security/vomsdir
structure. - Enable GridSite and restart the WebServer.
APT-based distributions (Debian, Ubuntu, …) RPM-based distributions (Scientific Linux, CentOS, …) a2enmod zgridsite service apache2 restart
service httpd restart
Tested in Debian 7 Wheezy Tested in SL 6.5 Carbon
Dummy Backend
The Dummy backend is intended for testing purposes only. It is enabled by default, but you still need to make a few adjustments to use it. Edit file /etc/apache2/sites-available/occi-ssl
or /etc/httpd/conf.d/occi-ssl.conf
, respectively.
- Server name attributes must be set to the rOCCI server's fully qualified domain name. Set
ROCCI_SERVER_HOSTNAME
andServerName
accordingly: ServerName rocci-server.example.com and SetEnv ROCCI_SERVER_HOSTNAME rocci-server.example.com - If you have been using a different backend previously, and wish to revert to dummy, change attribute
ROCCI_SERVER_BACKEND
todummy
as shown: SetEnv ROCCI_SERVER_BACKEND dummy - Reload WebServer configuration:
APT-based distributions (Debian, Ubuntu, …) RPM-based distributions (Scientific Linux, CentOS, …) service apache2 reload
service httpd reload
Tested in Debian 7 Wheezy Tested in SL 6.5 Carbon
Configuring Access
With your OCCI chain in place, you need to decide on maintaining user identities on the Cloud Manager side, and on the methods of authentication your users will be allowed/required to use.
Maintaining User Identities
rOCCI-server itself provides only pass-through authentication, i.e., it neither stores nor checks user identities, but rather accepts your authentication information, augments it if necessary, depending on your strategy of choice, and passes it along to the cloud manager for the final authentication decision. This means that you need to maintain user identities within your Cloud Manager, e.g., Open Nebula.
Basic Methods
Basically, there are three ways of maintaining user identities, at least considering an rOCCI-server in combination with OpenNebula:
Manual | you maintain user accounts manually, incl. setting all details and choosing authentication drivers for each account. To do that use your Cloud Manager's built-in user management tools, e.g., the oneuser utility for OpenNebula.
|
---|---|
Perun | EGI Federated Cloud and other infrastructures use Perun to maintain user accounts. If you are an EGI member, you should use it. If not, you are welcome to consider it. |
Autocreation | Not supported yet! |
Authentication Drivers in OpenNebula
OpenNebula Supports two kinds of authentication drivers for general users:
core |
(default) The user will be using a user name and password to authenticate. Both are maintained in OpenNebula. |
---|---|
x509
|
The user will be using a certificate or proxy certificate to authenticate, possibly with VOMS extensions. OpenNebula stores the user's DN together with VOMS extensions, if provided. Note: Your certificate/proxy must contain the same extensions every time you connect. Otherwise you won't be recognized as the same user and authentication will fail. On the other hand, you can possess multiple accounts mapped to the same DN but distinguished by VO. |
Choosing Authentication Strategies
rOCCI-server supports multiple authentication strategies. You can decide which ones will be used in your deployment, and in what order they will be attempted when a user tries to connect.
Essential Settings
Authentication strategies are set using the ROCCI_SERVER_AUTHN_STRATEGIES
attribute in the Virtual Host configuration file /etc/apache2/sites-available/occi-ssl
or /etc/httpd/conf.d/occi-ssl.conf
, respectively. For instance the following line selects three strategies, which will be attempted left-to-right:
SetEnv ROCCI_SERVER_AUTHN_STRATEGIES "voms x509 basic"
An authentication attempt for each strategy can have three outcomes:
Success | User is authenticated, authentication finished. |
---|---|
Failure | Authentication details required by the given strategy were valid, but authentication failed. For instance, username and password were available for the basic strategy but it still failed. In that case authentication fails and no other strategy is attempted.
|
Invalidity | Authentication strategy failed due to auth. details being invalid. For instance, the basic strategy failed but there was no user name and password supplied in the first place. In that case authentication continues with the next strategy.
|
The following authentication strategies are currently supported by the rOCCI-server:
basic
|
Basic name/password authentication |
---|---|
x509
|
Authentication based on x509 certificates |
voms
|
Authentication based on x509 certificate proxies with VOMS extensions |
keystone
|
(experimental) Authentication based on keystone tokens |
dummy
|
For testing only, authentication based on arbitrary, locally specified rules |
Fine-Tuning Authentication Strategy Settings
Specific behaviour of authN strategies is controlled trhough settings in strategy configuration files:
/opt/rOCCI-server/etc/authn_strategies/*/production.yml
Caution is recommended. Use for inspiration rather than modification.
Maintenance
Updates from Repository
APT-based distributions (Debian, Ubuntu, …) | RPM-based distributions (Scientific Linux, CentOS, …) |
---|---|
Simply update all packages and restart Apache2. There are no special instructions. |
Update all packages and manually update native binaries for Phusion Passenger (instructions below). /opt/occi-server/embedded/bin/passenger-install-apache2-module --auto --languages ruby /opt/occi-server/embedded/bin/passenger-install-apache2-module --snippet \ > /etc/httpd/conf.d/passenger.conf |
Tested in Debian 7 Wheezy | Tested in SL 6.5 Carbon |
Updates from Source
In case you have installed rOCCI-server from source, you can also obtain updates that way. To update, do the following:
cd /opt/rOCCI-server git pull bundle install --deployment
Changing Default Configuration
Changing Default Listener Port
You may make rOCCI-server listen on a port different than the default 11443. The port is set in two different files and three different locations:
/etc/apache2/ports.conf
, using theListen
directive/etc/apache2/sites-available/occi-ssl
in theVirtualHost
tag/etc/apache2/sites-available/occi-ssl
, theROCCI_SERVER_PORT
attribute- Provided you plan to run multiple instances of rOCCI-server in one machine, then, also in
/etc/apache2/sites-available/occi-ssl
, theROCCI_SERVER_LOG_DIR
attribute, where it is recommended to add the given instance's port as a postfix to the log dir name for differentiation.
Choose whichever port you want, but keep the setting aligned across all three locations. After changing port settings in all places, restart the WebServer with
service apache2 restart
Testing
Smoke Tests
There are simple tests you can perform to check you have installed rOCCI-server correctly.
Basic Authentication
- Create a test account in OpenNebula: su - oneadmin oneuser create roccitest '<actual_password_edited_out>' exit
- Try accessing your cloud manager through the rOCCI-server in the following way: curl --insecure -u 'roccitest:<actual_password_edited_out>' https://$(hostname -f):11443/-/
X.509 Authentication
- Make sure you have rOCCI-server configured to use GridSite and VOMS.
- Create a test account in OpenNebula. The DN you use, naturally, must be registered with VOMS: su - oneadmin oneuser create roccix509 '<your certificate DN>' --driver x509 exit
- Try accessing your cloud manager through the rOCCI-server, for instance in the following way:
Distributions with OpenSSL (Debian, Ubuntu, …) Distributions with NSS SSL (Scientific Linux ≥ 6, CentOS, …) curl --cert <your certificate PEM file> \ --key <your key PEM file> \ --capath <path to your CA directory> \ https://$(hostname -f):11443/-/
pk12util -i <your certificate in PKCS12> -d sql:/etc/pki/nssdb curl --capath <path to your CA directory> \ https://$(hostname -f):11443/-/
Tested in Debian 7 Wheezy Tested in SL 6.5 Carbon
In both cases you should receive a text rendering of the OCCI model, looking approximately like the following:
Fig. 4: Example model listing in the command line
If, instead of the model, you receive a message like this:
Authentication failed! The following strategies are supported "voms, x509, basic"!
rOCCI-server works but your Cloud Manager was unable to authenticate you. Check your authentication details!
If you are able to get the model either way, your setup works. Note that this does not constitute a functionality test. It does not check for errors in either product, but it confirms that all components in your client ⇄ rOCCI-server ⇄ Cloud Manager chain are up and configured properly.
Monitoring Probes
Nagios probes for rOCCI server are available as α. Documentation will be made available on release.
Troubleshooting
FAQ
There are currently no questions asked frequently enough to merit inclusion.
Reporting Issues
Use rOCCI-server's GitHub Issues to report problems or contact the developers with your issues: https://github.com/EGI-FCTF/rOCCI-server/issues