Show Children Hide Children

VOMS Server Installation and Configuration Guide

Service Overview

VOMS Admin provides an intuitive web user interface for daily administration tasks and a SOAP interface for remote clients. (The entire functionality of the VOMS Admin service is accessible via the SOAP interface.) The Admin package includes a simple command-line SOAP client that is useful for automating frequently occurring batch operations, or simply to serve as an alternative to the full blown web interface. It is also useful for bootstrapping the service. The VOMS server can use MySQL or ORACLE as a backend.

VOMS Node Installation

The general steps to install the OS and the gLite-VOMS 3.1 server are explained at: https://twiki.cern.ch/twiki/bin/view/LCG/GenericInstallGuide310

Upgrading from a gLite 3.0 VOMS Server

This section describes the necessary steps if you are migrating from a 3.0 VOMS server. Please read these instructions carefully before starting the upgrade process!

Besides switching to a new base operating system (from SL3 for the gLite 3.0 release series to SL4 for the gLite 3.1 release series), the gLite 3.1 VOMS server comes with the redesigned version 2 of VOMS-ADMIN which uses a new database schema. The old VOMS databases must therefore be upgraded for the gLite 3.1 VOMS server.

You are strongly advised to backup your database before doing the upgrade!

The database upgrade program is part of the VOMS-ADMIN 2 release and it will be automatically installed on your new server.

Also, the database upgrade will only work if you are using the latest database schema in production from the gLite 3.0 VOMS server.

You should complete successfully all database upgrades before running the VOMS configuration script (glite-voms-server-config.py).

Before proceeding with the database upgrade you should decide whether you want to keep the old database instance or if you want to create a new one. If you run VOMS 3.0 with a MySQL database backend on the same machine you will probably want to use a new database instance on the 3.1 VOMS node as the node also needs to be updated to the new OS. In this case you can copy the dumped database to the new host and then run the database upgrade script against the new instance on the new node.

Migrating the database to the new node

To migrate the database to the new node you need to do the following steps:

• Dump the old database on the old VOMS server and transfer the file to the new node

       mysqldump -h <OLD_HOSTNAME> -u <USER> -p --databases <DB_NAME> > <DUMP_FILE>

• Use the database dump on the new machine to create the new database

       mysql -h <NEW_HOSTNAME> -u <PRIV_USER> -p < <DUMP_FILE>

• Grant ALL PRIVILEGES to the user that VOMS-ADMIN will use to connect to and use the database

       mysql -h <NEW_HOSTNAME> -u <PRIV_USER> -p

       mysql> GRANT ALL PRIVILEGES ON <DATABASE_NAME> 
              TO <VOMS_USER>@localhost
              IDENTIFIED BY '<VOMS_USER_PASSWORD>';

Migrating the VOMS configuration to the new node

• Copy all configuration files *.cfg.xml from /opt/glite/etc/config on the old gLite 3.0 VOMS server node to the new node (in the same place)

• Copy recursively all subdirectories from /var/glite/etc/voms-admin named after the VOs you want to upgrade to the new node (in the same place)

• In each of these subdirectories check the voms.database.properties file. It contains the database connection parameters. Edit these on the new 3.1 server if needed (they should point to the database you want to upgrade).

• Copy the certificates of the VO administrators to the new server (pointed by the value of the voms.admin.certificate VO-level parameter)

Upgrading the database schema

Before you proceed make sure that the database is not in use by someone else as the following steps will modify the database schema! To actually upgrade the database you need to:

• Set the following variables with the appropriate values

       export GLITE_LOCATION=/opt/glite
       export GLITE_LOCATION_VAR=/var/glite
       export GLITE_LOCATION_LOG=/var/log/glite

• In each VO subdirectory located under /var/glite/etc/voms-admin check the voms.database.properties file. It contains the database connection parameters. Edit these on the new 3.1 server if needed (they should point to the database you want to upgrade).

The format of this file will change after the upgrade because VOMS-ADMIN 2 uses Hibernate as a persistence layer.

