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:
make gsi-myproxy. This will build MyProxy as well as simpleCA and their dependencies.
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.
|If running the install script from its directory, then PWD would be the value|
|Provide the path to the bzip2 Globus Toolkit 4 tarball|
|A location where the script can build the Globus code.|
|A directory in which the install script will place various scripts, etc.|
|The location of an existing Globus deployment, or the place where you want the install script to install Globus.|
|The location where SimpleCA should be deployed.|
|The distinguished name or subject of your SimpleCA.|
|The email of your certificate authority (CA) administrator.|
|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.|
|The 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.|
|These MySQL properties are fairly self-explanatory.|
|Optional, although may be necessary if the MySQL installation is not on the user's command path.|
|The password used by PURSe to encrypt users' passwords stored in the MySQL database.|
|Hostname of the server running a mail server.|
|Hostname 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"
<GLOBUS_LOCATION>is the GLOBUS_LOCATION defined in the install.conf file and likewise for
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
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
(or some other non-root grid user account). By default, the
simpleCA directory will be installed in the
.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
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
script, you're not required to pass it the
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
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:
myproxy-server.config(these lines should be there in the provided template, so typically you only need to uncomment them):
accepted_credentials "*" authorized_retrievers "*"
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
<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';
$PURSE_HOME you need to edit
test.properties file, and edit the
dbPassword properties with
the values you just specified. Then execute the following:
ant bootstrap will fail if you don't
have a JUnit jar in the
You can use
this JUnit jar if you wish.