The pieces

Before beginning, we describe what components are there in GUMS.

• The service: the main component is a web application that consists of a Web Service interface (WS) and a Web User Interface (WebUI). The same web application contains web pages for the admin to use through a browser, and a Web Service door that allows command line tools and other services to use GUMS functionalities. The Web Service part is a SOAP service built on Apache Axis. The web application is secured through SSL, that is both WS and WebUI have the same transport level security. If GUMS is installed on a server without SSL, though part of the WebUI will be available, it won't proceed with any operations. The authorization is internal to GUMS: in the configuration you define a group of admins, who have full access; other services will have only read access to their mappings (i.e. map user or generate maps).
  
  The service was developed and tested on a Tomcat 5.0.28 + EGEE security installation, though it should work on any J2EE compliant web servers with SSL. VDT is distributing GUMS with an Apache+Tomcat combination.
• The persistence layer: GUMS will need a place to store some temporary data, for example it caches the information it reads from the VO server, and some critical data, such as manual mappings the admin might want to define. At this time, the default persistence layer is based on a MySQL server, though Hibernate (Hibernate abstracts the persistence of Java object to any RDDMS, which means that "porting" GUMS to other databases is just a runtime configuration). The idea, though, is that a site might want to integrate this part within their infrastructure. For example, at BNL we want to store all the critical data on our LDAP servers, which already contain most of the user accounts information. To integrate one needs only to implement a couple of classes and change the configuration file, all of which can be done at runtime. The suggestion is to evaluate GUMS on a MySQL back-end, and then, if desired, plan the integration.
• The client tools: this is a set of command line tools to allow and admin to administer GUMS and, at a gatekeeper, to retrieve the maps (i.e. grid-mapfile et al) and/or to test the connectivity for the callout. They connect to the WS to perform the different tasks. The admin operations will be carried with the admin credentials, who will use the GRID proxy beforehand. The host operations will be carried out with the host/service credentials, that is the certificate and private key. The host will be allowed only to retrieve information about its mappings. The CN of the host certificate and the hostname will be used, and must match to the GUMS setup (i.e. host DN needs to match the map). All this activity will be logged on the server. The client tools can be installed on the same host where GUMS is running and on any other machine.

The installation steps are:

• Preparing the persistance layer backend (i.e. MySQL for the standard installation)
• Installing the service and setting up a policy
• Installing the client tools

Root vs non-root

GUMS can be run as both root and non-root. The only issue is the host certificate: GUMS must be able to access a host/service certificate with its private key for authentication. Generally, it is located in /etc/grid-mapfile/hostcert.pem with root permissions. One could either set those permissions to a different user, or create another copy for gums. Such as /etc/grid-security/gumscert.pem.

Firewall and security considerations

GUMS doesn't require any port to be installed outside the site firewall. The only requirement is to have an inbound TCP port opened on the GUMS server (default 8443), and an outbound port from all gatekeeper to that GUMS port.

All GUMS requests are over SSL. Grid certificates are used for authentication and authorization.

All access to GUMS is logged. Logs can be configured to use syslogd, which can be used to forward the logs to the cybersecurity department of the site.

Prepare the database

