GUMS Install Guide

1 Introduction

GUMS is a service that authorizes and maps users from their global (X.509) identity to a local (Linux user) identity. It is not a required service (some sites use the simple edg-mkgridmap to construct a grid-mapfile instead), but it is commonly used. GUMS is useful when more than one resource (Compute Element, Storage Element, etc.) needs to authorize or map users, because it helps them share data. It is particularly helpful when using gLExec at a site, because gLExec runs on every worker node and needs authorization and mapping information. GUMS is a web application that runs in Tomcat.

HELP NOTE
Starting on 11 February 2014, all OSG-issued Digicert certificates (host, service, and personal) use the SHA-2 algorithm. The GUMS software must be on a recent version to support SHA-2 certificates. Please visit our SHA-2 compliance page for more information about minimum required versions of software components.

2 About This Document

This document is intended for site administrators who want to install and configure the GUMS service.

on on

3 Requirements

3.1 Host and OS

  • A host for the GUMS service

    It is strongly recommended that GUMS be installed on a separate computer from the Compute Element, although it is possible to install both on the same computer. But for security reasons, it is best to run the authorization service separately from any resource that can run user jobs.

  • OS is Red Hat Enterprise Linux 5, 6, 7, and variants (see details...)
  • Root access

3.2 Users

The GUMS installation will create two users unless they exist already:

User Default UID Comment
mysql 27 Runs the MySQL database server, which GUMS uses
tomcat 91 Runs the Tomcat web application server, which runs GUMS

Note that if UIDs 27 and 91 are taken already but not used for the appropriate users, you will experience errors. Details...

3.3 Certificates

Certificate Certificate Owner Path to Certificate
HTTP service certificate tomcat /etc/grid-security/http/httpcert.pem
/etc/grid-security/http/httpkey.pem

3.4 Networking

For more details on overall Firewall configuration, please see our Firewall documentation.

Service Name Protocol Port Number Inbound Outbound Comment
GUMS tcp 8443 Y    

4 Installation Procedure

Install the Yum Repositories required by OSG

The OSG RPMs currently support Red Hat Enterprise Linux 5, 6, 7, and variants (see details...).

OSG RPMs are distributed via the OSG yum repositories. Some packages depend on packages distributed via the EPEL repositories. So both repositories must be enabled.

Install EPEL

  • Install the EPEL repository, if not already present. Note: This enables EPEL by default. Choose the right version to match your OS version.
    # EPEL 5 (For RHEL 5, CentOS 5, and SL 5) 
    [root@client ~]$ curl -O https://dl.fedoraproject.org/pub/epel/epel-release-latest-5.noarch.rpm
    [root@client ~]$ rpm -Uvh epel-release-latest-5.noarch.rpm
    # EPEL 6 (For RHEL 6, CentOS 6, and SL 6) 
    [root@client ~]$ rpm -Uvh https://dl.fedoraproject.org/pub/epel/epel-release-latest-6.noarch.rpm
    # EPEL 7 (For RHEL 7, CentOS 7, and SL 7) 
    [root@client ~]$ rpm -Uvh https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
    WARNING: if you have your own mirror or configuration of the EPEL repository, you MUST verify that the OSG repository has a better yum priority than EPEL (details). Otherwise, you will have strange dependency resolution (depsolving) issues.

Install the Yum priorities package

For packages that exist in both OSG and EPEL repositories, it is important to prefer the OSG ones or else OSG software installs may fail. Installing the Yum priorities package enables the repository priority system to work.

  1. Choose the correct package name based on your operating system’s major version:

    • For EL 5 systems, use yum-priorities
    • For EL 6 and EL 7 systems, use yum-plugin-priorities
  2. Install the Yum priorities package:

    [root@client ~]$ yum install PACKAGE

    Replace PACKAGE with the package name from the previous step.

  3. Ensure that /etc/yum.conf has the following line in the [main] section (particularly when using ROCKS), thereby enabling Yum plugins, including the priorities one:

    plugins=1
    NOTE: If you do not have a required key you can force the installation using --nogpgcheck; e.g., yum install --nogpgcheck yum-priorities.

