System Administrator guide

Table of contents

• Introduction
• Quickstart
• Prerequisites and recommendations
• Installation instructions
• Upgrade
• Configuration instructions
• Service operation
• Troubleshooting

## Introduction

The Virtual Organization Membership Service (VOMS) is an attribute authority which serves as central repository for VO user authorization information, providing support for sorting users into group hierarchies, keeping track of their roles and other attributes in order to issue trusted attribute certificates and SAML assertions used in the Grid environment for authorization purposes.

## Quickstart

This quickstart guide covers the MySQL installation of VOMS.

• Install the EMI release package.
• Install the emi-voms-mysql metapackage.
• Set a sensible password for the MySQL root user, as explained in the instructions below.
• Configure the VOMS service using voms-configure following the instructions given in the configuration section of this guide.

## Prerequisites and recommendations

Hardware

• CPU: No specific requirements
• Memory: 2GB if serving <= 10 VOs, more otherwise
• Disk: 10GB free space (besides OS and EMI packages)

Operating system

• NTP Time synchronization: required.
• Host certificates: required
• Networking
  • Open ports : see the Service reference card

Installed software

Besides the usual OS and EMI release packages, in case of an Oracle based installation you will need the oracle-instantclient-basic package, version 11.2.0.3, as repackaged by CERN:

yum localinstall oracle-instantclient-basic-11.2.0.3-1.x86_64.rpm

All the other dependencies are resolved by the installation of the VOMS metapackages, i.e.:

• emi-voms-mysql, in case of a MySQL installation,
• emi-voms-oracle, in case of an Oracle installation.

Recommended deployment scenarios

A single-node installation, with the hardware recommendations given above should serve well most scenarios. Serving a large number of VOs (> 20) will require more memory and disk space.

## Installation instructions

Repositories

Follow the general EMI 3 installation instructions. VOMS requires that the OS and EPEL repositories are active and correctly configured on the target machine. If Oracle is used, a repository where Oracle packages are available should also be provided. Otherwise Oracle packages need to be installed manually.

Certificate revocation lists

Following the EMI-3 installation instructions you have installed the EGI IGTF certification authorities certificates. To enable periodically fetching certificate revocation lists, install the fetch-crl package

yum install fetch-crl

run it a first time

/usr/sbin/fetch-crl

and enable a cron job that periodically refresh CRLs on the filesystem as follows:

/sbin/chkconfig fetch-crl-cron on
/sbin/service fetch-crl-cron start

Clean installation

Install the emi-voms-mysql metapackage, or emi-voms-oracle depending on the database backend you are using

yum install emi-voms-mysql

## Upgrade instructions

Upgrade from EMI 1 or EMI 2 VOMS

It is always a good idea in this cases to make a dump of the database

/usr/bin/mysqldump -u <dbusername> -p<dbpassword> <dbname>

Follow the general EMI 3 installation instructions.

Stop the services

service voms stop
service voms-admin stop

Run yum update, and then manually remove Apache Tomcat (tomcat5 or tomcat6 depending on the SL version) as VOMS 3.x does not depend on it anymore.

yum update
yum remove tomcat6

Run voms-configure providing the database information, and skipping the options for database creation

voms-configure install --vo <vo_name> \
--core-port 15000 \
--admin-port 16000 \
--hostname <hostname> \
--dbusername <dbusername> \
--dbpassword <dbpassword> \
--dbname <dbname> \
--mail-from <mail-from> \
--smtp-host <smtp-host>

Start the services

service voms stop
service voms-admin stop

Upgrade from gLite 3.2

The upgrade from gLite 3.2 is not supported. Upgrade to EMI 1 or 2 and then upgrade to the latest VOMS release.

## Configuration instructions

VOMS is now configured only using its own configuration utility, voms-configure. YAIM configuration for this version of VOMS is not supported.

Database backend configuration

MySQL

Make sure that the MySQL administrator password that you specify when running voms-configure matches the password that is set for the root MySQL account, as voms-configure will not set it for you.

