VOMS System Administrator Guide

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

VOMS is composed of two main components:

• the VOMS core service, which issues attribute certificates to authenticated clients
• the VOMS Admin service, which is used by VO manager to administer VOs and manage

user membership details.

1.1 Quickstart guide

This quickstart guide covers the MySQL installation of VOMS.

1. Install the EMI 2 release package.
2. Install the emi-voms-mysql metapackage.
3. Install the xml-commons-apis package to avoid useless warnings when running Tomcat.
4. Set a sensible password for the MySQL root user, as explained in the instructions below.
5. Configure the VOMS service with YAIM as explained in this section.

1.2 Prerequisistes and recommendations

1.2.1 Hardware

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

1.2.2 Software

1.2.2.1 Operating system

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

1.2.2.2 Preinstalled software

Besides the usual OS and EMI release packages, you will need the oracle-instantclient-basic package, version 10.2.0.4, installed on the system (in case of an Oracle-based installation).

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.

1.3 Recommended deployment scenarios

A single-node installation, with the hardware recommendations given above should serve well most scenarios. It is not recommended to deploy a large number of VOs (> 20) on a single installation. This is due to an architectural limitation of VOMS (i.e., independent web applications and service for each VO) that will be solved in a future VOMS release.

1.4 Installation instruction

1.4.1 Software repositories

Follow the general EMI 1 or 2 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.

1.4.2 Clean installation

• In case you plan to install the emi-voms-oracle metapackage, download and install the Oracle instant client basic libraries (v. 10.2.0.4-1) on your system:
  • yum localinstall oracle-instantclient-basic-10.2.0.4-1.x86_64.rpm

• Install the emi-voms-mysql metapackage or emi-voms-oracle depending on the database backend you are using (mysql or Oracle):
  • yum install emi-voms-mysql or yum install emi-voms-oracle

• Manually install xml-commons-apis libraries (after having installed the right metapackage for your installation), as the ones provided by the default OS JREs cause warnings when starting/stopping tomcat:
  • yum install xml-commons-apis

1.4.3 Upgrade installation

1.4.3.1 Upgrade from gLite 3.2 VOMS

1.4.3.1.1 Install and configure a SL5 or SL6 X86_64 EPEL machine

In order to install the EMI VOMS metapackage you will need a clean SL5 or SL6 X86_64 machine with the EPEL repository configured and the emi release package correctly installed.

SL5, as configured by gLite 3.2, is not suitable for installing the EMI VOMS since gLite uses the DAG repository, which is alternative and incompatible with EPEL.

Once you have a clean machine configured, install the emi-voms-mysql metapackage without launching yaim configuration.

1.4.3.1.2 VOMS database dump and YAIM configuration

On your existing gLite 3.2 VOMS node dump the VOMS database for all the VOs issuing the following command:

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

You will then copy the dump file on the new EMI VOMS node.

Remember to save your YAIM configuration (in most cases, site-info.def and services/glite-voms in your siteinfo directory) and copy it on the new EMI VOMS node.

1.4.3.1.3 Restoring the VOMS database on the EMI node

You should now have the mysql daemon installed in your EMI machine (it was installed as a dependency of the emi-voms-mysql metapackage). Follow the instructions in this section to properly configure the mysql root account.

Once the root account is configured and working (check that you can login issuing the command mysql -uroot -p<MYSQL_ROOT_PASSWORD>), you can restore the VOMS database issuing the following command:

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

1.4.3.1.4 Configuring VOMS on the EMI node

The gLite 3.2 YAIM configuration should work in your EMI installation. Just check that no gLite-specific paths are referenced in your configuration and possibly integrate it with the new options provided by EMI VOMS.

When upgrading an Oracle installation follow these instructions before configuring the VOMS services with YAIM.

In order to configure VOMS, place the YAIM configuration files in your favorite directory and launch the following command:

/opt/glite/yaim/bin/yaim -c -s site-info.def -n VOMS

1.4.3.1.5 Upgrading a VOMS Oracle installation

On Oracle, a database schema upgrade is required when upgrading from gLite 3.2 or EMI 1. The schema upgrade should be performed before running the YAIM configuration following this procedure:

1. Backup the contents of the VOMS databases uses the appropriate tools as described in Oracle documentation.
2. Run voms-admin-configure upgrade
3. Reconfigure the services with YAIM (as described in the previous section)

