Introduction

This document is a guide to installing and configuring PURSe and its required software for use in a portal system. Please note that starting with the 1.1.0 release of the PURSe portlets, there is now an install script available with the PURSe download that automates these installation steps and you are encouraged to use it. See the section on using the PURSe install script for more information.

The following prerequisites are required for installing PURSe:

  • GT4 Prerequisites (Java 1.4.2+, Ant 1.5.1+, etc.)
  • GT4 installation on the portal server. Note: you'll only need to configure the SimpleCA and MyProxy services of GT4.
    • Note that if you want to just install simpleCA and MyProxy, it is highly recommended that you grab the latest stable 4.0.x "Full Toolkit Source Download" (v. 4.0.2 at the time of this writing) release and when you follow the build instructions, instead of doing make substitute make gsi-myproxy . This will build MyProxy as well as simpleCA and their dependencies.
  • MySQL database server on your network

Using the PURSe install script

The PURSe install script is designed to make it easier to get up and running with PURSe, by automating a lot of the steps necessary to build and install PURSe and its dependencies. The install script will install and setup Globus, simpleCA, MyProxy, the PURSe database, and various config files, in a non-root setup. If you already have Globus installed, it can make use of that as well.

To use the install script, download the PURSe tarball from the downloads page. Untar it. Copy the install.conf.template file to install.conf. Edit the variables inside. Here is a list of configurable parameters.

VariableDescription
PURSE_HOMEIf running the install script from its directory, then PWD would be the value
GT_TARBALLProvide the path to the bzip2 Globus Toolkit 4 tarball
BUILD_LOCATIONA location where the script can build the Globus code.
DEPLOY_LOCATIONA directory in which the install script will place various scripts, etc.
GLOBUS_LOCATIONThe location of an existing Globus deployment, or the place where you want the install script to install Globus.
SIMPLECA_DIRThe location where SimpleCA should be deployed.
SIMPLECA_SUBJECTThe distinguished name or subject of your SimpleCA.
SIMPLECA_EMAILThe email of your certificate authority (CA) administrator.
SIMPLECA_PASS The password to use to encrypt the CA's private key. This field is optional. If not provided, the install script will prompt you for the password.
GRID_CERTS_DIRThe location where to put generated certificates. The install script will generate a host certificate and a test user certificate for doing a self test of the MyProxy server.
MYSQL_HOSTNAMEThese MySQL properties are fairly self-explanatory.
MYSQL_DATABASE
MYSQL_USERNAME
MYSQL_PASSWORD
MYSQL_HOME Optional, although may be necessary if the MySQL installation is not on the user's command path.
MYSQL_ENCRYPT_PASSThe password used by PURSe to encrypt users' passwords stored in the MySQL database.
SMTP_HOSTHostname of the server running a mail server.
PORTAL_HOSTNAMEHostname of the portal.

Once configured, run "./install.sh". Once the install is complete, you will find a purse.properties file in the DEPLOY_LOCATION that should be deployed with the PURSe Portlets war file (see PURSe Portlets install notes). A MyProxy init script is also generated and is located at $DEPLOY_LOCATION/myproxy.init and should be installed as appropriate. Then to configure your portal's Tomcat container, add the following lines to the top of $CATALINA_HOME/bin/catalina.sh:

GLOBUS_LOCATION=<GLOBUS_LOCATION>
export GLOBUS_LOCATION
JAVA_OPTS="$JAVA_OPTS -Dorg.globus.config.file=<DEPLOY_LOCATION>/cog.properties"

        
where <GLOBUS_LOCATION> is the GLOBUS_LOCATION defined in the install.conf file and likewise for <DEPLOY_LOCATION>.

Manual PURSe Installation

Installing PURSe

Grab the PURSe System Source Tarball from the Downloads page for the current release. Unpack it in a directory on your portal server host. Hereafter, the install directory will be referred to as $PURSE_HOME.

Configuring SimpleCA

Note that simpleCA must be installed on the file system of the portal server.

See the GT4 SimpleCA Admin Guide for instructions on configuring SimpleCA. Follow those instructions. Some caveats follow.

The typical thing to do when configuring SimpleCA is to run the setup-simple-ca script as user globus (or some other non-root grid user account). By default, the simpleCA directory will be installed in the globus user's .globus/ directory. It's important that the user under which you run your portal server read/write access to the simpleCA directory. If that user is not globus, then you can pass the -dir option to setup-simple-ca, like so:

$GLOBUS_LOCATION/setup/globus/setup-simple-ca -dir /usr/local/globus-4.0.0/portalCA
        

Then set the permissions on that directory such that the user under which the portal server runs can access and write to that directory.

When you run setup-gsi to install the CA created by the setup-simple-ca script, you're not required to pass it the -default option, because you can configure the CA hash to use in PURSe. You may wish to do this is you want to have the portal CA be distinct from your grid's default CA.

Configuring MyProxy

These PURSe portlets use a customized version of PURSe that allows it to store user certificates in a remote MyProxy server (the version of PURSe available at the PURSe web site requires that PURSe be installed locally). Therefore, if you have a current installation of MyProxy on your grid, you can use that. It just needs to be version 0.6.5 or higher of MyProxy. You can use the installation notes for the MyProxy that comes with GT4, which is a PURSe compatible version of MyProxy. Or you can upgrade your installation with MyProxy from the MyProxy site.

Some things to keep in mind:

  • If you are upgrading MyProxy from an earlier version, and you wish for users to be able to retrieve their certificates from MyProxy that are stored for them by PURSe, then you need to add the following configuration line in your myproxy-server.config file:
    authorized_key_retrievers "*"
              
    With this, users will be able to retrieve their user certificate and key from MyProxy with their username and password using the myproxy-retrieve command.
  • If you are new to MyProxy configuration and you're looking for a quick start configuration, make sure you have these two lines in myproxy-server.config (these lines should be there in the provided template, so typically you only need to uncomment them):
    accepted_credentials "*"
    authorized_retrievers "*"		  
              

Configuring MySQL database

PURSe uses a MySQL database to store its state, things like the certificate request status of a user (e.g., PENDING, ACCEPTED, etc.). If you already have a MySQL server installed, you can use that. Otherwise you'll need to install MySQL, which you can get from the MySQL site.

In order to create the MySQL PURSe database, do the following:

mysqladmin -h <dbHostName> [-u <user>] [-p] create purseDatabase
        

Where <dbHostName> is the hostname of your MySQL server and <user> is the user with administrative privileges on your MySQL server. Use -p to prompt for password. Now we'll initialize the database:

mysql [-u <user>] [-p] purseDatabase < $PURSE_HOME/etc/purse_database_schema.sql
        

You'll need to have add at least one user account for accessing the PURSe database. To do this, log into the MySQL server with the MySQL client using an administrative MySQL account, and create a user account, with something like the following:

$ mysql [-u <user>] [-p] 
mysql> GRANT ALL ON purseDatabase.* TO 'purseuser'@'portalserver.com'
       IDENTIFIED BY 'password';
        

Then in $PURSE_HOME you need to edit test.properties file, and edit the dbConnectionURL, dbUsername, and dbPassword properties with the values you just specified. Then execute the following:

ant bootstrap
        

Note: ant bootstrap will fail if you don't have a JUnit jar in the $PURSE_HOME/lib directory. You can use this JUnit jar if you wish.