Setting the MySQL administrator password

Ensure that MySQL is running. If not running, start it (as root) using the following command:

service mysqld start

The following commands change the password for the MySQL root account:

/usr/bin/mysqladmin -u root password <adminPassword>
/usr/bin/mysqladmin -u root -h <hostname> password <adminPassword>

Oracle

VOMS uses the Oracle instant-client native libraries to connect to Oracle databases.

These libraries require that the TNS_ADMIN and LD_LIBRARY_PATH environment libraries are set in a compatible way with your oracle-instantclient installation.

VOMS comes with default settings that work out-of-the box with the oracle instantclient packages as repackaged by CERN.

tnsnames.ora configuration

To configure the database endpoints, a tnsnames.ora file must be used and placed in the following location:

/etc/voms

If you want to place the tnsnames.ora in a different location, change the value of the TNS_ADMIN variable in the following files:

/etc/sysconfig/voms
/etc/sysconfig/voms-admin

VOMS services configuration

Run voms-configure to configure both voms-admin and voms. The general syntax of the command is

voms-configure COMMAND [OPTIONS]

Available commands are:

• install: is used to configure a VO
• remove: is used to unconfigure a VO
• upgrade: is used to upgrade the configuration of a VO installed with an older version of voms-admin.

Usually, you do not have a dedicated MySQL administrator working for you, so you will use voms-admin tools to create the database schema, configure the accounts and deploy the voms database. If this is the case, you need to run the following command:

voms-configure install --dbtype mysql
--vo <vo name> 
--createdb 
-–deploy-database  
--dbauser <mysql root admin  username>
--dbapwd <mysql root admin  password>
--dbusername <mysql voms username>
--dbpassword  <mysql voms password>
--core-port <voms core service port>
--admin-port <voms admin service port>
--smtp-host <STMP relay host>
--mail-from <Sender address for service-generated emails>

Note that the above command is entered as a single command; it has been broken up into multiple lines for clarity. The command creates and initializes a VOMS database, and configures the VOMS core and admin services that use such database. For more information about voms-configure options, see the man page.

An example MySQL VO installation command is shown below:

/usr/sbin/voms-configure install --dbtype mysql \ 
--vo test.vo --createdb --deploy-database \ 
--dbauser root --dbapwd pwd \ 
--dbusername voms --dbpassword pwd \ 
--core-port 15000 \
--admin-port 16000 \
--mail-from [email protected] \ 
–-smtp-host iris.cnaf.infn.it

Oracle VO configuration is different from MySQL configuration. In Oracle you need to setup the database account for VOMS before launching voms-admin configure. Moreover, Oracle instant client libraries must be installed and configured before running voms-admin configuration.

Once you have configured the Oracle database backend, you can install a new Oracle VO using the following command:

voms-configure install --dbtype oracle 
--vo <VO name> 
--dbname <TNS alias of the database backend> 
--deploy-database
--dbusername <voms db account username> 
--dbpassword <voms db account password> 
--core-port <voms core service port> 
--admin-port <voms admin service port>
--smtp-host <SMTP relay host> 
--mail-from <Sender address for service-generated emails>

Note that the above command is entered as a single command; it has been broken up into multiple lines for clarity. This command is indeed very similar to the one used to configure a MySQL VO. The main difference lies in the dbname option, that is used to specify the TNS alias for the Oracle database backend.