• For each VO database you want to upgrade check the table named "admins" for rows that have the same value for the column "dn". You have to remove the duplicates manually before proceeding to the next step. After importing the MySQL dump on the new MySQL 4.x server, you could use the following SQL statements to do that. First delete all rows in the admins table that have no corresponding ACL entries:

  mysql> DELETE FROM admins WHERE adminid NOT IN (SELECT adminid FROM acl);

  Then use the next query to find duplicates:

  mysql> SELECT adminid, dn, c.ca FROM admins a JOIN ca c ON a.ca = c.cid
         WHERE dn IN (SELECT dn FROM admins GROUP BY dn HAVING COUNT(*) > 1);

  If this query returns an empty set proceed with the next step. Otherwise you will have to choose which rows to remove (ACLs for the deleted users will not be migrated) and delete them with:

  mysql>DELETE FROM admins WHERE adminid = <ID>

  choosing an ID from the adminid column of the table returned by the previous SELECT

• For each VO database you want to upgrade run:

       /opt/glite/sbin/voms-admin-configure --vo=<VO_NAME> upgrade

Note: In case of an unexpected error during the upgrade of a VO, its corresponding voms.database.properties file might be left in the new format. To rerun the upgrade you will have to restore the old one manually.

Updating the configuration

You can continue to use the old configuration files but you will probably need to change the following variables:

• JAVA_HOME (in glite-global.cfg.xml)
• CATALINA_HOME (in glite-global.cfg.xml)
• tomcat.user.name (in glite-global.cfg.xml)
• tomcat.user.group (in glite-global.cfg.xml)
• fetch-crl.script (in glite-security-utils.cfg.xml) It should point to the actual location of the fetch-crl executable (normally /usr/sbin/fetch-crl on gLite VOMS 3.1 host).
• voms.db.oracleinstantclient.location (in glite-voms-server.cfg.xml if you are using Oracle as backend)
• voms.admin.certificate (per-VO parameter) Its value should be a valid path to a PEM file containing the certificate of the VO administrator.

Also make sure you are using the desired database connection parameters for the VO (in the volist.cfg.xml file)

Reconfiguring the VOMS server

Reconfigure the VOMS server by executing:

/opt/glite/etc/config/scripts/glite-voms-server-config.py --configure

Starting the VOMS server

Start the VOMS server by executing:

/opt/glite/etc/config/scripts/glite-voms-server-config.py --start

Configuring access for gridmap file generation

This step needs an appropriate environment being set up for running the voms-admin CLI on the voms host. This can be done either by running:

[root@vomshost: ~] # . /etc/glite/profile.d/glite_setenv.sh

or by restarting the shell session with the server (It is loaded automatically for new sessions with the VOMS host).

For successful gridmap file generation on the relevant grid hosts, the appropriate access rights should be granted for each VO. This can be done via the voms-admin command line interface. The following command grants the necessary rights to the predefined user “Anyone” (any user that presents a valid certificate issued by a trusted CA) for the top group “/” and its descendants (the TRUE flag triggers recursive operation).

voms-admin --vo=<VO_NAME> --nousercert add-ACL-entry /<VO_NAME> ANYONE VOMS_CA 'CONTAINER_READ,MEMBERSHIP_READ' TRUE

Registration of the VOMS host identity as a default admin

This step should be performed only if the VOMS host will have a new hostname or for any reasons the subject of its host certificate differs from the one that was installed on the gLite VOMS 3.0 host. For each VO, execute the following command on the VOMS host:

/opt/glite/sbin/voms-db-deploy.py add-admin --vo <VO_NAME> --cert /etc/grid-security/hostcert.pem

Verification of the ACL configuration

VOMS-ADMIN 2 has a redesigned security model. The global ACL is now deprecated. If you had set up custom ACEs in VOMS-ADMIN 1, inspect the ACLs of the groups hierarchy after the upgrade is complete. Consult the VOMS-ADMIN-2 Users guide on how the access control mechanism works in the new version.

VOMS Server Configuration

If you upgrade from the gLite 3.0 version, please follow the instructions above.