Install OSG Repositories

  1. If you are upgrading from OSG 3.1 (or 3.2) to OSG 3.2 (or 3.3), remove the old OSG repository definition files and clean the Yum cache:

    [root@client ~]$ yum clean all
    [root@client ~]$ rpm -e osg-release

    This step ensures that local changes to *.repo files will not block the installation of the new OSG repositories. After this step, *.repo files that have been changed will exist in /etc/yum.repos.d/ with the *.rpmsave extension. After installing the new OSG repositories (the next step) you may want to apply any changes made in the *.rpmsave files to the new *.repo files.

  2. Install the OSG repositories using one of the following methods depending on your EL version:

    1. For EL versions greater than EL5, install the files directly from repo.grid.iu.edu:

      [root@client ~]$ rpm -Uvh URL

      Where URL is one of the following:

      Series EL6 URL (for RHEL 6, CentOS 6, or SL 6) EL7 URL (for RHEL 7, CentOS 7, or SL 7)
      OSG 3.2 https://repo.grid.iu.edu/osg/3.2/osg-3.2-el6-release-latest.rpm N/A
      OSG 3.3 https://repo.grid.iu.edu/osg/3.3/osg-3.3-el6-release-latest.rpm https://repo.grid.iu.edu/osg/3.3/osg-3.3-el7-release-latest.rpm
    2. For EL5, download the repo file and install it using the following:

      [root@client ~]$ curl -O https://repo.grid.iu.edu/osg/3.2/osg-3.2-el5-release-latest.rpm
      [root@client ~]$ rpm -Uvh osg-3.2-el5-release-latest.rpm

For more details, please see our yum repository documentation.

Install the CA Certificates: A quick guide

You must perform one of the following yum commands below to select this host's CA certificates.

Set of CAs CA certs name Installation command (as root)
OSG osg-ca-certs yum install osg-ca-certs Recommended
IGTF igtf-ca-certs yum install igtf-ca-certs
None* empty-ca-certs yum install empty-ca-certs --enablerepo=osg-empty
Any** Any yum install osg-ca-scripts

* The empty-ca-certs RPM indicates you will be manually installing the CA certificates on the node.
** The osg-ca-scripts RPM provides a cron script that automatically downloads CA updates, and requires further configuration.

HELP NOTE
If you use options 1 or 2, then you will need to run "yum update" in order to get the latest version of CAs when they are released. With option 4 a cron service is provided which will always download the updated CA package for you.

HELP NOTE
If you use services like Apache's httpd you must restart them after each update of the CA certificates, otherwise they will continue to use the old version of the CA certificates.
For more details and options, please see our CA certificates documentation.

4.1 Install and Configure GUMS

4.1.1 Install GUMS

  1. Whether installing or upgrading GUMS, please make sure to follow these instructions for updating/installing Java to work correctly with GUMS.
    Note: if you have older versions of java installed (for instance, jdk), make sure to re-run alternatives --config java and alternatives --config javac
  2. If you have an existing GUMS installation on the same host, shutdown Tomcat.
    For OSG 3.x (RPM) installs, see the shutdown instructions.
    For OSG 1.2.x (Pacman) installs: vdt-control --off tomcat-55
  3. Install the GUMS Service
    [root@client ~]$ yum install osg-gums
  4. Configure Tomcat to use GSI
    [root@client ~]$ /var/lib/trustmanager-tomcat/configure.sh

    Note: This step will overwrite your server.xml file in your tomcat configuration directory (/etc/tomcat5 on EL5, /etc/tomcat6 on EL6, or /etc/tomcat on EL7); if you are using Tomcat on this host for non-grid purposes, you may want to save the server.xml file first, run the script, then merge your own configuration back into the file.

4.1.2 Configure GUMS database

In this section, you will configure the GUMS MySQL database, either by creating a new database or by copying an existing GUMS database. Pick the appropriate subsection below for your environment.

