0.0.0.0.1 Upgrading a VOMS Oracle installation

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

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

0.0.0.0.0.1 Oracle instantclient library path

/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. Configure the VOMS service with YAIM as explained in this section.

1 Introduction

• 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

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

0.2 Prerequisistes and recommendations

0.2.1 Hardware

0.0.1 Software

0.0.0.1 Operating system

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

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

0.2 Installation instruction

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

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

0.2.3 Upgrade installation

0.2.3.1 Upgrade from gLite 3.2 VOMS

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

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

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

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

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

0.2.3.1.5 Known issues for the gLite 3.2 to EMI upgrade

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

0.2.3.2 Upgrade from EMI 1 VOMS

0.2.3.2.1 Upgrading an SL5 EMI 1 installation

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

0.2.4 Configuration

0.2.4.1 Configuring the database backend

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

0.2.4.1.2 Oracle configuration

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

0.2.4.2 Configuring the VOMS server with YAIM

0.2.4.2.1 YAIM siteinfo and glite-voms example files

0.2.4.2.1.1 MySQL backend

Below is a siteinfo and service file for a VOMS mysql node configuration:

site-info.def:

MYSQL_PASSWORD="pwd"
SITE_NAME="voms-certification.cnaf.infn.it"
VOS="cert.mysql"

services/glite-voms: 

# VOMS server hostname
VOMS_HOST=cert-voms-01.cnaf.infn.it 
VOMS_DB_HOST='localhost'

VO_CERT_MYSQL_VOMS_PORT=15000
VO_CERT_MYSQL_VOMS_DB_USER=cert_mysql_user
VO_CERT_MYSQL_VOMS_DB_PASS="pwd"
VO_CERT_MYSQL_VOMS_DB_NAME=voms_cert_mysql_db

VOMS_ADMIN_SMTP_HOST=iris.cnaf.infn.it
VOMS_ADMIN_MAIL=andrea.ceccanti@cnaf.infn.it

0.2.4.2.1.2 Oracle backend

site-info.def:

VOMS_DB_TYPE="oracle"
SITE_NAME="voms-certification.cnaf.infn.it"
VOS="cert.oracle"
ORACLE_CLIENT="/usr/lib/oracle/10.2.0.4/client64"

services/glite-voms:

VOMS_HOST=cert-voms-01.cnaf.infn.it 

VOMS_ADMIN_SMTP_HOST=iris.cnaf.infn.it
VOMS_ADMIN_MAIL=andrea.ceccanti@cnaf.infn.it
VOMS_ADMIN_CERT=/root/andreacert.pem

ORACLE_CONNECTION_STRING="(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST = voms-db-02.cr.cnaf.infn.it)(PORT = 1521)))(CONNECT_DATA=(SERVICE_NAME = vomsdb2.cr.cnaf.infn.it)))"

VO_CERT_ORACLE_VOMS_PORT=15000
VO_CERT_ORACLE_VOMS_DB_USER=admin_25
VO_CERT_ORACLE_VOMS_DB_PASS=***

0.2.4.3 YAIM configuration steps

1. Take the site-info.def and services/glite-voms examples given above as a starting point for your installation.
2. Set yaim variables as specified in the VOMS YAIM configuration guide
3. Make sure mysql is running with service mysqld status. Start the service in case it's not running with the command: service mysqld start
4. Launch yaim as follows:

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

0.3 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

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.

0.3.1 Validation and monitoring

TBD

0.3.2 Migration

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.

0.0.0.1 VOMS configuration migration

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

0.0.0.1 VOMS database migration (MySQL backend)

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

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

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

0.0.0.0.1 Migrating database accounts

0.1 Troubleshooting

VOMS System Administrator Guide

Introduction

Quickstart guide

Prerequisistes and recommendations

Hardware

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

Software

Operating system

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

Preinstalled software

Depending on the database backend that your installation will use, you will need

• mysql-server
• oracle-instantclient-basic

installed on your system.

Recommended deployment scenarios

Installation instruction

Software repositories

Clean installation

Upgrade installation

Upgrade from gLite 3.2 VOMS

Upgrade from EMI 1 VOMS

Configuration

--++ Service operation

Validation and monitoring

Migration

--++ Troubleshooting

-- AndreaCeccanti - 2012-03-03