Please note: This documentation is for OSG 1.2. While we still provide critical security updates for OSG Software 1.2, we recommend you use OSG Software 3 for any new or updated installations. We are considering May 31, 2013 as possible OSG 1.2 End of Life (EOL).

ReleaseDocumentation
VomrsInstallGuide
Owner StevenTimm
Area VO
Role SysAdmin
Type Installation
Reviewer TerrenceMartin Tester MarcoMambelli Owner StevenTimm
In Progress Failed Not Released

VOMRS Installation Guide

About this Document

hand This document is VO Administrators. It describes the installation, configuration and operation of the VOMRS service.

About the Virtual Organization Management Registration Service (VOMRS)

The Virtual Organization Management Registration Service (VOMRS) is compliant with OSG Virtual Organization policy and offers a comprehensive set of services that facilitates secure and authenticated management of VO membership, grid resource authorization and privileges:

  • Implements a registration workflow providing means for collaborators to register with a Virtual Organization (VO)
  • Supports management of multiple grid certificates per member
  • Permits VO-level control of member's privileges
  • Provides email notifications of selected events
  • Keeps track of Grid and VO AUPs signed by members
  • Supports VO-level control over its trusted set of Certificate Authorities (CA)
  • Permits delegation of responsibilities within the various VO administrators
  • Manages groups and group roles
  • Is capable of interfacing to third-party systems and pulling or pushing relevant member information from/to them
  • Is synchronized with VOMS

Components

VOMRS consists of three components:

  1. MySQL database which is a persistent repository for VO membership information,
  2. VOMRS admin which provides the Web UI/services to maintain the VO membership. This requires Apache/Tomcat.
  3. VOMRS server, a daemon process which performs variety of tasks that include synchronization with VOMS, sending email notifications, managing Certificate Authorities certificates within VOMRS, etc.

Also included in the installation is a VOMRS soapclient that allows to execute any webservice supported by VOMRS for testing.

When you install VOMRS, you get all three parts. VOMRS is synchronized with VOMS, so VOMS will be installed on your system as well. Please refer to VOMS Installation Guide for all issues related to VOMS.

VOMRS comes with a test VO called VDT. We suggest that you use it for testing. You're going to need to create your real VO with the appropriate name. Instructions for doing that are also on this page.

Requirements

  • a Pacman installation
  • root privileges on the installation server
  • GNU Compiler Collection
  • a http service certificate installed in /etc/grid-security/http/httpcert.pem and /etc/grid-security/http/httpkey.pem respectively

Please make sure that the /etc/hosts file contains an entry for the external FQDN of the VOMRS server separately from the localhost line, for example:

127.0.0.1 localhost.localdomain localhost
123.45.67.89 myvoms.opensciencegrid.org myvoms

VOMRS Installation Procedure

  1. create an installation directory
  2. use Pacman to install VOMRS
  3. update the environment

Create an Installation Directory

Create a directory for the installation and change into it. For simplicity in this document we'll call it /opt/vomrs.

[root@myvoms /opt/vomrs]$ mkdir /opt/vomrs

ALERT! WARNING!
You can install VOMRS in any arbitrary directory. Please don't directly use a system directory like /opt or /usr here. The installation routine will create many sub-directories in the install directory chosen.

Use Pacman to install VOMRS

[root@myvoms /opt/vomrs]$ cd /opt/vomrs
[root@myvoms /opt/vomrs]$ pacman -get  http://software.grid.iu.edu/osg-1.2:vomrs  