4.1.2.1 New Installation

  1. Start the database server
    • On EL5 and EL6, this is MySQL:
      [root@client ~]$ service mysqld start
    • On EL7, this is MariaDB:
      [root@client ~]$ systemctl start mariadb
  2. Create a new GUMS database
    [root@client ~]$ /usr/bin/gums-setup-mysql-database --user gums --host localhost:3306 --password PASSWORD --template /etc/gums/gums.config.template

    Note: The password is saved in plaintext in the /etc/gums/gums.config file, so choose one that is not used elsewhere. The gums.config file should be readable only by the tomcat user, but this situation provides light security at best.

    Note: When specifying the database host with the --host option above, it is also possible to use $HOSTNAME instead of localhost, though localhost is recommended. This value corresponds to @SERVER@ in a gums.config.template file, discussed below.

    Note: Although it is possible to specify a different location for the --template or to omit the option and use the default GUMS template (at /usr/lib/gums/config/gums.config.template), neither option is typically useful for an OSG installation.

  3. Add yourself as a GUMS administrator
    [root@client ~]$ gums-add-mysql-admin 'YOUR DN'
  4. [Optional but recommended:] Apply reasonable MySQL security settings
    [root@client ~]$ /usr/bin/mysql_secure_installation

4.1.2.2 Upgrade from existing GUMS server on another host

Note for GUMS 1.4+: Since the database schema has not changed between GUMS 1.3 and 1.4, the database name continues to be GUMS_1_3. Do not rename GUMS_1_3 database references to GUMS_1_4. There was a schema change within the GUMS 1.4 series, but this happens automatically when GUMS is started - make sure the GUMS user has permission to perform schema changes. Nevertheless the database name remains GUMS_1_3 in GUMS 1.4 and GUMS 1.5.

  1. On the older host, dump the GUMS_1_3 database to a text file
    [root@client ~]$ mysqldump GUMS_1_3 > gums_1_3.sql
  2. Copy the gums_1_3.sql file from the old host to the new one
  3. Start MySQL
    [root@client ~]$ service mysqld start
    * On EL7, this is MariaDB:
    [root@client ~]$ systemctl start mariadb
  4. Load the old GUMS data into the new MySQL database
    [root@client ~]$ echo 'CREATE DATABASE IF NOT EXISTS GUMS_1_3;' | mysql
    [root@client ~]$ mysql GUMS_1_3 < gums_1_3.sql
  5. [Optional but recommended for new MySQL instances:] Apply reasonable MySQL security settings
    [root@client ~]$ /usr/bin/mysql_secure_installation

4.1.2.3 Upgrade from existing GUMS server (installed by Pacman) on the same host

Note for GUMS 1.4+: Since the database schema has not changed between GUMS 1.3 and 1.4, the database name continues to be GUMS_1_3. Do not rename GUMS_1_3 database references to GUMS_1_4. There was a schema change within the GUMS 1.4 series, but this happens automatically when GUMS is started - make sure the GUMS user has permission to perform schema changes. Nevertheless the database name remains GUMS_1_3 in GUMS 1.4 and GUMS 1.5.

  1. In one terminal, use the old installation to dump the GUMS_1_3 database to a text file
    [root@client ~]$ cd VDT_LOCATION
    [root@client ~]$ source setup.sh
    [root@client ~]$ mysqldump GUMS_1_3 > /tmp/gums_1_3.sql
  2. Shut down the old MySQL server
    [root@client ~]$ vdt-control --off mysql5
  3. Switch to another terminal (window, session, etc.) to avoid contamination from OSG 1.2.x environment variables
  4. Start the new database server
    • On EL5 and EL6, this is MySQL:
      [root@client ~]$ service mysqld start
    • On EL7, this is MariaDB:
      [root@client ~]$ systemctl start mariadb
  5. Load the old GUMS data into the new MySQL database
    [root@client ~]$ echo 'CREATE DATABASE IF NOT EXISTS GUMS_1_3;' | mysql
    [root@client ~]$ mysql GUMS_1_3 < /tmp/gums_1_3.sql
  6. Update the database schema

    There was a GUMS database schema change between the OSG 1.2.x (Pacman) and OSG 3.x (RPM) versions of GUMS. In particular, the USER table is now named USERS. You must update the GUMS_1_3 database schema before starting Tomcat

    [root@client ~]$ mysql GUMS_1_3
    mysql> RENAME TABLE USER TO USERS;
    mysql> quit
  7. [Optional but recommended for new MySQL instances:] Apply reasonable MySQL security settings
    [root@client ~]$ /usr/bin/mysql_secure_installation