You will need a mysql server, with version 4.0.18 or greater installed. You can either install one from scratch (follow the instruction on mysql's site) or you can use an installation you have ready.

The gums service comes with a ./sbin/setupDatabase script which will create the database, and modify the policy file with the relevant information. The script will make you log in as root in mysql, will create a user and a database. You can see the script in ./var/sql/setupDatabase.mysql.

[root@www gums-service]# cat var/sql/setupDatabase.mysql
CREATE DATABASE GUMS_1_1;

GRANT ALL
  ON GUMS_1_1.*
  TO @USER@@'@SERVER@' IDENTIFIED BY '@PASSWORD@';

USE GUMS_1_1;

CREATE TABLE `USER` (
 `ID` INTEGER AUTO_INCREMENT PRIMARY KEY,
 `GROUP_NAME` VARCHAR(255) NOT NULL,
 `DN` varchar(255) NOT NULL,
 `FQAN` varchar(255) default NULL
) TYPE=InnoDB;

CREATE INDEX complete ON USER (GROUP_NAME(10), DN(70), FQAN(30));

CREATE TABLE `MAPPING` (
 `ID` INTEGER AUTO_INCREMENT PRIMARY KEY,
 `MAP` VARCHAR(255) NOT NULL,
 `DN` varchar(255) default NULL,
 `ACCOUNT` varchar(255) default NULL
) TYPE=InnoDB;

CREATE INDEX complete ON MAPPING (MAP(10), DN(70));

The database structure is very simple: it's just a place to store lists of users (in the USER table) and a list of mappings (MAPPING). It's meant to be simple: it's direct consequence of the requirement that GUMS should be easily ported to other persistence mechanisms (i.e. LDAP, other site internal DB, ...). The first table will be mainly used to cache the values from the VO servers. For example, in the policy you will specify you want to map all the users from the ATLAS VO to the 'usatlas1' account: from time to time GUMS will query the VO server and store the list of users in the USER table. For each mapping request, GUMS will look at its local copy instead of the remote VO server.

The USER and MAPPING tables are also critical for manual user groups and manual mappings. This means an admin is free to create a group of certificates, or a certificate to user mapping, to handle special cases. GUMS will have commands to add entries to these mapping, so you do not need to use the DB directly. You can if you want, though, for integration purposes. In any case, the use of these manual groups and mappings has a big effect: this is critical information that cannot be lost. Which means you will need to backup the server. This is a good candidate for integration: you might want to keep this information in the same information system you use for user account, as the information is connected.

To sum up: if you do not use manual groups and mappings, the information in the database can be regenerated at any time. If you do, GUMS has critical information, and you might want to make it safer through some kind of backup.

Once you created the database, you probably want to insert your DN in the USER table within a group you will later use in GUMS as the admin group. You can use the ./sbin/addAdmin script, which will use the ./var/sql/addAdmin.mysql template:

[root@www sbin]# cat ../var/sql/addAdmin.mysql
USE GUMS_1_1;

INSERT INTO USER SET DN="@ADMINDN@", GROUP_NAME="admins";

This inserts a DN in a manual user group named "admins".

Once the database is prepared: you can now proceed to install the Service

Installing the service

GUMS is written in java, and requires java to be installed to run. It was developed and tested against Sun JDK 1.4.2 and 1.5.0, but it will run on any 1.4.x and 1.5.x compliant JVM. If you need to install java, or learn more about it, refer to the documentation at http://java.sun.com.

The GUMS service is a standard J2EE application, which means it's application directory (./var/war) can be installed in any compliant engine. The VDT installation uses Apache+Tomcat combination: you should refer to the VDT documentation for more information.

We provide a tarball containing a Tomcat 5.0.28 + EGEE security preconfigured, which is the configuration GUMS was developed against. The EGEE provides an SSL Socket Factory that Tomcat uses to create the SSL connections. The EGEE SSL is essentially standard SSL with the addition of Grid proxies. You can find more information about it if you look for "glite trustmanager". The bundled tomcat is modified in the following way:

• 4 more jars where put in the $CATALINA_HOME/server/lib directory:
  
  bcprov-jdk14-125.jar
  
  glite-security-trustmanager.jar
  
  glite-security-util-java.jar
  
  log4j-1.2.8.jar
  
  These contain the EGEE SSL socket factory and dependency
• In $CATALINA_HOME/conf the following file is added:
  
  log4j-trustmanager.properties
  
  Which is the logging configuration for the EGEE security
• The $CATALINA_HOME/conf/server.xml was modified. The following section is added:

      <Connector port="8443"
                 maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
                 enableLookups="false" disableUploadTimeout="true"
                 acceptCount="100" debug="0" scheme="https" secure="true"
                 sSLImplementation="org.glite.security.trustmanager.tomcat.TMSSLImplementation"
                 sslCAFiles="/etc/grid-security/certificates/*.0"
                 crlFiles="/etc/grid-security/certificates/*.r0"
                 sslCertFile="/etc/grid-security/hostcert.pem"
                 sslKey="/etc/tomcat/hostkey.pem"
                 log4jConfFile="/opt/tomcat-5.0.28-egeesec/conf/log4j-trustmanager.properties"
                 clientAuth="true" sslProtocol="TLS" />

  This makes Tomcat listen on port 8443 for https, using the EGEE security. You will notice all the parameters for a Grid connection, and the configuration file that was added for EGEE security logging. The part declaring the port 8080 on http was closed.

Essentially, this is what is needed to setup EGEE security.

The tar of the service contains the web application in ./var/war, and the configuration files are for kept in the ./var/war/WEB-INF/classes directory. Tomcat will need to refer to this war directory: the easiest way is to make a link to it from the Tomcat webapps directory. The service tar also contain a couple of scripts to setup the database, which you have seen before.

The configuration files are 2:

• log4j.properties. This is a standard log4j configuration, which will determine how the logging is implemented. This is loaded once when the service is started. To change it, the service will need to be restarted.
• gums.config. This is the policy file for GUMS, which determines how all users will be mapped to their local account. Also the access to the database is defined here. This can be changed at any point, and the service will pick it up. At any operation that needs the configuration, a check is performed to see if the file has been changed. If it is, this will trigger a configuration reload.

You can refer to the full documentation of the configuration files for the details.

Once you have setup the server and the web application, you can use your browser with your grid credential to connect to the WebUI and run a couple of commands.

Installing the client tools

The client tools come packaged in an rpm. The default location is /opt/gums, but the destination can be changed. Once you install it, you will see 4 directories:

• bin: contains the gums executables. They are shell script that prepares the java environment for GUMS. One critical part is the creation of the variable to handle the grid security. It is a single executable that accept different commands, like cvs does (i.e. "./gums mapUser ...", "./gums generateGridMapfile ...". The script has --help options that explains what are the current features.
• etc: contains the configuration file for admin, which is one. The only thing it contains the URL to the servlet that runs the web service. You have to point to your server before being able to run any commands
• lib: contains all the java libraries needed by GUMS
• var/log: contains the log files for the admin. There won't be much there, as all the functionalities are implemented on the service.

There are two main tools: gums and gums-host. The first one runs with the user credentials (proxy) and allows an admin to perform all the operations. The second runs with the host credentials (/etc/grid-security/host*.pem), and allows the host to retrieve the maps (grid-mapfiles and the OSG accounting map).

You can use ./bin/gums to:

• View the generations of the map
• Change the manual group and mapping
• Trigger a refresh of the groups (i.e. make GUMS contact the VO servers to refresh the local member lists)

You can use ./bin/gums-host to:

• Generate maps for the host: these will be based on the hostname
• Test the connectivity of the callout door.