Configuring the database backend

Configure MySQL (if you use MySQL as backend)

Make sure that the MySQL administrator password that you have specified in the configuration file matches the password that is set in the MySQL database. The configuration script does not set it for you. If you want to set a MySQL administrator password, you have to issue the following commands as root:

/usr/bin/mysqladmin -u root password <yourPassword>;
/usr/bin/mysqladmin -u root -h <yourHostname> password <yourPassword>;

where yourHostname is the name of your host and yourPassword is the password that you want to set.

Configure Oracle (if you use Oracle as backend)

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

Glite configuration files

The configuration files and scripts can be found in /opt/glite/etc/config

A set of template configuration files are installed into /opt/glite/etc/config/templates

The following configuration files are used:

• glite-global.cfg.xml

It contains global configuration values. Refer to the ‘Advanced Installation and Configuration Guide’ for the values that can be set and for the description about the general configuration.

• glite-security-utils.cfg.xml

It contains the security utils specific configuration values. Refer to ‘Advanced Installation and Configuration Guide’ for the list of parameters and for the description of the security utils.

• glite-voms-server.cfg.xml

It contains the VOMS server specific configuration files. Since multiple instances of the VOMS Server can be installed on the same node (one per VO), some of the parameters refer to individual instances. Each instance is contained in a separate name tag. A default instance is already defined and can be directly configured. Additional instances can be added by simply copying and pasting the section, assigning a name and changing the parameters values as desired.

Setting the Configuration values for the VOMS server

General configuration of the VOMS server

You first need to set the general configuration parameters for the VOMS server. Table 1 shows the list of parameters that can be set. You will find them in the file glite-voms-server.cfg.xml.

VO configuration

Setting up the VO configuration

To set up a VO, you have to specify the necessary configuration parameters of the VO. Normally this is done via a ‘vo-list’ file that can be put locally or remote (to share information for several services). A template of such a vo-list file is installed at

/opt/glite/etc/config/templates/vo-list.cfg.xml

However you can also put this information in the glite-voms-server.cfg.xml file via copy/paste directly. Detailed information on how to use the VO configuration can be found in the 'generic gLite v3.0 VO Configuration Guide'.

Using the vo-list file locally

To use a local vo-list file defining the set of VOs you want to support, you need to do the following steps:

• Copy the template to the configuration directory

        cp /opt/glite/etc/config/templates/vo-list.cfg.xml /opt/glite/etc/config/.

• Make the configuration files aware of the new configuration file. For this we use the standard Xinclude technique of XML. In the file glite-voms-server.cfg.xml replace the token

        <config>

        <config xmlns:xi="http://www.w3.org/2001/XInclude">

• Define the file(s) to be included by adding the following tag below (inside) the tag:

<xi:include href="/opt/glite/etc/config/vo-list.cfg.xml" xpointer="" />

Using the vo-list file remotely

To use a vo-list file remotely follow the same instructions as described in section 4.3.2.2 but add the corresponding parts in your remote configuration file.

Including the VO information in the glite-voms-server.cfg.xml file

If you want to put the information for the vo’s directly to the glite-voms-server.cfg.xml file, copy the entries from the vo-list.cfg.xml file

   <vo name="VO_NAME">
      ...
   </vo>

   <config>
      <vo name="VO_NAME">
         ...
      </vo>
      ...
   </config>

   <instance service="voms" iterate="volist">
      <parameters/>
   </instance>

   <vo name="VO_NAME">
      ...
   </vo>

./glite-voms-server-config.py -c

/opt/glite/etc/config/scripts/glite-voms-server-config.py --configure

./glite-voms-server-config.py --configure --vo=voName

/opt/glite/etc/config/scripts/glite-voms-server-config.py --start

[root@vomshost: ~] # . /etc/glite/profile.d/glite_setenv.sh

voms-admin --vo=<VO_NAME> --nousercert add-ACL-entry /<VO_NAME> ANYONE VOMS_CA 'CONTAINER_READ,MEMBERSHIP_READ' TRUE