4.1.3 Set Initial GUMS Configuration

In this section, you will set up an initial GUMS configuration file, either by copying in an OSG template or by copying an existing configuration from an old installation. Pick the appropriate subsection below for your environment.

4.1.3.1 New Installation

If you ran the gums-setup-mysql-database command above with the --template option, the OSG GUMS template will be used. This should have created a suitable /etc/gums/gums.config with the configuration values in this section already filled in. In that case, you can skip this section.

If you ran the gums-setup-mysql-database command above without a --template option, it created a default, pre-configured /etc/gums/gums.config file. It is almost certainly not what you want. Instead, it is recommended that you start with an OSG template for your configuration.

  1. Copy the OSG template over the default configuration file
    [root@client ~]$ cp /etc/gums/gums.config.template /etc/gums/gums.config
  2. Edit the new /etc/gums/gums.config file and change the following settings

    Note: Each placeholder occurs exactly once in the file

Search for Replace with
@USER@ The name of the MySQL GUMS user. If you followed the instructions above, this will be gums.
@PASSWORD@ The password for the MySQL gums user (see above).
@SERVER@ The name of your computer and port (e.g. localhost or my.computer:3306) .
Normally MySQL is running on the same machine as GUMS (as in the instructions above).
We highly recommend using localhost instead of the actual hostname; this will cause MySQL to use a local Unix socket instead of listening on the network, which is more secure. If you use localhost, there is no need to specify a port. In either case, the value for @SERVER@ must match the value for --host used when setting up the gums database with the gums-setup-mysql-database command, above.
@DOMAINNAME@ Your local domain, such as wisc.edu.

4.1.3.2 Existing Installation

Note for GUMS 1.4+: Since the database schema has not changed between GUMS 1.3 and 1.4, the database name continues to be GUMS_1_3. Do not rename GUMS_1_3 database references to GUMS_1_4. There was a schema change within the GUMS 1.4 series, but this happens automatically when GUMS is started - make sure the GUMS user has permission to perform schema changes. Nevertheless the database name remains GUMS_1_3 in GUMS 1.4 and GUMS 1.5.

If you are migrating from an older version of GUMS (i.e., from OSG 1.2.x), you can copy your existing gums.config file to its new location, then update it for the new version of GUMS.

  1. Copy your existing gums.config into /etc/gums/gums.config
  2. Edit /etc/gums/gums.config as follows
    • Update the MySQL username and password (if different)
    • Change the connection string for hibernate.connection.url so that the port is 3306 instead of 49xxx
    • If you're migrating from GUMS installed by pacman, change vomsServer elements to remove the services/VOMSAdmin string from each baseURL.
    • If you're migrating from GUMS installed by pacman, update the sslCAFiles attribute in the vomsServer element to identify correctly to your CA certificate files (/etc/grid-security/certificates/*.0, if you are using default settings).
  3. If you have updated GUMS from another server or from an OSG 1.2.x installation, you will need to authorize the user being used by GUMS to access the GUMS_1_3 database. Using the table above, replace values in the following command and run it
    [root@client ~]$ mysql -u root mysql
    mysql> GRANT ALL ON GUMS_1_3.* TO '@USER@'@'@SERVER@' IDENTIFIED BY '@PASSWORD@';
    mysql> FLUSH PRIVILEGES;
    mysql> quit

For convenience, you can use the following sed commands to make the changes to the vomsServer and sslCAFiles elements:

[root@client ~]$ sed -i -e "s@/services/VOMSAdmin'@'@g" gums.config.template_from_pacman
[root@client ~]$ sed -i -e "s@sslCAFiles=''@sslCAFiles='/etc/grid-security/certificates/*.0'@g" gums.config.template_from_pacman

4.1.4 Configure Log Rotation