This TNS alias is needed to build the connection string that VOMS will use to communicate with the database backend. Usually, TNS aliases are maintained in the tnsnames.ora file, located in a directory that is usually exported to applications via the TNS_ADMIN Oracle environment variable. For more information regarding TNS aliases, consult the Oracle online documentation (http://www.oracle.com/pls/db102/homepage).

voms-configure is used also for removing already configured vos

voms-configure remove --vo VONAME

Available options are:

• undeploy-database: Undeploys the VOMS database. By default when removing a VO the database is left untouched. All the database content is lost.
• dropdb (MySQL only): This flag is used to drop the mysql database schema created for MySQL installations using the --createdb option

Information system

BDII

The script voms-config-info-providers configures the providers for the resource bdii. Run

voms-config-info-providers -s SITENAME -e

giving the site name (which in the past went into the sitedef configuration file). If not deploying the administration service, skip the -e option.

Start the bdii service and check services are published. The query

ldapsearch -x -h localhost -p 2170 -b 'GLUE2GroupID=resource,o=glue' objectCLass=GLUE2Service

should return a service for each virtual organization.

EMIR

You can use EMIR-SERP to publish VOMS information to EMIR. EMIR-SERP uses the information already available in the resource bdii and publish it to an EMIR DSR endpoint. You have to know the EMIR endpoint to do this, in the following example the EMI testbed EMIR endpoint is used.

Install emir-serp

yum install emir-serp

and edit the configuration file /etc/emi/emir-serp/emir-serp.ini, providing the url for the EMIR DSR and the url for the resource bdii

...
url = http://emitbdsr1.cern.ch:9126
...
[servicesFromResourceBDII]
resource_bdii_url = ldap://localhost:2170/GLUE2GroupID=resource,o=glue
...

See the configuration file documentation for other options. You for sure will want to change the validity (the time EMIR DSR is told to consider the information valid) and period (the interval at which emir-serp will check for change in the bdii and refresh the publishing) attributes

# Period of registration/update messages
# Mandatory configuration parameter
# Value is given in hours
period = 1

# Time of registration entry validity
# Mandatory configuration parameter
# Value is given in hours
validity = 1

Start emir-serp with

service emir-serp start

and check your EMIR deployment to make sure the endpoints are published. You can spot problems increasing the verbosity of the emir-serp logging by editing the configuration file

verbosity = debug

## Service operation

To start and stop the VOMS core and admin service for all the vos on the machine, use the following commands:

service voms start
service voms-admin start

To start or stop a specific VO, use the following commands:

service voms start <vo>
service voms-admin start <vo>

Log files locations

Service	Directory	Filename
VOMS core	/var/log/voms	voms.VO_NAME
VOMS admin	/var/log/voms-admin	voms-admin-VO_NAME.log

Logging verbosity configuration

VOMS core

The VOMS core service logging verbosity is set with the --loglevel option in the:

/etc/voms/VO_NAME/voms.conf

Log levels are numeric values which have the meaning defined in the following table:

Value	Level name	Meaning
1	LEV_NONE	Do not log
2	LEV_ERROR	Log only error messages
3	LEV_WARN	Log warn error messages and above
4	LEV_INFO	Log info messages and above
5	LEV_DEBUG	Log debug messages and above

The --logtype flag controls which type of information is logged by the voms server. The default value for this option is 7 and should be left configured so.

VOMS admin

The VOMS admin service uses logback for logging configuration. The logging configuration for a given VO is maintained in the following file:

/etc/voms-admin/VO_NAME/logback.xml

Migration

In order to migrate VOMS to a different machine, the following items will need to be migrated:

1. The configuration
2. The database content. This holds only if VOMS was configured to access a local database instance. If a remote database is used for VOMS only the configuration will need to be migrated to the new installation.

Configuration migration

To migrate VOMS configuration, archive the contents of the following directories and move the archive to the new installation:

/etc/voms/*
/etc/voms-admin/*

Database migration (MySQL)

In order to dump the contents of the VOMS datbase issue the following command on the original VOMS installation machine:

mysqldump -uroot -p<MYSQL_ROOT_PASSWORD> --all-databases --flush-privileges > voms_database_dump.sql

This database dump contains all the VOMS data and can be moved to the new VOMS installation machine.

To restore the database contents on the new VOMS installation machine, ensure that:

1. mysql-server is up & running
2. the password for the MySQL root account is properly configured (see the configuration section for more details)

The database content can then be restored using the following command:

mysql -uroot -p<PASSWORD> < voms_database_dump.sql

## Troubleshooting

See the known issues page.