HOW TO: GUMS Service quick-start installation

This article describes how to quickly install a GUMS service, without going through many of the details. As of GUMS 1.0.0, the preferred way to install GUMS will be VDT. You should use this guide only if you need to install GUMS without using VDT (i.e. when you need the really latest version).

Preparing java

GUMS is written in java, and requires java to be installed to run. Be sure it is installed in your $PATH. Try running:

[root@gums root]# java -version
java version "1.4.2_04"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.2_04-b05)
Java HotSpot(TM) Client VM (build 1.4.2_04-b05, mixed mode)

If you do not have java installed, go to http://java.sun.com and follow the instructions to get the latest version. Then add java to $PATH.

Preparing the certificate directory

GUMS will need the GRID certificate for the host and the certificate directories in place. Easiest way: use VDT; but you are not, so you are on your own here.

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. You'll need root password.

Preparing Tomcat + EGEE security

The GUMS service will require a web server container, configured to use SSL with Globus proxy certificates. You will also need Xerces 2.5.0 in the common/endorsed directory. If you do not know what that means, just grab the already packaged Tomcat from the download page and install it.

  • Grab the tarball from the download section
    [root@gums root]# cd /opt/
    [root@gums opt]# wget http://grid.racf.bnl.gov/maven/gums/tar.gzs/tomcat-5.0.28-egeesec.tar.gz .
  • Untar it
    [root@gums opt]# tar -xzvf tomcat-5.0.28-egeesec.tar.gz
  • Review the configuration of the server
    [root@gums opt]# vi tomcat-5.0.28-egeesec/conf/server.xml

    NOTE: if you need to change the configuration for the service certificate, or the port on which the service runs, you can edit the $TOMCAT_HOME/conf/server.xml tomcat configuration file. Find the section:

        <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/grid-security/hostkey.pem"
                   log4jConfFile="/opt/tomcat-5.0.28-egeesec/conf/log4j-trustmanager.properties"
                   clientAuth="true" sslProtocol="TLS" />

    If you installed in a different directory than /opt/tomcat-5.0.28-egeesec, change the location of log4jConfFile. To change the location of the service certificate or the CAs, simply change the sslXxx and crlFiles properties. To change the port, change the port property.

  • Start the server
    [root@gums opt]# tomcat-5.0.28-egeesec/bin/catalina.sh start
  • Connect to the server through a web browser with a Grid certificate installed, to check that is indeed running.

Install the service

The service itself is a standard java web application. Grab the latest gums-service tarball file from the dist directory, and unpack it.

  • Grab the latest build and install
    [root@gums root]# cd /opt/
    [root@gums opt]# wget http://grid.racf.bnl.gov/maven/gums/tar.gzs/gums-service-SNAPSHOT.tar.gz .
    [root@gums opt]# tar -xzvf gums-service-SNAPSHOT.tar.gz
  • You will need to create the database. You can do by running the setupDatabase script giving
    [root@gums opt]# cd gums-service/sbin/
    [root@gums sbin]# ./setupDatabase
    Usage: ./setupDatabase [mysql user for GUMS] [GUMS server host] [GUMS mysql password]
    
    Examples:
    ./setupDatabase gums gums.mysite.com secret
    
      This will make mysql authenticate as root with a password (-p), create a 'gums' user with password 'secret' authorized to connect from 'gums.mysite.com'.
    [root@gums sbin]# ./setupDatabase gums gums.mysite.com secret

    The script will only run on localhost. If you need to create db on another server, or with different account then root, edit setupDatabase:

    [root@gums sbin]# cat setupDatabase
    #!/bin/sh
    ...
    MYSQLPARAM="-p"
    ..
  • Now add yourself to admins:
    [root@gums sbin]# ./addAdmin
    Adds an admin in the GUMS database on localhost
    Usage: ./addAdmin [DN for administrator]
    
    Example:
    ./addAdmin "/DC=org/DC=doegrids/OU=People/CN=Gabriele Carcassi 12345"
    [root@gums sbin]# ./addAdmin "/DC=org/DC=doegrids/OU=People/CN=Your Self 83753"
  • Last thing, we need to tell tomcat to run GUMS:
    [root@gums sbin]# cd ../..
    [root@gums opt]# ln -s ../../gums-service/var/war tomcat-5.0.28-egeesec/webapps/gums
    
  • Get a browser in which you have your grid certificate, go to: https://<machine>:<port>/gums: you should see the GUMS web interface. You might need to wait a bit for tomcat to realize the gums application was installed.
  • Try generating the mapfile for the host "testing.site.com", and it should give you some response.
  • [Optional] Another thing you can do is activate the e-mail forwarding of the log in case of error. Edit /opt/gums-service/webapps/gums/WEB-INF/classes/log4j.properties, following the instructions within the file. Fill in the appropriate information, restart the service, and whenever GUMS will encounter an error, an e-mail will be sent to the address you specified.
  • [Optional] GUMS provides a log suitable for cybersecurity in the /opt/gums-service/logs/gums-site-admin.log. The same log can be configured to use syslogd. Please refer to the logging documentation for more details.
  • [Optional] One of the things GUMS does, is downloading the information from the VO servers every 12 hours. The clock will start at the first access to GUMS functionalities after each restart (i.e. first time you actually generate a mapfile or map a user). The time between updates can be set. The easiest way to do it, is to edit the /opt/gums-service/webapps/gums/WEB-INF/web.xml file.
      <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 the entry value to the number of mintues you prefer.