By default, certain output is written to files named /var/log/tomcat*/catalina.YYYY-MM-DD.log without automatic cleanup of old logs. To configure log rotation and cleanup of catalina.log, follow the steps below:

  1. Choose the Tomcat directory name based on your operating system:

    If your operating system is... Then your TOMCAT DIR NAME is...
    EL6 tomcat6
    EL7 tomcat
  2. Edit /etc/tomcat*/logging.properties so that Tomcat only produces a single, undated log file:

    --- /etc/TOMCAT DIR NAME/logging.properties.orig
    +++ /etc/TOMCAT DIR NAME/logging.properties
    @@ -24,7 +24,8 @@
     
     1catalina.org.apache.juli.FileHandler.level = FINE
     1catalina.org.apache.juli.FileHandler.directory = ${catalina.base}/logs
    -1catalina.org.apache.juli.FileHandler.prefix = catalina.
    +1catalina.org.apache.juli.FileHandler.prefix = catalina
    +1catalina.org.apache.juli.FileHandler.rotatable = false
     
     2localhost.org.apache.juli.FileHandler.level = FINE
     2localhost.org.apache.juli.FileHandler.directory = ${catalina.base}/logs
    
  3. Write /etc/logrotate.d/tomcat_catalina_logs to configure logrotate:

    /var/log/TOMCAT DIR NAME/catalina.log {
        copytruncate
        weekly
        rotate 52
        compress
        missingok
        create 0644 tomcat tomcat
    }
    

5 Services

The GUMS service is actually a web application running within the Tomcat web application server. It uses the MySQL database server for storage and the Fetch CRL service to maintain each Certificate Revocation List.

5.1 Starting and Enabling Services

To start GUMS and associated services:

  1. Start the GUMS and associated services
    • You need to fetch the latest CA Certificate Revocation Lists (CRLs) and you should enable the fetch-crl service to keep the CRLs up to date:
      # For RHEL 5, CentOS 5, and SL5 
      [root@client ~]$ /usr/sbin/fetch-crl3   # This fetches the CRLs 
      [root@client ~]$ /sbin/service fetch-crl3-boot start
      [root@client ~]$ /sbin/service fetch-crl3-cron start
      # For RHEL 6, CentOS 6, and SL6, or OSG 3 _older_ than 3.1.15 
      [root@client ~]$ /usr/sbin/fetch-crl   # This fetches the CRLs 
      [root@client ~]$ /sbin/service fetch-crl-boot start
      [root@client ~]$ /sbin/service fetch-crl-cron start
      # For RHEL 7, CentOS 7, and SL7 
      [root@client ~]$ /usr/sbin/fetch-crl   # This fetches the CRLs 
      [root@client ~]$ systemctl start fetch-crl-boot
      [root@client ~]$ systemctl start fetch-crl-cron
      
      For more details and options, please see our CRL documentation.
    • Start other services:
       # For RHEL 5, CentOS 5, and SL5 
      [root@client ~]$ /sbin/service mysqld start
      [root@client ~]$ /sbin/service tomcat5 start
       # For RHEL 6, CentOS 6, and SL6  
      [root@client ~]$ /sbin/service mysqld start
      [root@client ~]$ /sbin/service tomcat6 start
       # For RHEL 7, CentOS 7, and SL7 
      [root@client ~]$ systemctl start mariadb
      [root@client ~]$ systemctl start tomcat
      
  2. [Optional but recommended:] Enable services so that they start automatically when your system is powered on
    • To enable the fetch-crl service to keep the CRLs up to date after reboots:
      # For RHEL 5, CentOS 5, and SL5 
      [root@client ~]$ /sbin/chkconfig fetch-crl3-boot on
      [root@client ~]$ /sbin/chkconfig fetch-crl3-cron on
      # For RHEL 6, CentOS 6, and SL6, or OSG 3 _older_ than 3.1.15 
      [root@client ~]$ /sbin/chkconfig fetch-crl-boot on
      [root@client ~]$ /sbin/chkconfig fetch-crl-cron on
      # For RHEL 7, CentOS 7, and SL7 
      [root@client ~]$ systemctl enable fetch-crl-boot
      [root@client ~]$ systemctl enable fetch-crl-cron
      
    • Enable other services:
      # For RHEL 5, CentOS 5, and SL5 
      [root@client ~]$ /sbin/chkconfig mysqld on
      [root@client ~]$ /sbin/chkconfig tomcat5 on
      # For RHEL 6, CentOS 6, and SL6 
      [root@client ~]$ /sbin/chkconfig mysqld on
      [root@client ~]$ /sbin/chkconfig tomcat6 on
      # For RHEL 7, CentOS 7, and SL7 
      [root@client ~]$ systemctl enable mariadb
      [root@client ~]$ systemctl enable tomcat
      

