VOMS services configuration reference

For VOMS 2.0.16, VOMS Admin server 3.8.1, VOMS Admin client 2.0.21

Table of contents

• VOMS Configuration files
• VOMS server configuration
  • /etc/sysconfig/voms
  • VOMS Server VO configuration
• VOMS Admin configuration
  • /etc/sysconfig/voms-admin
  • Container configuration
  • VOMS Admin VO configuration
  • CERN HR plugin configuration
• Configuration utilities
• Information system configuration
• Troubleshooting

VOMS 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

VOMS server configuration

/etc/sysconfig/voms

This file contains variables needed by startup scripts to properly execute the VOMS service

VOMS server VO configuration

The VOMS server configuration for a VO can be found in /etc/voms/VO_NAME and is composed of two files:

• voms.conf containing the server configuration
• voms.pass containing the password used to access the database

/etc/voms/vo/voms.conf

The server configuration file is a text file containing a series of command line options that is parsed by the VOMS daemon at startup time. Check the VOMS man page for more information, using the following command:

man voms

An example VOMS configuration file:

--x509_user_cert=/etc/grid-security/vomscert.pem
--x509_user_key=/etc/grid-security/vomskey.pem
--dbname=voms_mysql
--contactstring=localhost
--username=voms-admin
--logfile=/var/log/voms/voms.mysql
--loglevel=4
--logtype=7
--passfile=/etc/voms/mysql/voms.pass
--port=18001
--code=18001
--sqlloc=/usr/lib64/libvomsmysql.so
--vo=mysql
--uri=wilco.cnaf.infn.it:18001
--timeout=86400
--socktimeout=60
--max-reqs=50

Special configuration flags:

/etc/voms/vo/voms.pass

This is a text file containing the password used by the VOMS server to connect to the database.

VOMS Admin configuration

/etc/sysconfig/voms-admin

This file contains variables needed by startup scripts to properly execute the VOMS Admin services

Container configuration

VOMS Admin container configuration can be found in the /etc/voms-admin directory. The container configuration consists of two files:

• voms-admin-server.properties
• voms-admin-server.logback

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

This is a standard Java properties file.

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

This is logback configuration file, which controls the logging to the following files:

• /var/log/voms-admin/server.log (server messages)
• /var/log/voms-admin/server-authn.log (authentication-related messages)

For more information about logback configuration syntax, check the logback documentation.

To change the verbosity of the authentication-related messages, for instance to get more information about certificate-related issues, change the level for the CANLListener logger from INFO to DEBUG as follows:

<configuration>
	...
	<logger name="org.italiangrid.utils.https.impl.canl.CANLListener" level="DEBUG" additivity="false">
	       <appender-ref ref="AUTHN" />
	</logger>
	<root level="INFO">
	       <appender-ref ref="FILE" />
	</root>	
</configuration>

VO configuration

VOMS Admin configuration files can be found in /etc/voms-admin/VO_NAME for a given VO.

The following files control the configuration of a given VO:

• service.properties: the main VO configuration file
• database.properties : contains credentials and settings for accessing the database
• logback.xml : the VO logging configuration
• vo-aup.txt : the text of the default VO AUP
• vomses: this file contains the vomses configuration displayed by the VOMS Admin webapp configuration page
• lsc : this file contains the lsc configuration displayed by the VOMS Admin webapp configuration page

All the options described below can be set using the voms-configure script.

/etc/voms-admin/vo/service.properties

This is a Java properties file.

Base service options

Notification settings

Membership validation settings

Registration service options

AUP options

SAML Attribute authority options

Caching options

Other options

/etc/voms-admin/vo/database.properties

Look at the Hibernate documentation for more detailed information about these properties.

Database connection pool settings

Look at the c3p0 documentation to know about connection pool tuning.

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

This is logback configuration file. For more information about logback configuration syntax, check the logback documentation.

By default all log messages for a VO will go to /var/log/voms-admin/voms-admin-VO_NAME.log.

This file is well commented, and explains how to change log levels for separate parts of the VOMS Admin service.

An example configuration file is listed below:

<configuration>
    <!--
        This logger controls the MAIN voms admin log messages. Set the level to DEBUG 
        for maximum detail.  
     -->
    <logger name="org.glite.security.voms.admin" level="INFO" />
    <!--
         This logger controls the main validation service VOMS Admin log messages.
         Set the level to DEBUG for maximum detail.
    -->
    <logger name="org.glite.security.voms.admin.core.validation" level="DEBUG"/>
    
    <!-- 
        This logger controls the log messages produced when exceptions are raised by a call to the voms admin
        web services. Set the level to DEBUG for maximum detail.  
     -->
    <logger
        name="org.glite.security.voms.admin.service.ServiceExceptionHelper"
        level="DEBUG" />
    
    <!-- 
        The loggers below control the amount of logging produced by the main frameworks used by voms admin. Normally
        you shouldn't change the defaults listed here.
     -->
    <logger name="org.opensaml" level="ERROR" />
    
    <!-- 
        Set the level to INFO (or DEBUG) for the hibernate logging if you want to have more detailed log messages regarding
        the persistence management in voms-admin.
     -->
    <logger name="org.hibernate" level="ERROR" />
    
    <logger name="org.apache.struts2" level="WARN" />
    <logger name="com.opensymphony.xwork2" level="WARN" />
    <logger name="com.opensymphony.xwork2.config.providers.XmlConfigurationProvider" level="ERROR" />
    
    <!-- NORMALLY YOU SHOULD NOT EDIT BELOW THIS POINT  -->
    <appender name="FILE"
        class="ch.qos.logback.core.rolling.RollingFileAppender">
        <File>/var/log/voms-admin/voms-admin-${voms.vo.name}.log</File>
        <rollingPolicy
            class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <FileNamePattern>/var/log/voms-admin/voms-admin-${voms.vo.name}-%d{yyyy-MM-dd}.log</FileNamePattern>
        </rollingPolicy>

        <encoder>
            <pattern>%date{yyyy-MM-dd HH:mm:ss.SSS'Z',UTC} - %level [%logger{0}] - %msg%n</pattern>
        </encoder>
    </appender>    
    
    <root level="WARN">
        <appender-ref ref="FILE" />
    </root>
    
</configuration>

CERN HR plugin configuration

The VOMS HR plugin provides integration with the CERN Human Resource database (aka OrgDB).

When the CERN HR integration is active:

• registration requests are validated so that only applicants present in the experiment in the HR database can apply for VO membership.
• VO membership expiration time is linked to the HR membership expiration.

A periodic background task keeps the information in VOMS in sync with the information in the HR.

The CERN HR db plugin replaces the former OrgbDB plugin. This plugin integrated with a REST API services in front of the HR database, while the OrgDB plugin connected directly to the CERN Oracle database.

Enabling the HR plugin

The plugin configuration is currently not supported by voms-configure.

Assuming the VO for which the OrgDB plugin must be enabled is already configured, you will need to do the following changes to the configuration:

• Edit the /etc/voms-admin/<vo-name>/service.properties file for the VO to enable the plugin.
• Create the file /etc/voms-admin/<vo-name>/hr.properties that will hold the plugin configuration.

Changes to the service.properties file

Add the following lines at the bottom of the service.properties file:

## External validation plugin options
voms.external-validators = orgdb
voms.ext.orgdb.configClass = org.glite.security.voms.admin.integration.cern.HrDbConfigurator

The hr.properties configuration file

The hr.properties defines the configuration for the HR plugin.

# The experiment name.
experiment=atlas

# How frequently the check is run (in seconds). Default: 43200
membership_check.period=43200

# Should the membership check be enabled. Default: true
membership_check.enabled=true/false

# At what time should the first hr sync be triggered ? Default: 23
membership_check.start_hour=23

# When true triggers an hr sync 5 mins after startup (I'd set this to
# false in production) Default: true
membership_check.run_at_startup=true/false

So if in production you want the sync to run every 12h starting at 2 in the morning, the right configuration is:

membership_check.enabled=true
membership_check.start_hour=2
membership_check.run_at_startup=false

Other configuration utilities

voms-mysql-util

The voms-mysql-util command is used for the creation or removal of the database that will host the VOMS services tables on a MySQL database backend. This command does not create the VOMS tables. This is done by the voms-db-util command, which is described below. As voms-mysql-util is invoked internally by voms-configure normally system administrators do not use it, but it can sometimes be of help.

The general invocation is

voms-mysql-util COMMAND OPTIONS

Available options are:

• create_db creates a MySQL database and grants read and write access
• drop_db drops a MySQL database
• grant_rw_access grants read and write access to a user
• grant_ro_access grants read-only access to a user

The options are described in the following table

voms-db-util

The voms-db-util command is used to manage the deployment and upgrade of the VOMS database tables, and to add/remove administrators without requiring VOMS Admin VOs to be active. As voms-db-util is invoked internally by voms-configure normally system administrators do not use it, but it can sometimes be of help.

The general invocation is

voms-db-util COMMAND [OPTIONS]

The commands for installing or removing the database are

• check-connectivity check whether the database can be contacted
• deploy deploys the database for a given VO
• undeploy undeploys the database for a given VO
• upgrade upgrades the database for a given VO

The commands for adding or removing administrators are

• add-admin creates an administrator with full privileges for a given VO
• remove-admin removes an administrator from a given VO
• grant-read-only-access creates ACLs so that VO structure is readable for any authenticated user

The options are described in the following table

voms-vo-ctl

The voms-vo-ctl command, introduced with the CENTOS7 release, is used to manage the deployment of VOs for the voms-admin service.

# voms-vo-ctl --help
Usage: /usr/sbin/voms-vo-ctl {list|deploy|undeploy}

Information system  

BDII  

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