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).

[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)

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.