System Administrator guide
- Introduction
- Prerequisites and recommendations
- Upgrade instructions
- Installation instructions
- Configuration instructions
- Service operation
- Service migration
- Troubleshooting
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- CPU: No specific requirements
- Memory: 2GB if serving <= 15 VOs, more otherwise
- Disk: 10GB free space (besides OS and EMI packages)
- NTP Time synchronization: required.
- Host certificates: required
- Networking
- Open ports : see the Service reference card
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.rpmAll 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.
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 instructionsThe upgrade from gLite 3.2 is not supported. Upgrade to EMI 1 or 2 and then upgrade to the latest VOMS release.
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
Follow the general EMI 3 installation instructions for installing the EMI-3 repositories.
Before upgrading, stop the running VOMS services issuing the following commands
service voms stop
service voms-admin stopand stop the tomcat service:
service tomcat5 stop (SL5)
service tomcat6 stop (SL6)Run the following commands:
yum clean all
yum updateThis 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_LOCATIONand remove any reference to the above environment variables from the file /etc/profile.d/grid-env.sh, which
was generated by YAIM.
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.
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
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"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 startConfiguration 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 instructionsThese are the full instructions for a clean installation. If you are upgrading, see the upgrade instructions section.
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.
Following the EMI-3 installation instructions you have installed the EGI IGTF certification authorities certificates. To update the certificate revocation lists (CRLs) for those CAs, run the fetch-crl script:
/usr/sbin/fetch-crland enable a cron job that periodically refresh CRLs on the filesystem as follows:
/sbin/chkconfig fetch-crl-cron on
/sbin/service fetch-crl-cron startPlease refer to the fetch-crl documentation for detailed configuration instructions.
Note that the fetch-crl cron job requires that the /etc/sysconfig/fetch-crl file
is present on the filesystem. You can create it with the following command:
touch /etc/sysconfig/fetch-crlInstall the emi-voms-mysql metapackage, or emi-voms-oracle depending on the database backend you are using
yum install emi-voms-mysqlVOMS is now configured only using its own configuration utility, voms-configure. YAIM configuration for this version of VOMS is not supported.
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>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
See the instructions above.
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 ciccio@cnaf.infn.it \
–-smtp-host iris.cnaf.infn.itOracle 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 VONAMEAvailable 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
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
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
EOFThe script voms-config-info-providers configures the providers for the resource bdii. Run
voms-config-info-providers -s SITENAME -egiving 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=GLUE2Serviceshould return a service for each virtual organization.
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-serpand 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 = 1Start emir-serp with
service emir-serp startand 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 = debugVOMS 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 startTo start or stop a specific VO, use the following commands:
service voms start <vo>
service voms-admin start <vo> | 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 |
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.
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.
To change the verbosity of the voms-db-util command, refer to the following logback configuration file:
/var/lib/voms-admin/tools/logback.xml
In order to migrate VOMS to a different machine, the following items will need to be migrated:
- The configuration
- 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.
To migrate VOMS configuration, archive the contents of the following directories and move the archive to the new installation:
/etc/voms/*
/etc/voms-admin/*
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:
- mysql-server is up & running
- 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
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.