5.2 Stopping and Disabling Services

To stop GUMS, stop it and associated services in the opposite order from which you started them:

  1. Stop the GUMS and associated services:
    • Stop main services:
      # For RHEL 5, CentOS 5, and SL5 
      [root@client ~]$ /sbin/service tomcat5 stop
      [root@client ~]$ /sbin/service mysqld stop
      # For RHEL 6, CentOS 6, and SL6 
      [root@client ~]$ /sbin/service tomcat6 stop
      [root@client ~]$ /sbin/service mysqld stop
      # For RHEL 7, CentOS 7, and SL7 
      [root@client ~]$ systemctl stop tomcat
      [root@client ~]$ systemctl stop mariadb
      
    • (other grid service running on the machine may still use it) To stop fetch-crl:
      # For RHEL 5, CentOS 5, and SL5 
      [root@client ~]$ /sbin/service fetch-crl3-boot stop
      [root@client ~]$ /sbin/service fetch-crl3-cron stop
      # For RHEL 6, CentOS 6, and SL6, or OSG 3 _older_ than 3.1.15 
      [root@client ~]$ /sbin/service fetch-crl-boot stop
      [root@client ~]$ /sbin/service fetch-crl-cron stop
      # For RHEL 7, CentOS 7, and SL7 
      [root@client ~]$ systemctl stop fetch-crl-boot
      [root@client ~]$ systemctl stop fetch-crl-cron
      
      For more details and options, please see our CRL documentation.
  2. Stop services from starting when the system is powered on:
    • Disable the main services:
      # For RHEL 5, CentOS 5, and SL5 
      [root@client ~]$ /sbin/chkconfig mysqld off
      [root@client ~]$ /sbin/chkconfig tomcat5 off
      # For RHEL 6, CentOS 6, and SL6 
      [root@client ~]$ /sbin/chkconfig mysqld off
      [root@client ~]$ /sbin/chkconfig tomcat6 off
      # For RHEL 7, CentOS 7, and SL7 
      [root@client ~]$ systemctl disable mariadb
      [root@client ~]$ systemctl disable tomcat
      
    • (other grid service running on the machine may still use it) To disable the fetch-crl service:
      # For RHEL 5, CentOS 5, and SL5 
      [root@client ~]$ /sbin/chkconfig fetch-crl3-boot off
      [root@client ~]$ /sbin/chkconfig fetch-crl3-cron off
      # For RHEL 6, CentOS 6, and SL6, or OSG 3 _older_ than 3.1.15 
      [root@client ~]$ /sbin/chkconfig fetch-crl-boot off
      [root@client ~]$ /sbin/chkconfig fetch-crl-cron off
      # For RHEL 7, CentOS 7, and SL7 
      [root@client ~]$ systemctl disable fetch-crl-boot
      [root@client ~]$ systemctl disable fetch-crl-cron
      

6 Validating GUMS

This section is optional, but if you would like to verify that your GUMS installation and configuration are good, consider using some or all of the sections below.

6.1 Connect to the GUMS web page

Connect to https://HOSTNAME:8443/gums/ to use your GUMS instance. You must have the certificate that you used for gums-add-mysql-admin above loaded in your browser. You should see the GUMS web page load.

HELP NOTE
Javascript must be enabled in order to make any configuration changes on the web interface.

If you do not see it load, check a few things:

For OSG 3.x (RPM) installs on EL5 systems

  • Look for errors in /var/log/tomcat5/catalina.out and /var/log/tomcat5/catalina.err.
  • Look for errors in /var/log/tomcat5/trustmanager.log. There are likely to be CRL errors in this file, this can be ignored unless all your CA's get CRL errors in which case you should check to make sure that your CRL updates are running correctly.

