-- ChrisKendrick - 08 Jan 2007

-- GrahamJenkins - 04 Apr 2007

nggums Server Build Guide

Purpose - Document of how to build an nggums Server at your local site.

Responsible Group - VPAC

Contact - Chris Kendrick - kendrick@vpac.org

Technology - CentOS 4.4, VDT GUMS

How GUMS handles user mapping requests

Should a user submit a plain grid proxy to Globus. GUMS by default will run the user under the first VO they are found to be in. I have deliberately ordered the names listed in the "groups" variable of the "hostGroup" tag within the default gums.config so that GUMS first checks if the user has manually mapped themselves with the Authtool (which syncs to the GUMS database), then it proceeds through the VO's it has listed.

If a user uses a voms proxy where they have specified the VO they wish to run under .. GUMS will run them under the VO specified in the VOMS proxy if the user is found to be in that VO and that VO has been added to the gums.config, otherwise the globus submit will fail.

Step One: Virtual Machine (VM) Creation.

Build the basic Xen guest for NGGUMS using the procedure shown in XenInstall and set-up networking and user authentication in accordance with local conventions

Step Two: Installing VDT GUMS

Apply for and install a host certificate (and key) for the machine as shown at: HostCertRequestAPAC

Login as root, set http_proxy if appropriate, then perform the following operations:

# yum install Gbuild
# /usr/local/sbin/BuildNggumsVdt161.sh  .. and answer 'y' to the cache question
# . /etc/profile .. to pick-up the VDT environment variables

Step Three: Configuring VDT GUMS

Set root password for mysql server

# mysql -u root
(no passwd for root user)
# SET PASSWORD FOR 'root'@'nggums.your.domain' = PASSWORD('secret');
# SET PASSWORD FOR 'root'@'localhost' = PASSWORD('secret');

Check GUMS web interface is up Go to "https://nggums.your.domain:8443/gums/"

Add yourself to the list of GUMS admins

# cd $VDT_LOCATION/gums-service/sbin
# ./addAdmin "YOUR_CERT_DN"

Verify you have administrative capabilities in GUMS:

• Go to your gums web interface at https://nggums.your.domain:8443/gums.
• Click "Generate Grid Mapfile".
• Enter anything (e.g., xyz) as host computer just to test that the process runs.
• You should get "null" as a response.

If you get the following, you have not added yourself correctly to the admins group or you are using the wrong certificate in your browser:

GUMS encountered an error
Error Type: gov.bnl.gums.admin.AuthorizationDeniedException
Error Message: Authorization denied

Customise your gums.config file

# cp /usr/local/src/gums.config /opt/vdt/vdt-app-data/gums/ 

Edit the gums.config file.

• Replace "your.domain" in the hibernate.connection.url variable with the FQDN of your nggums machine
• gums password: The vdt install of gums automatically creates a gums user account in the mysql database and sets a random password. You need to use this random password from your original gums.config as follows:Fill in hibernate.connection.password variable with the password that is located within /opt/vdt/vdt-app-data/gums/gums.config.ORI (your original gums.config as saved by the build script).
• enable commented groups that may apply to your site, eg. GIN. Note you must add the "name" variable from each "groupMapping" tag that you add to the "groups" variable in the "hostGroup" tag. The order of the "name"s in the "groups" variable is what defines the order in which GUMS checks for a users membership in each VO. This is only relevant when the user submits a proxy where they have not specified the VO they wish to run under.
• edit the "hostGroup" element to reflect the domain your gateway machines run under.
• edit the "cn" variable within the "hostGroup" tag to reflect the domain under which your globus and grid-ftp machines are found.

Note: The "hostGroup" element. The point of the host group element is to specify what groups of machines (or even an individual machine) certain VO to account mapping info should be sent to, when PRIMA on those machines connects to the GUMS server.

Test out your new GUMS server

Populate your VO Members Database manually.

• Go to your gums web interface at https://nggums.your.domain:8443/gums.
• click "Update Members" in the left pane
• then click the "Update VO Members Database" button

This will contact the VOMS server(s) listed in your gums.config and pull down all the users in the VO and store them in the mysql GUMS database. By default this will happen automatically once every 12 hours, but can be adjusted as explained in the following section "GUMS to VOMS server sync frequency".

