Skip to content

System Administrator guide

Jump to bottom Edit New page
Valerio Venturi edited this page May 7, 2013 · 36 revisions

Table of contents

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

 ## Prerequisites and recommendations

Hardware

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

Operating system

  • NTP Time synchronization: required.
  • Host certificates: required
  • Networking

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 (> 15) will require more memory and disk space.

## Upgrade instructions

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

Upgrade preparation

It is always a good idea to dump the contents of the VOMS database. For MySQL-based installation follow the instructions in the database migration section.

Also archive the configuration files for VOMS and VOMS-Admin, which live in the following directories:

/etc/voms
/etc/voms-admin

EMI repository configuration

Follow the general EMI 3 installation instructions for installing the EMI-3 repositories.

Upgrade

Before upgrading, stop the running VOMS services issuing the following commands

service voms stop
service voms-admin stop

and stop the tomcat service:

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

Run the following commands:

yum clean all
yum update

This will update the VOMS packages to the latest version.

You can then remove Apache Tomcat (tomcat5 or tomcat6 depending on the SL version) as it is no longer needed to run VOMS Admin.

Older versions of VOMS and VOMS Admin needed a few environment variables to be set. This is no longer true, so please unset them this command

unset VOMS_LOCATION_CONF VOMS_ADMIN_LOCATION_VAR VOMS_LOCATION VOMS_LOCATION_VAR VOMS_ADMIN_LOCATION

and remove any reference to the above environment variables from the file /etc/profile.d/grid-env.sh, which was generated by YAIM.

### Configuring the VOMS Admin container

Since version 3.0.1 VOMS Admin does not depend anymore on Tomcat but uses an embedded Jetty container for running the VO web applications. Please set the host, port and ssl information by editing the

/etc/voms-admin/voms-admin-server.properties

before reconfiguring the VOs (as explained in the following sections) or start the voms-admin server.

Configuring file limits for the VOMS Admin container

It is safe to configure the VOMS Admin container to have a reasonable limit for the number of open files that can be opened by the voms-admin process (which runs as user voms). The default file limit can be modified by editing the /etc/security/limits.conf file:

voms          soft    nofile  63536
voms          hard    nofile  63536

Configuring memory for the VOMS Admin container

The default Java VM memory configuration for the VOMS Admin container is suitable for deployments which have at max 10 VOs configured, and is set in the voms-admin init script:

VOMS_JAVA_OPTS="-Xms256m -Xmx512m -XX:MaxPermSize=512m"

In case your server will host more VOs, you should adapt the memory configuration for the container accordingly. This can be done by setting the VOMS_JAVA_OPTS variable in the /etc/sysconfig/voms-admin file. We recommend to allocate roughly 50m of heap space and 75m of permanent space per VO. For example, for 15 VOs, the memory should be configued as follows:

VOMS_JAVA_OPTS="-Xms375m -Xmx750m -XX:MaxPermSize=1125m"

Reconfiguring the VOs

The upgrade to EMI3 requires a reconfiguration of the deployed VOs. The VOs can be reconfigured using the voms-configure configuration tool (YAIM is no more suppported).

This tool is the evolution of the voms-admin-configure script, and provides access to all the VOMS and VOMS-Admin service configuration parameters. For more detailed information about the voms-configure tool, see the VOMS Admin user's guide.

The following command shows a basic reconfiguration of the VO:

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

Once the configuration is over you can restart the VOMS services:

service voms start
service voms-admin start

Reconfiguring the information system

Configuration files for voms information providers are now provided by voms. In order to properly configure the informaton provider for voms follow the instructions here.

If you wish to configure EMIR follow the instructions here.

## Clean installation instructions

These are the full instructions for a clean installation. If you are upgrading, see the upgrade instructions section.

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, run the fetch-crl script

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

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.

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

Configuring the VOMS Admin container

See the instructions above.

VOMS services configuration

Run voms-configure to configure VOs for 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 --vo <vo name> 
--dbtype mysql
--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>
--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:

voms-configure install --vo test.vo \
--dbtype mysql --createdb --deploy-database \
--dbauser root --dbapwd pwd \
--dbusername voms --dbpassword pwd \ 
--core-port 15000 \
--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 --vo <VO name> 
--dbtype oracle 
--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> 
--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

Configuration files

The VOMS server configuration lives in the /etc/voms/<VO_NAME> directory and is composed of two files:

  • voms.conf, which contains the configuration for the server
  • voms.pass, which contains the password to access the database

The VOMS Admin container configuration lives in the /etc/voms-admin directory and consists of the following files:

  • voms-admin-server.properties, which contains the main service configuration (host, port, certificates)
  • voms-admin-server.logback, which contains the logging configuration for the server

The VOMS Admin VO configuration lives in the /etc/voms-admin/<VO_NAME> direcotory and is composed of the following files:

  • service.properties, which contains the main VO configuration
  • database.properties, which contains database access and connection pool configuration for the VO
  • logback.xml, which controls logging of the VO application

Information system

BDII

Fix BDII default configuration on SL5

Run the following command to fix your BDII default configuration or you will get errors when starting the slapd service on the Scientific Linux 5 platform.

cat > /etc/sysconfig/bdii << EOF
#SLAPD_CONF=/etc/bdii/bdii-slapd.conf
SLAPD=/usr/sbin/slapd2.4
#BDII_RAM_DISK=no
EOF
Configure the info providers

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

VOMS is made of two daemons, VOMS Core and VOMS Admin.

To start and stop all 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
VOMS admin /var/log/voms-admin server.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 container level logging configuration is maintained in the file:

/etc/voms-admin/voms-admin-server.logback

while for a given VO is maintained in the file:

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

Instructions for configuring the logging can be found directly in the configuration files.

voms-db-util logging

To change the verbosity of the voms-db-util command, refer to the following logback configuration file:

/var/lib/voms-admin/tools/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.

VOMS is developed and supported by Italiangrid, a project of the Italian National Institute for Nuclear Physics (INFN).

VOMS maintenance and evolution has been co-funded by the European Commission as part of the EMI project under Grant Agreement INFSO-RI-261611.

Add a custom sidebar
Clone this wiki locally