Using GUMS in the VDT 1.10.1

The Grid User Management System (GUMS) helps a grid site map incoming grid user credentials to local user accounts (or other local identities). GUMS is responsible only for managing and performing mappings, not enforcing the use of the resulting information.

The VDT 1.10.1 release includes GUMS 1.2.16.

To use GUMS in the VDT, you will probably have to perform at least some of the following basic tasks.

Install GUMS components
Configure GUMS
Start and stop the GUMS services
Add an administrator to GUMS
Use the web administration tool to manage GUMS
Enabling GUMS monitoring
Miscellaneous information

For more information, look at the Miscellaneous section.

Note: This page contains links to the GUMS documentation website, which is for the latest version of GUMS only.

Installing GUMS Components

Our installation instructions will help you install GUMS as you would any other component of the VDT.

There are three GUMS-specific packages that you can select to install:

GUMS-Client: Only the command-line tools for managing GUMS
GUMS-Service: Just the GUMS web service
GUMS: Both client and service components; i.e., both GUMS-Client and GUMS-Service

Other VDT packages will install all or part of GUMS. For example:

VDT: Installs the complete GUMS package
VDT-Gatekeeper: Installs the GUMS-Client package

Configuring GUMS

Part of your GUMS configuration is managed using its administrative web application, but some configuration details are maintained manually in other files.

To change how GUMS maps users, edit
```
$VDT_LOCATION/vdt-app-data/gums/gums.config
```
Please consult the GUMS documentation for details on the contents of this file.

Note: In general, you do not have to restart GUMS to pick up configuration changes. However, if you add, change, or remove a VOMS-based mapping, the VOMS mappings will not be reloaded until the next scheduled reload cycle. You can force a reload of the VOMS mappings using the gums updateGroups command, which is in the GUMS documentation.
[Optional] To activate email forwarding of the GUMS log in case of error, edit
```
$VDT_LOCATION/tomcat/v55/webapps/gums/WEB-INF/classes/log4j.properties
```
The file contains its own documentation. Fill in the appropriate information, restart the service; when GUMS encounters an error, it will send an email to the address you specified.
[Optional] GUMS provides a log suitable for cybersecurity in
```
$VDT_LOCATION/tomcat/v55/logs/gums-service-cybersecurity.log
```
The same log can be configured to use syslogd. Please refer to the GUMS documentation for more details.
[Optional] If configured to use a VOMS server, GUMS downloads data from the VO servers every 12 hours by default. This time interval begins with the first request to map a user. To change the time interval between updates, edit
```
$VDT_LOCATION/tomcat/v55/webapps/gums/WEB-INF/web.xml
```
The default entry is as follows:
```
<env-entry>
  <env-entry-name>updateGroupsMinutes</env-entry-name>
  <env-entry-type>java.lang.Integer</env-entry-type>
  <env-entry-value>720</env-entry-value>
</env-entry>
```
Change env-entry-value to your preferred interval in minutes.

Starting and stopping the GUMS services

Once GUMS is installed, a system administrator may need to start and stop GUMS services. The preferred way to start and stop services in the VDT is to use the vdt-control command, which installs services into system-wide locations so that the services will be run upon system start-up. However, it is also possible to start and stop services without affecting the rest of the system or if you are running as non-root.

In any case, you must first:

Log in as root or (if you use the second method, without vdt-control) as the user who installed GUMS.
Set up your environment to use GUMS (i.e., source setup.sh or setup.csh).

Standard Method (vdt-control, must be done as root)

To start services:

vdt-control --on

To stop services:

vdt-control --off

Manual Method (no system-wide changes, can be done as non-root)

To start services:

$VDT_LOCATION/post-install/mysql start
$VDT_LOCATION/post-install/apache start
$VDT_LOCATION/post-install/tomcat-55 start

To stop services:

$VDT_LOCATION/post-install/voms stop
$VDT_LOCATION/post-install/tomcat-55 stop
$VDT_LOCATION/post-install/apache stop

Adding an administrator to GUMS

You must add at least one administrator to GUMS using the command line before using the web administration tools. Only those users whose web browsers present to the web tools an administrator's certificate will be allowed to make changes to GUMS.

Make sure that:
- You are root or the user who installed GUMS
- You set up your environment to use GUMS (i.e., source a setup script)
- The GUMS service is running
Add the administrator:
```
$VDT_LOCATION/tomcat/v55/webapps/gums/WEB-INF/scripts/addMySQLAdmin 'DN'
```
where DN is the DN of the administrator. The single quotes may be needed to protect parts of the DN string from the shell. You will be prompted for confirmation and, if needed, for the MySQL root password.

Using the web administration tool to manage GUMS

You can administer GUMS using the GUMS web application. Note: To make changes to GUMS, you must have installed your certificate in your web browser and be listed as an administrator in GUMS; see the previous procedure for help adding administrators to GUMS.

Make sure that:
- The GUMS services are running
- Your web browser has been loaded with your user certificate
Access your local VDT services home page at
```
https://<machine-address>:8443/
```
where <machine-address> is the address to the machine on which GUMS is running.
Accessing this URL should show a page that lists GUMS on the right, along with the VDT website links on the left. If, for some reason, accessing this page does not work, or if you'd rather skip this page, you can access the GUMS administrative page directly at
```
https://<machine-address>:8443/gums/
```
Follow the links and instructions in the web application to manage GUMS

Note: If you receive an error message saying "Access denied", double-check to make sure your browser is loaded with your user certificate and that you have been added to GUMS as an administrator.

Enabling GUMS monitoring

We have detailed information on monitoring GUMS with the Generic Information Provider (GIP).

Miscellaneous information

For more information about GUMS, please visit these resources (outside the VDT website):