For OSG 3.x (RPM) installs on EL6 systems

  • Look for errors in /var/log/tomcat6/catalina.out and /var/log/tomcat6/catalina.err.
  • Look for errors in /var/log/tomcat6/trustmanager.log. There are likely to be CRL errors in this file, this can be ignored unless all your CA's get CRL errors in which case you should check to make sure that your CRL updates are running correctly.

For OSG 3.x (RPM) installs on EL7 systems

  • Look for errors in /var/log/tomcat/catalina.*.log
  • Look for errors in /var/log/tomcat/trustmanager.log. There are likely to be CRL errors in this file, this can be ignored unless all your CA's get CRL errors in which case you should check to make sure that your CRL updates are running correctly.

For all systems

  • Ensure that you have an http certificate in /etc/grid-security/http/httpcert.pem and /etc/grid-security/http/httpkey.pem. Make sure it is readable by the tomcat user. Permissions should be as follows:
    # ls -l /etc/grid-security/http/
    total 8
    -r--r--r-- 1 tomcat tomcat 1671 Jul  2 15:54 httpcert.pem
    -r-------- 1 tomcat tomcat 1675 Jul  2 15:54 httpkey.pem

If you change the permissions/ownership, make sure to restart tomcat so that your changes take effect.

6.2 Check accounts

After you connect to the GUMS web page, go to the Summary tab to check the configuration. You should see several dozen OSG VOs listed.

In the Account column on the summary page, you will see the local Unix user accounts that these VO users will be mapped to. It is critical that these accounts exist on the gatekeeper and worker nodes at your site. If they do not, there will be errors when users attempt to access your site.

6.3 Update VO members list

GUMS contacts each VOMS server to update its knowledge of VO membership every 6 hours. After installing or updating GUMS, you should trigger the update manually by going to the Update VO Members tab, and clicking update.

You can track the progress of the update process by watching a log file:

#For OSG 3.x (RPM) installs on EL5 systems
[root@client ~]$ tail -f /var/log/tomcat5/gums-service-admin.log
#For OSG 3.x (RPM) installs on EL6 systems
[root@client ~]$ tail -f /var/log/tomcat6/gums-service-admin.log
#For OSG 3.x (RPM) installs on EL7 systems
[root@client ~]$ tail -f /var/log/tomcat/gums-service-admin.log

With so many VOMS servers in the OSG config, several member updates may fail for various reasons (e.g., host down "connect timed out", bad or expired host certificates, etc.). Unfortunately, this situation is normal. Typically, you will see about 5 or 6 failed updates, with the rest succeeding. The update will take a while and then should display any errors that occurred during the updates. To get more details or track the update process in real time, look at /var/log/gums-service-admin.log.

6.4 Map a known good user DN

  1. Go to Map Grid Identity to Account tab: https://HOSTNAME:8443/gums/map_grid_identity_form.jsp
  2. Fill in the required info. Service DN means the DN of the host certificate of your CE (see above). Use the DN of a user (probably yourself) who you know belongs to a particular VO. Fill in the VO name in the VOMS FQAN field.
  3. Click "map user". A failed mapping will display "null". A successful mapping will display a UNIX account name.

7 Miscellaneous Procedures

7.1 Forcing GUMS to update the set of users

GUMS automatically contacts each VOMS server every 6 hours to update its knowledge of VO membership. To trigger a manual update:

  1. Access the “Update VO Members” tab
  2. Click “Update”
  3. [Optional:] Monitor update progress via a log file
    #For OSG 3.x (RPM) installs on EL5 systems
    [root@client ~]$ tail -f /var/log/tomcat5/gums-service-admin.log
    #For OSG 3.x (RPM) installs on EL6 systems
    [root@client ~]$ tail -f /var/log/tomcat6/gums-service-admin.log
    #For OSG 3.x (RPM) installs on EL7 systems
    [root@client ~]$ tail -f /var/log/tomcat/gums-service-admin.log
    