1.4.3.1.6 Known issues for the gLite 3.2 to EMI upgrade

1.4.3.1.6.1 AUP is not shown correctly after upgrade to EMI

After upgrading a gLite 3.2 VOMS Admin the URL pointing to the default AUP text (/var/glite/etc/voms-admin//vo-aup.txt) is not upgraded to the new location (/etc/voms-admin//vo-aup.txt). This issue lead to an empty AUP shown to the users for the upgraded VOMS. To solve this issue, change the AUP url from the VOMS admin web interface by pointing your browser to:

https://<voms-hostname>:8443/voms/<vo>/aup/load.action

The default URL for the new aup is:

file:/etc/voms-admin/<vo>/vo-aup.txt

1.4.3.2 Upgrade from EMI 1 VOMS

1.4.3.2.1 Upgrading an SL5 EMI 1 installation

1. Install the emi-release package for EMI 2.
2. Update packages via yum update.
3. Restart the services

When upgrading an Oracle installation, follow this procedure:

1. Install the emi-release package for EMI 2.
2. Update packages via yum update.
3. Stop the services (voms and tomcat)
4. Backup the contents of the VOMS databases uses the appropriate tools as described in Oracle documentation.
5. Run voms-admin-configure upgrade
6. Restart the services

1.4.4 Configuration

1.4.4.1 TOMCAT file limits

It is safe to configure tomcat to have a reasonable limit for the number of open files that can be opened by the tomcat process. The default file limit can be modified by editing the /etc/security/limits.conf file:

tomcat          soft    nofile  63536
tomcat          hard    nofile  63536

1.4.4.2 Configuring the database backend

1.4.4.2.1 MySQL configuration

Make sure that the MySQL administrator password that you specify in the YAIM VOMS configuration files matches the password that is set for the root MySQL account. Yaim configuration script does not set it for you. If you want to set a MySQL administrator password:

1. Check that mySQL is running; if not, launch it using service mysqld start
2. Issue the following commands as root (putting appropriate information in the <adminPassword> and <hostname> placeholders)

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

The above command sets a password for the mysql root account.

1.4.4.2.2 Oracle configuration

Create the necessary users and databases in Oracle. Please see the Oracle manuals for details.

1.4.4.2.2.1 Oracle instantclient library path

In order to properly configure the library load path for the VOMS oracle backend, create a file named oracle-x86_64.conf in the /etc/ld.so.conf.d directory, with the following content:

/usr/lib/oracle/10.2.0.4/client64/lib

In case you use a different version of the the instantclient libraries (not recommended) , adjust the above accordingly.

1.4.4.3 Configuring the VOMS server with YAIM

Check the VOMS YAIM configuration guide.

1.5 Service operation

The YAIM configuration step is enough to have the VOMS core and admin services up and running. To start and stop the VOMS core service use:

service voms start/stop

To start and stop VOMS admin, use the tomcat start/stop scripts:

service tomcat5 start/stop (SL5)
service tomcat6 start/stop (SL6)

If you want to restart individual VOMS admin VO web applications, you can use:

service voms-admin start/stop <vo>

Use the above commands only in exceptional cases, and to deal with potential issues that affect only individual VOs.

The recommended way to start and stop VOMS admin is by using the tomcat startup scripts.

For other information regarding service operation see the VOMS service reference card.

1.5.1 Validation and monitoring

TBD

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

1.5.2.1 VOMS configuration migration

To migrate VOMS configuration, just archive the contents of the YAIM configuration directory and move this archive to the new installation. In case YAIM is not used, you will need to archive and move the following directories:

/etc/voms/* (EMI1 VOMS)
/etc/voms-admin/* (EMI1 VOMS Admin)

$GLITE_LOCATION/etc/voms/* (gLite 3.2 VOMS)
$GLITE_LOCATION_VAR/etc/voms-admin/* (glite 3.2 VOMS Admin)

1.5.2.2 VOMS database migration (MySQL backend)

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 installed and running
2. The password for the MySQL root account is properly configured (follow the instructions in this section to configure the root account password).

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

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

1.6 Troubleshooting

See the VOMS known issues page.

-- AndreaCeccanti - 2012-03-03