Note: This version of the VDT (1.9.1) is no longer supported. Feel free to look through the documentation and install it, but we cannot guarantee support for it. The current stable release is 2.0.0.

GUMS

Enabling GUMS monitoring

Introduction

It is possible for the Generic Information Provider (GIP) to monitor your GUMS service and publish this information via BDII. As of VDT 1.8.1, fresh installs of GUMS v1.2 and upgrades from v1.1 to v1.2 are automatically configured to accept the monitoring probe distributed via VDT 1.8.1.

These instructions detail the steps taken by the automatic configuration scripts and are provided by Gabriele Garzoglio. They are meant to be used for debugging purposes. They are also useful to manually authorize the GUMS probe in a v1.1 GUMS installation.

Basics

We check the availability of GUMS by running a probe (Information Provider). The probe asks GUMS to perform an identity mapping. The output of the probe is used by the GIP to publish the status information via BDII. The identity of the probe is a generic string ("/GIP-GUMS-Probe-Identity"), which is pre-loaded in the GUMS database by following these instructions. These instructions also configure GUMS to map the identity of the probe to a non-existent pre-defined UID.

Define the probe identity mapping in your GUMS v1.2 configuration

NOTE: You should not need to manually change the GUMS v1.2 configuration to enable GIP monitoring. The GUMS v1.2 installation or upgrade scripts add the following XML in the GUMS configuration, which is normally at $VDT_LOCATION/vdt-app-data/gums/config/gums.config.

If your GUMS configuration has <userGroups>, <accountMappers>, <groupToAccountMappings>, and <hostToGroupMappings> defined already, then the scripts nest the <manualUserGroup>, <groupAccountMapper>, <groupToAccountMapping>, and <hostToGroupMapping> tags inside of them as shown below.

<userGroups>
<manualUserGroup
name='gums-test'
access='write'
description=''
persistenceFactory='mysql'/>

</userGroups>

<accountMappers>
<groupAccountMapper
name='GumsTestUserMappingSuccessful'
description=''
accountName='GumsTestUserMappingSuccessful'/>
</accountMappers>

<groupToAccountMappings>
<groupToAccountMapping
name='gums-test'
description=''
accountingVoSubgroup=''
accountingVo=''
userGroups='gums-test'
accountMappers='GumsTestUserMappingSuccessful'/>
</groupToAccountMappings>

<hostToGroupMappings>
<hostToGroupMapping
groupToAccountMappings='gums-test'
description=''
cn='*/?*.my.site'/>
</hostToGroupMappings>

Define the probe identity mapping in your GUMS v1.1 configuration

If you run GUMS v1.1, you need to change the configuration of the GUMS manually, in order to enable GIP monitoring.

Add the following XML within your GUMS configuration, which is normally at $VDT_LOCATION/gums-service/var/war/WEB-INF/classes/gums.config.
If your GUMS has <groupMappings> defined already, add the <groupMapping> tag below within your <groupMappings> tag.
If your GUMS has <hostGroup> tags defined already, add the 'gums-test' group at the end of your groups attributes and change the value of the cn attributes to the regular expression '*/?*.my.site', as shown below. This allows rule-matching for service certificates of the form 'host/machine.my.site', 'http/machine.my.site', and 'machine.my.site'.
Note that you don't need to stop GUMS when editing its configuration.

<groupMappings>
  <groupMapping name='gums-test'>
    <userGroup className='gov.bnl.gums.ManualUserGroup'
               persistenceFactory='mysql'
               name='gums-test'/>
    <accountMapping className='gov.bnl.gums.GroupAccountMapper'
                    groupName='GumsTestUserMappingSuccessful' />
  </groupMapping>
</groupMappings>
<hostGroups>
  <hostGroup className='gov.bnl.gums.CertificateHostGroup'
             cn='*/?*.my.site'
             groups='gums-test' />
</hostGroups>

Add the identity of the probe to the GUMS database

These steps are executed automatically when installing GUMS v1.2. They need to be executed ONLY if you want GUMS v1.1 to be monitored by the GIP probe.
• Setup your gums client environment (typically this means sourcing the VDT setup.sh or setup.csh).
• Execute the following command using the administrative user credentials. This makes the probe identity part of the gums-test group in the gums database

  root> $VDT_LOCATION/gums/bin/gums manualGroup-add gums-test "/GIP-GUMS-Probe-Identity"
  

  Note that this is the syntax for adding manual groups via the gums v1.1 client command. The equivalent in v1.2 syntax is

  root> $VDT_LOCATION/gums/scripts/gums manualGroupAdd gums-test "/GIP-GUMS-Probe-Identity"
  

Check that the test configuration is working.

• From the machine that runs the probe, login as the user that can read the http service certificate.
• Setup your gums client environment
• Define the environment variables X509_USER_CERT and X509_USER_KEY to point to the http certificate and key files. This gives your environment the same identity as the GIP probe.
  NOTE: versions of GIP older than v1.0.15 (VDT 1.8.1) used ldap service certificates, instead of http certificates, for their identity. If you see yourself in need of using those, you might be using an older version of GIP, which is not authorized to access GUMS via these instructions.
For example for bash:

export X509_USER_CERT=/etc/grid-security/http/httpcert.pem
export X509_USER_KEY=/etc/grid-security/http/httpkey.pem

• Execute the following command, substituting the subject of the http service certificate DN appropriately

  $VDT_LOCATION/gums/scripts/gums-service mapUser -s "<http-DN>" "/GIP-GUMS-Probe-Identity"
  

  For example (with an http certificate copied from the host certificate):

  $VDT_LOCATION/gums/scripts/gums-service mapUser -s "/DC=org/DC=doegrids/OU=Services/CN=host/mymachine.my.site" "/GIP-GUMS-Probe-Identity"
  
  LocalId[userName: GumsTestUserMappingSuccessful]
  

  If you see the output LocalId[userName: GumsTestUserMappingSuccessful] the mapping works. If you see "null" something went wrong.