You can also use the GUMS web interface to present a grid-mapfile in your web browser, just so you can see what sort of data you are pulling from your VOMS server(s)

• Click on "Generate Grid Mapfile" in the left pane
• Enter the DN of one of a your gateway machines that will be calling to the GUMS database in future, eg "/C=AU/O=APACGrid/OU=VPAC/CN=ng1.vpac.org"
• Click "Generate grid-mapfile."

You should get the text of a grid-mapfile formatted output (as of this writing):

#---- members of vo: mappedUsers ----#
#---- members of vo: ngadmin ----#
"/C=AU/O=APACGrid/OU=APACNF/CN=Stephen McMahon" grid-admin
"/C=AU/O=APACGrid/OU=BeSTGRID/CN=Andrey Kharuk" grid-admin
"/C=AU/O=APACGrid/OU=CSIRO/CN=Jeroen van den Muyzenberg" grid-admin
"/C=AU/O=APACGrid/OU=CSIRO/CN=Ryan Fraser" grid-admin
"/C=AU/O=APACGrid/OU=QPSF/CN=Andrew Sharpe" grid-admin
"/C=AU/O=APACGrid/OU=SAPAC/CN=Daniel Cox" grid-admin
"/C=AU/O=APACGrid/OU=SAPAC/CN=Gerson Galang" grid-admin
"/C=AU/O=APACGrid/OU=SAPAC/CN=Jingjing Sun" grid-admin
"/C=AU/O=APACGrid/OU=TPAC/CN=John Dalton" grid-admin
"/C=AU/O=APACGrid/OU=UQ/CN=William Hsu" grid-admin
"/C=AU/O=APACGrid/OU=VPAC/CN=David Bannon" grid-admin
"/C=AU/O=APACGrid/OU=VPAC/CN=Graham Jenkins" grid-admin
"/C=AU/O=APACGrid/OU=VPAC/CN=Markus Binsteiner" grid-admin
"/C=AU/O=APACGrid/OU=ac3/CN=Andrew Li" grid-admin
"/C=AU/O=APACGrid/OU=ac3/CN=Youzhen Cheng" grid-admin
"/C=AU/O=APACGrid/OU=iVEC/CN=Darran Carey" grid-admin
"/C=AU/O=APACGrid/OU=iVEC/CN=Terry Rankine" grid-admin
#---- members of vo: gtest ----#
"/C=AU/O=APACGrid/OU=SAPAC/CN=Gerson Galang GTest" grid-test
"/C=AU/O=APACGrid/OU=VPAC/CN=Graham Jenkins GTest" grid-test
"/C=AU/O=APACGrid/OU=ac3/CN=Youzhen Cheng GTest" grid-test

GUMS to VOMS server sync frequency

By default the GUMS server will update the local GUMS mysql database with VO information from the VOMS servers listed in the gums.config file once every 12 hours. This can be adjusted as follows:

# vi /opt/vdt/gums-service/var/war/WEB-INF/web.xml

The third line from the bottom contains the interval in minutes. Its default is every 12 hours.

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

I suggest you update this to 5 minutes.

Restart the tomcat container --

# service tomcat-55 restart

Further Documentation

The Official Documentation on how the gums.config file works is here: https://www.racf.bnl.gov/Facility/GUMS/1.1/guide_config_gums.html

Step Four: Installing the AuthTool

Using LDAP or NIS with PAM for local user authentication

LDAP and NIS authentication via PAM is achieved by using the mod_authnz_external apache module which calls an external program called pwauth to do the authentication, which in turn uses PAM to determine which authentication mechanisms to use.

First, install the authtool:

# cd /opt/vdt/apache/htdocs 
# wget http://www.vpac.org/~kendrick/authtool.tar.gz 
# tar xzf authtool.tar.gz && rm -f authtool.tar.gz
# chown -R daemon:daemon auth mapfile && chmod 755 auth mapfile 
# chmod 644 auth/* && chmod 644 mapfile/*

Install the mod_authnz_external apache module:

# cd /tmp
# wget http://www.unixpapa.com/software/mod_authnz_external-3.1.0.tar.gz
# tar xzf mod_authnz_external-3.1.0.tar.gz
# cd mod_authnz_external-3.1.0
# apxs -c mod_authnz_external.c
# apxs -i -a mod_authnz_external.la