[root@myvoms /opt/vomrs]$ pacman -get http://software.grid.iu.edu/osg-1.2:vomrs
Do you want to add [http://software.grid.iu.edu/osg-1.2] to [trusted.caches]? (y/n/yall): y
Do you want to add [http://vdt.cs.wisc.edu/vdt_200_cache] to [trusted.caches]? (y/n/yall): y
Beginning VDT prerequisite checking script vdt-common/vdt-prereq-check... 

All prerequisite checks are satisfied.
                                                                          
========== IMPORTANT ==========
Most of the software installed by the VDT *will not work* until you install
certificates.  To complete your CA certificate installation, see the notes
in the post-install/README file.

HELP NOTE
The installation log file can be found in /opt/vomrs/install.log

Update your Environment

[root@myvoms /opt/vomrs]$ cd /opt/vomrs
[root@myvoms /opt/vomrs]$ source setup.sh

Secure the Server

All access to VOMRS is through Apache and Tomcat. To secure your server and require only authenticated access, run the following command that redirects non-SSL traffic from localhost as well.

[root@myvoms /opt/vomrs]$ $VDT_LOCATION/vdt/setup/configure_apache --secure
/etc/init.d/apache restart
restart

Install a Certificate Authority Package

Before you proceed to install a Certificate Authority Package you should decide which of the available packages to install. Choose according to the resource group you chose earlier during the resource registration process with the OSG Information Management System:

HELP NOTE
If in doubt, please consult the policies of your home institution and get in contact with the Security Team. You may inspect and remove CA Certificates after the installation process completed!

Next decide at what location to install the Certificate Authority Package:

  1. on the local file system beneath the current installation directory /opt/vomrs
  2. on the root file system in a system directory /etc/grid-security/certificates
  3. in a custom directory that can also be shared

The instructions below illustrate each method using the Certificate Authority Package used on the Open Science Grid. Choose a package by changing the --url argument provided to vdt-ca-manage.

Local Installation of the CA Certificates

This local installation of the Certificate Authority Package is preferably be used by grid users without root privileges or if the CA certificates will not be shared by other VDT installations on the same host.

[root@myvoms /opt/vomrs]$ vdt-ca-manage setupca --location local --url osg
Setting CA Certificates for VDT installation at '/opt/vomrs'

Setup completed successfully.

After a successful installation the certificates will be installed in ($VDT_LOCATION/globus/share/certificates, /opt/vomrs/globus/share/certificates in this example).

Root Installation

This root installation of the Certificate Authority Package is preferably be used if the CA certificates will be shared by several VDT installations on the same host. This installation requires always root privileges because the CA Package is installed in a system directory.

[root@myvoms /opt/vomrs]$ vdt-ca-manage setupca --location root --url osg
Setting CA Certificates for VDT installation at '/opt/vomrs'

Setup completed successfully.

After a successful installation the certificates will be installed in /etc/grid-security/certificates.

Custom Installation

This custom installation of the Certificate Authority Package is preferably be used if the CA certificates will be shared by several VDT installations on different hosts.

[root@myvoms /opt/vomrs]$ vdt-ca-manage setupca --location /mnt/nfs --url osg
Setting CA Certificates for VDT installation at '/opt/vomrs'

Setup completed successfully.

After a successful installation the certificates will be installed in /mnt/nfs/certificates.

Provide and Install a custom CA Package

If a custom Certificate Authority certificates package was made available on a web server, it can be used to be installed using the --url option on the command line to vdt-ca-manage:

[root@myvoms /opt/vomrs]$ vdt-ca-manage setupca --location /mnt/nfs --url <url to custom CA Package>
Setting CA Certificates for VDT installation at '/opt/vomrs'

Setup completed successfully.

After a successful installation the certificates provided at the provided --url location will be installed in /mnt/nfs/certificates.

Enable Updates of the CA Certificates

CA certificates have a limited lifetime and will expire. To keep the installed certificates current it is necessary to update them automatically using the vdt-update-certs provided by the Virtual Data Toolkit:

To enable the service use:

[root@myvoms /opt/vomrs]$ vdt-control --enable vdt-update-certs
running 'vdt-register-service --name vdt-update-certs --enable'... ok

Enable Updates of the Certificate Revocation List

The Certificate Revocation List lists certificates that have been temporarily or permanently revoked. To keep the CRL current it is necessary to update it automatically using fetch-crl provided by the Virtual Data Toolkit:

[root@myvoms /opt/vomrs]$ vdt-control --enable fetch-crl
running 'vdt-register-service --name vdt-update-certs --enable'... ok

Service Activation and Deactivation

Enable Services

Before a service can be activated it needs to be enabled. You can list the status of registered services to see if a service is enabled or disabled.

To enable a registered service use vdt-control:

[root@myvoms /opt/vomrs]$ vdt-control --enable vomrs

Disable Services

Disable a service to remove it from the list of services that can be activated or deactivated

To disable a registered service use vdt-control:

[root@myvoms /opt/vomrs]$ vdt-control --disable vomrs

Service Activation

Use vdt-control to activate registered services. This will:

  • add entries to crontab for cron services
  • add control scripts to /etc/init.d for init services
  • start new init services
  • configure the xinet daemon for xinet services

Unprivileged users must provide the --non-root argument to vdt-control to install cron services. All other services require root privileges.

[root@myvoms /opt/vomrs]$ vdt-control --on vomrs

vdt-control will fail to activate any service that is already provided by the operating system. In this case you may force the activation of the new service provided by the Virtual Data Toolkit:

[root@myvoms /opt/vomrs]$ vdt-control --force --on vomrs

Another reason for vdt-control to fail to activate a service may be that the service was previously installed by another installation of the Virtual Data Toolkit which has not been deactivated yet. In this case you must force the deactivation of the existing service before you continue to install the new service:

[root@myvoms /opt/vomrs]$ vdt-control --force --off vomrs
[root@myvoms /opt/vomrs]$ vdt-control --on vomrs

Service Deactivation

Use vdt-control to deactivate registered services. This will:

  • remove entries from crontab for cron services
  • stop init services
  • remove control scripts from /etc/init.d for init services
  • re-configure the xinet daemon for xinet services

Unprivileged users must provide the --non-root argument to vdt-control to uninstall cron services. All other services require root privileges.

[root@myvoms /opt/vomrs]$ vdt-control --off vomrs

vdt-control may fail to deactivate all services due to hanging processes. In this case expect the process table and kill hanging processes manually.

Software and Services

VOMRS Provided Software

Use the vdt-version program to get a detailed list of software packages that have been installed:

[root@myvoms /opt/vomrs]$ vdt-version

[root@myvoms /opt/vomrs]$ vdt-version

You have installed a subset of VDT version 2.0.0p27:

Software                                                 Status              
--------                                                 ------              
Apache HTTPD 2.2.17                                      OK                  
vdt-ca-manage 1.3                                        OK                  
vdt-update-certs 2.6                                     OK                  
CA Certificates 1.17 (includes IGTF 1.38 CAs)            -                   
Fetch CRL 2.8.5                                          OK                  
GPT 3.2-4.0.8p1                                          OK                  
Java 6 SDK 1.6.0_23                                      OK                  
Logrotate 3.7                                            OK                  
MySQL 5.0.92                                             OK                  
MySQL Connector/J 5.0.8                                  OK                  
Apache Tomcat 5.5.32                                     OK                  
VOMRS 1.3.4a                                             OK                  
VOMS Admin 2.0.15-1                                      OK                  
VOMS Client 1.8.8-2p1                                    OK                  
VOMS Server 1.8.8-2p1                                    OK                  
Wget 1.12                                                OK                  


Status legend:
OK: Software is up to date with the latest release in VDT version 2.0.0
- : Not enough information to determine if updates are available.
Type 'man vdt-version' for more information.

List Registered Services

To see a list of services registered by the Virtual Data Toolkit use vdt-control:

[root@myvoms /opt/vomrs]$ vdt-control --list

[root@myvoms /opt/vomrs]$ vdt-control --list
Service            | Type   | Desired State
-------------------+--------+--------------
fetch-crl          | cron   | enable
mysql              | init   | enable
vdt-rotate-logs    | cron   | enable
apache             | init   | enable
tomcat-55          | init   | enable
voms               | init   | enable
vomrs              | init   | enable

The services installed and enabled are:

Service Description
apache In front of tomcat
tomcat-55 used by VOMRS WEB UI and webservices
mysql Used by VOMS and VOMRS
voms this is the voms server that services voms-proxy-init requests
vomrs vomrs server that perform notification, synchronization with voms etc

VOMRS Configuration

The configuration is done entirely using the $VDT_LOCATION/vdt/setup/configure_vomrs script. The $VDT_LOCATION/vdt-install.log contains additional log messages not shown on the command line.

Creating a VO

Use the configure_vomrs script and following arguments to create a Virtual Organization:

[root@myvoms /opt/vomrs]$ configure_vomrs 
               --server <y|n>
               --vo <name of the VO>
               --mail-from <sender address for vomrs mail>
               --smtp-host <outgoing smtp server>
               --vdt-install $VDT_LOCATION 

This will:

  1. create a MySQL database named *vomrs13_vdt*
    [root@myvoms /opt/vomrs]$ mysql -uroot
    mysql> show databases;
    +----------------+
    | Database       |
    +----------------+
    | mysql          |
    | test           |
    | vomrs13_vdt    |
    +----------------+
  2. create all VOMRS configuration files for your VO in =$VDT_LOCATION/vomrs/var/etc/vomrs_<vo_name>.
    [root@myvoms /opt/vomrs]$ ls -al $VDT_LOCATION/vomrs/var/etc/vomrs_vdt
    -rw-r--r--  1 root   root    802 Jul 31 11:10 initial.conf
    -rw-r--r--  1 root   root    607 Jul 31 11:10 log4j.properties
    -rw-r--r--  1 root   root    608 Jul 31 11:10 log4j_webui.properties
    drwxr-xr-x  2 root   root   4096 Jul 31 11:12 logs
    -rw-------  1 root   root   1014  Jul 31 11:10 member.data
    -rw-r--r--  1 root   root    258 Jul 31 11:10 vomrs_vdt.xml
    lrwxrwxrwx  1 root   root     42 Jul 31 11:10 vomrs.xsd -> /opt/vomrs/vomrs/etc/cfg/vomrs.xsd
  3. update the Apache, Tomcat and glite configuration files for the new VOMS VO
  4. restart all the necessary services

Default values applied during the configuration process can be viewed in the $VDT_LOCATION/vdt-install.log searching for 'This is vomrs-configure'.

HELP NOTE
Refer to the VOMS Installation Guide (Configuring VOMS section) to learn how to add a Virtual Organization to VOMS.

Service Activation

Use vdt-control to activate registered services. This will:

  • add entries to crontab for cron services
  • add control scripts to /etc/init.d for init services
  • start new init services
  • configure the xinet daemon for xinet services

Unprivileged users must provide the --non-root argument to vdt-control to install cron services. All other services require root privileges.

[root@myvoms /opt/vomrs]$ vdt-control --on vomrs

vdt-control will fail to activate any service that is already provided by the operating system. In this case you may force the activation of the new service provided by the Virtual Data Toolkit:

[root@myvoms /opt/vomrs]$ vdt-control --force --on vomrs

Another reason for vdt-control to fail to activate a service may be that the service was previously installed by another installation of the Virtual Data Toolkit which has not been deactivated yet. In this case you must force the deactivation of the existing service before you continue to install the new service:

[root@myvoms /opt/vomrs]$ vdt-control --force --off vomrs
[root@myvoms /opt/vomrs]$ vdt-control --on vomrs

Removing a VO

We apologize, but there exists currently no script to remove a VOMS instance. Instead perform the following steps manually:

  1. stop the VOMRS server
  2. remove the associated MySql database
  3. remove =$VDT_LOCATION/var/etc/vomrs_ directory
  4. remove context file from $VDT_LOCATION/tomcat/v55/config/Catalina/localhost/vomrs#<vo_name.xml
  5. remove the =$VDT_LOCATION/tomcat/v55/webapps/vomrs/ directory
  6. restart tomcat-55

HELP NOTE
Refer to the VOMS Installation Guide (Configuring VOMS section) to learn how to remove a Virtual Organization from VOMS.

Add the VO Administrator

The following sub-sections will reference the default VDT VO in the text and examples. Please remember to use your real VO when executing the procedure.

Add the first VO Member

The first member of a Virtual Organization is a designated as a VO Administrator for the VOMRS VO created earlier. This member has administrative rights within VOMRS that a normal VO member will not have.

Choose among the two possibilities below to add the first member to the VO. Only the first member of a VO can be added the way described below.

  1. If the member has a valid grid user certificate:
    [root@myvoms /opt/vomrs]$ $VDT_LOCATION/vomrs/sbin/add_admin 
              --vo <your VO>
              --firstname <Member's First Name>
              --lastname <Member's Last Name> 
              --phone <Member's Work Phone>
              --org <Member's Organization>
              --file <members usercert.pem file>
  2. otherwise:
    [root@myvoms /opt/vomrs]$ $VDT_LOCATION/vomrs/sbin/add_admin
              --vo <your VO>
              --firstname <Member's First Name>
              --lastname <Member's Last Name> 
              --phone <Member's Work Phone>
              --org <Member's Organization>
              --nousercert  
              --dn "<Member's Distinguished Name>"
              --ca "<Member's Certificate Authority>"

Verifying the Administrative Rights of the first Member

This step requires the grid user certificate of the first member to be imported into the web browser you are using for the test.

  1. Point a certificate-enabled web browser window to https://myvoms.opensciencegrid.org:8443/vomrs/VDT/vomrs
  2. In order to expend menu click on [+], to collapse click on [-]
  3. Click on Members in order to see all members of the VO
  4. Select Search. You should see just one entry - yours.

Please refer to the VOMRS User Guide for further information

VOMRS Service Verification

If all the required certificates were in place prior to the Pacman installation, a default VO called VDT has been created in VOMRS and VOMS.

List Registered Services

To see a list of services registered by the Virtual Data Toolkit use vdt-control:

[root@myvoms /opt/vomrs]$ vdt-control --list

The output should be comparable to:

Service            | Type   | Desired State
-------------------+--------+--------------
fetch-crl          | cron   | enable
mysql              | init   | enable
vdt-rotate-logs    | cron   | enable
apache             | init   | enable
tomcat-55          | init   | enable
voms               | init   | enable
vomrs              | init   | enable

If any of the services in the list show disable then enable them as instructed in the Enabling Services section above.

HELP NOTE
For the Virtual Data Toolkit version 2.0.0 and earlier the VOMS and VOMRS services will only be enabled after successful VOMRS Service Configuration and VOMS Service Configuration respectively.

Verify the Apache/Tomcat Daemon

Verify that the apache daemon is running with ppid=1 as its parent pid and that and that the path contains your current $VDT_LOCATION:

[root@myvoms /opt/vomrs]$ ps -efwww | grep  apache | grep httpd
root     ... /opt/vomrs/apache/bin/httpd 
                    -d /opt/vomrs/apache -k start -f /opt/vomrs/apache/conf/httpd.conf
daemon   ... /opt/vomrs/apache/bin/httpd 
                    -d /opt/vomrs/apache -k start -f /opt/vomrs/apache/conf/httpd.conf

Verify that VOMRS is running under Tomcat 5.5 and VOMS is running under Tomcat 5; both with ppid=1 as their parent pids and that and that the pathes contain your current $VDT_LOCATION:

[root@myvoms /opt/vomrs]$ ps -efwww | grep tomcat
daemon   ... /opt/vomrs/jdk1.5/bin/java -server -Xmx256M -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager 
                -Djava.util.logging.config.file=/opt/vomrs/tomcat/v55/conf/logging.properties 
                -Djava.endorsed.dirs=/opt/vomrs/tomcat/v55/common/endorsed 
                -classpath :/opt/vomrs/tomcat/v55/bin/bootstrap.jar:/usr/local/osg-vomrs/tomcat/v55/bin/commons-logging-api.jar 
                -Dcatalina.base=/opt/vomrs/tomcat/v55 
                -Dcatalina.home=/opt/vomrs/tomcat/v55 
                -Djava.io.tmpdir=/opt/vomrs/tomcat/v55/temp org.apache.catalina.startup.Bootstrap start

daemon   ... /opt/vomrs/jdk1.4/bin/java            
                  -Djava.endorsed.dirs=/opt/vomrs/tomcat/v5/common/endorsed 
                  -classpath /opt/vomrs/jdk1.4/lib/tools.jar:/opt/vomrs/tomcat/v5/bin/bootstrap.jar:/opt/vomrs/tomcat/v5/bin/commons-logging-api.jar      
                  -Dcatalina.base=/opt/vomrs/tomcat/v5 -Dcatalina.home=/opt/vomrs/tomcat/v5 
                  -Djava.io.tmpdir=/opt/vomrs/tomcat/v5/temp org.apache.catalina.startup.Bootstrap start

Verify the MySQL Daemon

MySql is used to provide persistent storage of the VOMS VO membership data. Verify that MySQL is running with ppid=1 as its parent pid:

[root@myvoms /opt/vomrs]$ ps -efwww | grep mysql
root    ... /bin/sh /opt/vomrs/mysql/real-bin/mysqld_safe 
                   --defaults-file=/opt/vomrs/mysql/var/my.cnf 
                   --datadir=/opt/vomrs/vdt-app-data/mysql/var
                   --pid-file=/opt/vomrs/vdt-app-data/mysql/var/cms-xen3.fnal.gov.pid

Verify the Operation of the VOMRS Web Interface

This step requires a grid user certificate to be imported into the web browser you are using for the test.

  1. Point a certificate-enabled web browser window to https://myvoms.opensciencegrid.org:8443/vomrs/VDT/vomrs
    • You should get a Welcome to the VDT VO Registration Service! page
  2. In the left hand menu under VDT Registration Home, select Registration (Phase I).
    • The registration page should say There are no Representative with Approved Status. Can not register! Please try again later!. This is correct because there are no members in this Virtual Organization who could approve your registration.
  3. Go Back twice in your browser to return to the main page.
  4. Click Required Personal Information.
    • It should show you the list of default personal information that is collected by this VO. You should be able to modify it later when you become a VO Administrator.

At this point, you know your VOMRS WEB UI is functional.

Verify the VOMRS Server Daemon

The VOMRS server's performs multiple tasks that include email notification and synchronization with VOMS. To verify the VOMRS server is running:

[root@myvoms /opt/vomrs]$ service vomrs status
Status VORegistrationServer(vdt): Running...pid=31126      [  OK  ]

or

[root@myvoms /opt/vomrs]$ ps -ef | grep vomrs
root  ... java -Dfnal.vox.vomrs.server.mail=send fnal/vox/vomrs/server/VORegistrationServer /opt/vomrs/var/etc/vomrs_vdt/vomrs.xml

HELP NOTE
There is one VOMRS server for each VO.

Verify that the Web Service is Accessible

[root@myvoms /opt/vomrs]$ $VDT_LOCATION/vomrs/client/bin/vomrs_soapclient <FQDN of the VOMRS Server> 8443 vomrs/<VO Name> getCAs
...
- Client CN=http/osg-ress-3.fnal.gov, OU=Services, DC=doegrids, DC=org accepted
/C=AM/O=ArmeSFo/CN=ArmeSFo CA
/C=AT/O=AustrianGrid/OU=Certification Authority/CN=Certificate Issuer
/C=AU/O=APACGrid/OU=CA/CN=APACGrid/Email=camanager@vpac.org
/C=BE/O=BELNET/OU=BEGrid/CN=BEGrid CA/Email=gridca@belnet.be
/C=BR/O=ICPEDU/O=UFF BrGrid CA/CN=UFF Brazilian Grid Certification Authority
/C=CA/O=Grid/CN=Grid Canada Certificate Authority
....

In order to create your own VOMRS instance follow the instructions provided in VOMRS Configuration.

Comments

Currently in vdt-2.0.0, the voms and vomrs services do not show up in the list<br />of services when you do vdt-control --list. We are investigating why that is. S. Timm<br /> StevenTimm 06 Jul 2011 - 18:47
This document currently does not give any information on which certificates are needed, <br />i.e., host or http, and who they should be readable by, that should be added. StevenTimm 06 Jul 2011 - 18:52
PM2RPM?_TASK = NORPM RobertEngel 28 Aug 2011 - 05:21

Topic revision: r32 - 15 Feb 2012 - 21:00:27 - KyleGross
Hello, TWikiGuest
Register

Introduction

Installation and Update Tools

Clients

Compute Element

Storage Element

Other Site Services

VO Management

Software and Caches

Central OSG Services

Additional Information

Community
linkedin-favicon_v3.icoLinkedIn
FaceBook_32x32.png Facebook
campfire-logo.jpgChat
 
TWIKI.NET

TWiki | Report Bugs | Privacy Policy

This site is powered by the TWiki collaboration platformCopyright by the contributing authors. All material on this collaboration platform is the property of the contributing authors..