Congratulations: the server is up and running.

Installing the client

To generate maps (grid-mapfile, grid3-user-vo.txt) or to administer GUMS (i.e. create account pools, manage manual groups, ...) you will need to install GUMS Client which gives includes all the command line tools.

Grab the latest rpm file: it will install by default in /opt/gums, but the package is relocatable, so you can install it wherever you want.

  • Grab the latest build and install
    [root@gums root]# wget http://grid.racf.bnl.gov/maven/gums/noarch.rpms/gums-client-SNAPSHOT.noarch.rpm .
    [root@gums root]# rpm -Uvh gums-client-SNAPSHOT.noarch.rpm
  • Check that GUMS was installed correctly
    [root@gums root]# cd /opt/gums/bin/
    [root@gums bin]# ./gums
    usage: gums command [command-options]
    Commands:
      generateGrid3UserVoMap - Generate grid3-user-vo-map.txt for a given host.
      generateGridMapfile - Generate grid-mapfile for a given host.
      manualGroup-add - Includes a DN in a group.
      manualGroup-remove - Removes a DN from a group.
      manualMapping-add - Adds a DN-to-username in a mapping.
      manualMapping-remove - Removes a DN from a mapping.
      mapUser - Local credential used for a particular user.
      mapfileCache-refresh - Regerates mapfiles in the cache.
      updateGroups - Contact VO servers and retrieve user lists.
    For help on any command:
      gums command --help
  • Now, you need to tell gums-admin where is your GUMS server.

    [root@gums bin]# cat ../etc/gums-client.properties
    gums.location=https://localhost:8443/gums/services/GUMSAdmin
    gums.authz=https://localhost:8443/gums/services/GUMSAuthorizationServicePort
    

    Replace the localhost with the full machine name (even if you installed GUMS Admin on the same machine).

    [root@gums bin]# vi ../etc/gums-client.properties
    [root@gums bin]# cat ../etc/gums-client.properties
    gums.location=https://gums.mysite.com:8443/gums/services/GUMSAdmin
    gums.authz=https://gums.mysite.com:8443/gums/services/GUMSAuthorizationServicePort
  • Test the service by generating a mapfile at the command line

    [root@gums bin]# su - username
    [username@gums bin]# grid-proxy-init
    [username@gums bin]# ./gums generateGridMapfile /DC=org/DC=doegrids/OU=Services/CN=testing.test.gov
    

    You should get the same response you got from the web server.

  • You will have noticed that there are two command in the bin directory, plus a cron script: gums is meant to be run by an admin, and uses your proxy; gums-host and gums-host-cron are meant to be run using the host credentials, and they have limited functionalities (retrieve maps and mappings only). To make GUMS generate the maps periodically, just link the cron script in /etc/cron.hourly.

Congratulations you installed GUMS Admin. To make it actually useful, now you need to go back on the server and write an XML policy file. Please refer to the rest of the GUMS documentation.

Problems?

If you have any problem, feel free to contact GUMS developers.