If there were no error messages, you should have a new apache module in /opt/vdt/apache/modules called mod_authnz_external.so.

Now install the pwauth external authentication program:

# cd /tmp
# wget http://www.unixpapa.com/software/pwauth-2.3.2.tar.gz
# tar xzf pwauth-2.3.2.tar.gz
# cd pwauth-2.3.2

Edit config.h and comment out the following lines:

#define UNIX_LASTLOG
#define MIN_UNIX_UID 500
#define NOLOGIN_FILE "/etc/nologin"
#define SHADOW_SUN

and uncomment:

#define PAM

The last thing to change in this file is the setting for:

#define SERVER_UIDS 2

where 2 is the uid for the user defined by the User configuration statement in the apache configuration file /opt/vdt/apache/conf/httpd.conf. The default for the nggums VM is daemon (2).

Now edit Makefile, and uncomment the line:

LIB=-lpam -ldl

Now do the following:

# yum install make pam-devel
# make
# cp pwauth /opt/vdt/apache/bin
# chown daemon /opt/vdt/apache/bin/pwauth
# chmod 700 /opt/vdt/apache/bin/pwauth

Create a new file /etc/pam.d/pwauth with the following:

#%PAM-1.0

auth           required        pam_ldap.so
account        required        pam_ldap.so

# or if you are using NIS
#auth          required          pam_unix.so 
#account    required          pam_permit.so

Add the following line to the apache configuration file /opt/vdt/apache/conf/httpd.conf:

• this should already by "apxs -i"

LoadModule authnz_external_module modules/mod_authnz_external.so

And add these lines inside the <VirtualHost _default_:8443> section of /opt/vdt/apache/conf/extra/httpd-ssl.conf:

AddExternalAuth pwauth /opt/vdt/apache/bin/pwauth
SetExternalAuthMethod pwauth pipe
<Directory "/opt/vdt/apache/htdocs/auth">
        AllowOverride AuthConfig
</Directory>

Add the following lines to the .htaccess file in the authtool directory:

• Note: this should already have been done when extracting the authtool package.

AuthType Basic
AuthName "Grid Authorization Tool"
AuthBasicProvider external
AuthExternal pwauth
require valid-user
SSLVerifyClient require

Install gumsmanualmap.py

Note: Substitue "PASSWD" in the following for the password used in your gums.config file

# yum install MySQL-python.i386
# mysql -u root -p
# USE mysql;
# GRANT ALL ON GUMS_1_1.* TO 'gums'@'localhost' IDENTIFIED BY 'PASSWD';
# UPDATE user SET Password = OLD_PASSWORD('PASSWD') WHERE Host = 'localhost' AND User = 'gums';
# FLUSH PRIVILEGES;
# quit
# cd /opt/vdt/apache/htdocs 
# wget http://www.grid.apac.edu.au/repository/dist/development/files/gumsmanualmap.py
# chown daemon:daemon gumsmanualmap.py && chmod 755 gumsmanualmap.py
# cd /etc/cron.hourly/
# wget http://www.vpac.org/~kendrick/01-gumsmanualmap 
# chown daemon:daemon 01-gumsmanualmap && chmod 755 01-gumsmanualmap

Finally, restart apache: service apache restart

Test the authtool

To speed things along you can run /etc/cron.hourly/01-gumsmanualmap manually after mapping yourself through the web interface at https://nggums.your.domain:8443/auth rather than waiting up to an hour for the cron job to run.

If you currently have users manually mapped via the authtool on your ngportal server you may over write /opt/vdt/apache/htdocs/mapfile/mapfile on your gums server with the authtool mapfile from your ngportal server. Note the location of the authtool's mapfile on your ngportal server may vary depending on the version you have. The older version has it located under /var/www/html/mapfile/mapfile, while the newer version has it under /usr/local/share/mapfile. Once this is complete you may run /etc/cron.hourly/01-gumsmanualmap on nggums rather than wait an hour for it to be synced with the GUMS database.

Step Four: Configure your network

The only request that should be allowed to hit your nggums server from the outside world is 8443 because the authtool uses that port. Other than that it should only be contacted by your globus and grid-ftp machines.