Note: This version of the VDT (1.4.0) 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.

Using GUMS in the VDT 1.4.0

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.4.0 release includes GUMS 1.1.0.

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

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/gums-service/var/war/WEB-INF/classes/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/gums-service/var/war/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/v5/logs/gums-service-cybersecurity.log
```
The same log can be configured to use syslogd. Please refer to the GUMS logging 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/gums-service/var/war/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. Note: If you installed GUMS (or other VDT packages that included GUMS) as root and if you answered 'yes' to the questions about automatically starting GUMS, then the GUMS service should be running following the installation and will be run automatically every time the machine is rebooted.

The GUMS service is a web service that runs under Apache and Tomcat 5 and uses MySQL; therefore, starting or stopping GUMS implies starting or stopping these other components, which in turn may affect other components that rely on the same infrastructure. Currently, the VDT does not support starting or stopping individual services within Tomcat.

To start the GUMS service:

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)
Move to the post-install directory:
```
cd $VDT_LOCATION/post-install
```

Start the services (in the given order):

./mysql start
./apache start
./tomcat-5 start

To stop the services, do steps 1–2 above, then:

Stop the services (in the given order):

./tomcat-5 stop
./apache stop
./mysql stop

Note: If you installed GUMS as root, then the post-install commands are copied to your startup script directory (e.g., /etc/init.d) and can be run from there as well.

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/gums-service/sbin/addAdmin '<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.

Miscellaneous information

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