With so many VOMS servers in the OSG config, several member updates may fail for various reasons (e.g., host down "connect timed out", bad or expired host certificates, etc.). Unfortunately, this situation is normal.

7.2 Updating the GUMS configuration

Periodically, the OSG Grid Operations Center will release an updated template for the GUMS configuration that updates information about an existing VO or adds a new VO. You may get the update as part of a regular update process, or you can force an update by using yum:

[root@client ~]$ yum update osg-gums-config

This step does not update your GUMS configuration (/etc/gums/gums.config) but will update the template for your configuration (/etc/gums/gums.config.template), because RPM cannot merge configuration changes. Instead, use GUMS to merge in the new VO configuration information.

  1. Go to the Merge Configuration tab: https://HOSTNAME:8443/gums/mergeConfiguration.jsp
  2. Cut and paste the URL of the OSG template into the Configuration URI field.

    For the template provided in the RPM, use: file:///etc/gums/gums.config.template
    To fetch it directly from the GOC, use http://software.grid.iu.edu/pacman/tarballs/vo-version/gums.template

  3. Click Merge

    You should get a green success message if it has worked, along with a suggestion that you update the VO members.

  4. Check the Summary tab to verify the set of VOs you have, as well as their accounts

8 Troubleshooting

8.1 Useful Configuration and Log Files

Configuration Files

Service or Process Configuration File Description
MySQL /etc/my.cnf MySQL configuration, e.g. server port
tomcat (EL5) /etc/tomcat5/ Tomcat configuration files
tomcat (EL6) /etc/tomcat6/ Tomcat configuration files
tomcat (EL7) /etc/tomcat/ Tomcat configuration files

Log files

Service or Process Log File Description
tomcat (EL5) /var/log/tomcat5/catalina.out This is the Tomcat log file. Problems (and a lot of noise) are reported here.
  /var/log/tomcat5/trustmanager.log The trustmanager handles things related to authentication. Useful errors are sometimes here.
tomcat (EL6) /var/log/tomcat6/catalina.out This is the Tomcat log file. Problems (and a lot of noise) are reported here.
  /var/log/tomcat6/trustmanager.log The trustmanager handles things related to authentication. Useful errors are sometimes here.
tomcat (EL6/EL7) /var/log/tomcat*/catalina.*.log These are the Tomcat log files. Problems (and a lot of noise) are reported here.
tomcat (EL6/EL7) /var/log/tomcat*/catalina.log Alternate non-rotated location for tomcat log file. Not the same as catalina.out. Problems (and a lot of noise) are reported here.
  /var/log/tomcat/trustmanager.log The trustmanager handles things related to authentication. Useful errors are sometimes here.
GUMS (EL5) /var/log/tomcat5/gums-service-admin.log GUMS outputs error messages related to it's operations here.
  /var/log/tomcat5/gums-service-cybersecurity.log GUMS outputs security related messages to this file.
GUMS (EL6) /var/log/tomcat6/gums-service-admin.log GUMS outputs error messages related to it's operations here.
  /var/log/tomcat6/gums-service-cybersecurity.log GUMS outputs security related messages to this file.
GUMS (EL7) /var/log/tomcat/gums-service-admin.log GUMS outputs error messages related to it's operations here.
  /var/log/tomcat/gums-service-cybersecurity.log GUMS outputs security related messages to this file.

GUMS (EL5/EL6/EL7) /var/log/gums/gums-developer.root.log  
  /var/log/gums/gums-egee-security.root.log GUMS may also output some security related messages to this file as well.
  /var/log/gums/gums-privilege.root.log GUMS outputs mapping related errors to this file.

8.2 Tuning GUMS for a big Site

GumsScalability contains several performance tips built form the experience of running the service on FermiGrid, a big OSG Site.

9 How to get Help?

To get assistance please use the Help Procedure.

10 References

11 Comments

Topic attachments
I Attachment Action Size Date Who Comment
pngpng GUMSConfigurationModel.png manage 61.4 K 26 Apr 2012 - 21:22 JohnHover Schematic of GUMS Configuration Model
Topic revision: r61 - 08 Feb 2017 - 16:14:00 - BrianLin
Hello, TWikiGuest!
Register

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