Globus Toolkit 2.2 Installation Instructions

Upgrading Your Globus Toolkit Installation from 2.0 to 2.2

If you have the 2.0 version of the Globus Toolkit installed, and would like to upgrade your installation to 2.2, please follow the Upgrade: items in the sections below.  They discuss the issues involved with upgrading your installation.

In general you should keep the following in mind:

  • Create a new directory to install the Globus Toolkit 2.2 in. If you need to delete your current installation, be sure to back up any configuration files, certificates and keys before doing so.
  • If you have previously run setup-gsi as root, there is no need to do so again, although it should not be harmful if you do.
  • Any manual changes to configuration files in the 2.0 $GLOBUS_LOCATION/etc will need to be migrated to the new installation.
  • Host and service certificates not located in /etc/grid-security, such as the certificates used by MDS will have to be copied to a new location. More on this in the Verification section.

Packaging Overview

The Globus Toolkit 2.2 uses the Grid Packaging Technology for installation. You have two choices for installing the Globus Toolkit.

  1. Install from a binary distribution

    If you are obtaining the Globus Toolkit primarily to build a Grid, to develop Grid-enabled applications using our libraries, or to use our Grid tools, you may choose to obtain precompiled binaries. By doing this, you can save the storage space required by the code and you can skip the compilation phase of your installation.

  2. Install from a source distribution

    If you intend to make changes to the Globus Toolkit code or debug the Globus Toolkit code at the source level, or if you need to install the Globus Toolkit on a system for which precompiled binaries are not available, then you must obtain the source code, compile it yourself using our build tools, and install the resulting libraries and programs.

The first step in either choice is to download and install the Grid Packaging Technology. Once that is installed and configured, you will download and install the bundles of your choice: source or binary.   

To download the Globus Toolkit 2.2 software, please visit the download page.

Setting up Your Environment

Before you build and install the Globus Toolkit, you need to setup your environment.  You will need to set the environment variable GLOBUS_LOCATION to the directory in which you plan to install the Globus Toolkit.  You can do this using the following example for your shell:

    {csh}   setenv GLOBUS_LOCATION  <globus_install_dir>
    {bash}  export GLOBUS_LOCATION=<globus_install_dir>

Note: Be sure to replace "<globus_install_dir>" with an actual directory.

Upgrade: If you are upgrading from 2.0 be sure not to overwrite your existing installation directory, choose a new installation directory to install version 2.2 of the Globus Toolkit.

Next you will need to set GPT_LOCATION.  This environment variable will point to the packaging tools you need to install the Globus Toolkit. We recommend that you install GPT in a different directory than the Globus Toolkit. Examples:

    {csh}   setenv GPT_LOCATION  <gpt_install_dir>
    {bash}  export GPT_LOCATION=<gpt_install_dir>

Note: Be sure to replace "<gpt_install_dir>" with an actual directory.

Upgrade: If you are upgrading, we recommend that you upgrade to a new version of the GPT software. The Globus Toolkit 2.2 has not been tested with older versions of the GPT.

Installing GPT

The Globus Toolkit 2.2 uses the Grid Packaging Toolkit (GPT) packaging software developed at NCSA.  GPT is a multi-platform packaging system used to deploy Grid middleware. This release of the Globus Toolkit may be built using either GPT v1 or GPT v2. Both versions of GPT will build and install the toolkit equally well. The most compelling improvement in GPT 2 is that it makes upgrading individual packages easier. More improvements are expected as the GPT 2 series evolves. GPT 1 does on the other hand provide a code base that has gotten more exposure and thus might be more stable. It should be noted that GPT 2 will eventually obsolete GPT 1.

Before you build and install GPT, you must have your environment setup correctly.  See the section Setting up Your Environment for help on how to do this.  

Untar the distribution and enter the following commands.

   % gzip -dc gpt-*.tar.gz | tar xf -
   % cd gpt-{2.2.2,1.3}
   % ./build_gpt

Note: GPT requires perl 5.005 or later. If your perl 5.005 executable is not named "perl" or is not in your command search path, add --with-perl={perl-cmd} to the build_gpt command to identify the perl executable to be used by the packaging tools.

Note: GPT depends on GNU tar and GNU make.  We have found that on non-GNU (i.e. non-Linux) systems it helps to have these tools available as gtar and gmake.

All of the perl libraries will be installed in $GPT_LOCATION/lib/perl. All of the scripts will be installed into $GPT_LOCATION/sbin.

Binary Bundle Installation

This section will show you how to install a binary bundle.  We will install the toolkit using the linux binary bundle for the Intel i686 platform.  

To install the binary bundle, run one of the following commands:

GPT 2:
   % $GPT_LOCATION/sbin/gpt-install \ 
      globus-all-2.2.2-i686-pc-linux-gnu-bin.tar.gz

GPT 1:
   % $GPT_LOCATION/sbin/globus-install \ 
      globus-all-2.2.2-i686-pc-linux-gnu-bin.tar.gz

Before you can finish your install, you need to source the following file.  To do so, first set your GLOBUS_LOCATION. Then, depending on your shell, run:

   {csh} source $GLOBUS_LOCATION/etc/globus-user-env.csh 
   {sh}  . $GLOBUS_LOCATION/etc/globus-user-env.sh

Once the installation of the binary bundle is complete and you have sourced the above file, run the following commands to complete your installation:

   % $GPT_LOCATION/sbin/gpt-postinstall

If you install any of the SDK bundles, you need to run the following command to get a header file which other header files in the SDK bundle depend on.  GPT 1 users can obtain the globus_core source package here.  GPT 2 comes with globus_core included, you just need to install it.  For <flavor>, specify the flavor of your binary installation.  The binary bundles contained on the download page use gcc32dbg as the build flavor for Linux, and vendorcc32dbg as the build flavor for Solaris.

GPT 2:
   % $GPT_LOCATION/sbin/gpt-build <flavor> -nosrc 

GPT 1:
   % $GPT_LOCATION/sbin/globus-build -install-only \ 
      globus_core-99.tar.gz <flavor>

Next you are ready to configure your installation.  Please see the section, Configuring Your Installation, below.

Source Bundle Installation

This section covers building and installing the Globus Toolkit from the source distribution bundles. 

For each source bundle that you download, use the following procedure to build and install the bundle.  If you are not familiar with the individual bundles, please see the Overview page.

  1. Take a look at the platform notes.
  2. Download a bundle file from the download page.
  3. Enter one of the following commands, substituting the bundle's filename and flavors as recommended in the table below.

    GPT 2:
       % $GPT_LOCATION/sbin/gpt-build <bundle> <flavors>

    GPT 1:
       % $GPT_LOCATION/sbin/globus-build -install-only <bundle> <flavors>

    Note: You can instruct the build to keep logs of the install by including the following in the above command:

    GPT 2:
        -logdir=<log directory>

    GPT 1:
        -log=<log file>

    This chart shows what substitutions to make in the above command. Be sure to use the actual name of the bundle (e.g., globus_data_management_bundle-client-src.tar.gz) in the command.

      BUNDLE FLAVORS
      Data Management Client gcc32dbg
      Data Management SDK gcc32dbg
      Data Management Server gcc32dbg
      Information Services Client gcc32dbgpthr
      Information Services SDK gcc32dbgpthr
      Information Services Server gcc32dbgpthr
      Resource Management Client gcc32dbg
      Resource Management SDK gcc32dbg
      Resource Management Server gcc32dbg
      Replica gcc32dbgpthr
      GSI gcc32dbg

    Note: If you are installing the replica bundle you will have to follow a different set of installation instructions.

    Note: You do not need to install the GSI bundle if you have installed or plan to install any of the other bundles. It is meant for applications which only depend on GSI.

  4. You need to source the following file before we finish our install.  To do so, run the following command depending on your shell:

       {csh} source $GLOBUS_LOCATION/etc/globus-user-env.csh 
       {sh}  . $GLOBUS_LOCATION/etc/globus-user-env.sh

  5. Lastly, run the following commands:

       % $GPT_LOCATION/sbin/gpt-postinstall

An Example Source Installation

Below are the install commands for installing the Data Management client bundle using GPT 2.

(command output has been omitted for brevity where necessary)

   % echo $GLOBUS_LOCATION 
   /usr/local/globus

   % $GPT_LOCATION/sbin/gpt-build \ 
      globus-data-management-client-2.2.2-src_bundle.tar  gcc32dbg

Repeat for each of the bundles that you are installing, with the appropriate flavor each time.  Once you have installed all of the bundles, run the following commands to complete your installation:

   % source $GLOBUS_LOCATION/etc/globus-user-env.csh
   % $GLOBUS_LOCATION/sbin/gpt-postinstall

The next section talks about Configuring Your Installation.

Configuring Your Installation

This section talks about how to configure the Globus Toolkit once you have it installed. 

Upgrade: If you are upgrading your installation of the Globus Toolkit, it is not required that you run 'setup-gsi' below.  However, you will need to migrate any manual change you made to the configuration files in your old installation to your new $GLOBUS_LOCATION.  

The first thing we need to do is complete the setup of GSI, the security software that Globus uses.  To complete the setup of the GSI software, you need to run the following command as root to configure your /etc/grid-security directory:

   % $GLOBUS_LOCATION/setup/globus/setup-gsi

Note: If you do not have root privileges on your machine, you can run setup-gsi with its '-nonroot' option.  This will install the grid security directory to $GLOBUS_LOCATION/etc.  The '-nonroot' option is intended to make client side installations of the Globus Toolkit possible without root access.  It is not intended to provide for a mechanism to run servers from a self contained GLOBUS_LOCATION.

When it asks you if you wish to continue, hit return and then type 'q' followed by another return.

You may exit from your root shell to continue on.

Verification

To verify the installation of the Globus Toolkit on your system, you can run some simple tests.  The following procedure explains how to carry out testing of some of the basic functionality of the Globus Toolkit.

Step 1: Verifying  your installation

To verify that your installation is coherent, i.e. that all package dependencies have been satisfied, run the command:

GPT 2:
   % $GPT_LOCATION/sbin/gpt-verify

GPT 1:
   % $GPT_LOCATION/sbin/gpt_verify

Upgrade:  Users upgrading from 2.0 to 2.2 who in the above chose not to run setup-gsi will receive the following harmless error:

The following setup packages still need to be configured via gpt-    postinstall:
globus_trusted_ca_42864e48_setup-noflavor-pgm

ERROR: The collection of packages in /home/bacon/pkgs/globus-2.2 is not
coherent!

Step 2: Obtaining certificates

Security is at the heart of Globus, and as such, you will not be able to test your Globus configuration until you have obtained a certificate for yourself. Additionally, if you plan on running your own gatekeeper, you will have to request a certificate for your host as well. The gatekeeper must be run on a host which keeps a consistent name (i.e., you should not run it on a computer using DHCP where a different name could be assigned to your computer).

All of the following commands require you to set up your environment. To do so, first set your GLOBUS_LOCATION. Then, depending on your shell, run:

   {csh} source $GLOBUS_LOCATION/etc/globus-user-env.csh 
   {sh}  . $GLOBUS_LOCATION/etc/globus-user-env.sh

Now, to request a user certificate, simply run "grid-cert-request". It will ask for a password to protect your key, and give you a set of instructions for how to mail your request to the CA. We recommend using your regular mail agent to do this. Address an email to ca@globus.org and copy and paste the text from your ~/.globus/usercert_request.pem into that email. Please do not include the file as an attachment.

The instructions from grid-cert-request will recommend using the 'mail' program. We discourage this in these instructions because of several things which could go wrong: You could send email from 'root' or 'globus', which cannot be verified to your user account, you could be sending mail from a machine which cannot receive a reply from the CA, or you might simply be on a machine which cannot send mail in the first place. Using your regular email agent will avoid all of these problems.

Within two business days, your user certificate will be mailed to you. When it arrives, read the contents of the email and you may save the entire email to ~/.globus/usercert.pem. In the end, you will have a userkey.pem and usercert.pem in your $HOME/.globus directory.

If you would like to run a gatekeeper on your machine, you will also need a gatekeeper certificate for your host. Run the following command as root to get a gatekeeper certificate, replacing <FQDN> with the fully qualified hostname of your machine.

   % grid-cert-request -service host -host <FQDN>

Upgrade:  Users upgrading their installation of the Globus Toolkit from 2.0 to 2.2 do not need to replace their existing user certificates, host certificates, or LDAP certificates.  Existing certificates are valid for the 2.2 releases.

Then, using your regular, user mail agent, send an email to ca@globus.org and copy and paste the contents of /etc/grid-security/hostcert_request.pem into it. Please do not include this file as an attachment.

Within two business days, your host certificate will be mailed to you. When it arrives, read the contents of the email and you may save the entire email to /etc/grid-security/hostcert.pem. You will need to be root as this file should be owned by root with permissions 600.

If you want to use authenticated communcation with your LDAP server, you can also request an LDAP certificate for your host at this time. See the section about acquiring an LDAP Certificate in the Admin Guide for details.

Upgrade: If you have a existing LDAP service certificate and key you will need to copy them to either /etc/grid-security/ldap/ldap{cert,key}.pem (preferred) or $GLOBUS_LOCATION/etc/ldap/ldap{cert,key}.pem.

Step 3: Testing your installation

When you have a user certificate, you can use the following tests to verify a working installation.

First launch a gatekeeper by running the following (as yourself):

   % grid-proxy-init
   % globus-personal-gatekeeper -start

This command will output a contact string like "hostname:4589:/O=Grid/O=Globus/CN=Your Name". Substitute that contact string for "<contact>" in the following command: $ globusrun -o -r "<contact>" '&(executable=/bin/date)'

You should see the current date and time. At this point you can stop the personal gatekeeper and destroy your proxy with:

   % globus-personal-gatekeeper -killall
   % grid-proxy-destroy

Step 4: Debugging common errors

Q: When I run "grid-proxy-init", it says "grid-proxy-init: command not found". What should I do?

A: First make sure you set your $GLOBUS_LOCATION, and read in either $GLOBUS_LOCATION/etc/globus-user-env.sh or .csh. If you have done that, and still get this error, run 'ls $GLOBUS_LOCATION/bin' If you do not see grid-proxy-init, your installation is incomplete.

Q: When I run "grid-proxy-init", it says: "no certificate in file File=/home/user/.globus/usercert.pem". What's wrong?

A: Your usercert.pem is empty. You have to save the contents of the email you received from ca@globus.org into this file.

Q: When I run "globus-personal-gatekeeper -start", I get "ERROR: no valid proxy, or lifetime too small (one hour)". What's wrong?

A: Make sure you run grid-proxy-init first. If you ran the proxy-init a long time ago, the proxy may be about to expire. Run grid-proxy-init again.

Q: When I run "globusrun -o -r host.test.edu '&(executable=/bin/date)'", I get "GRAM Job submission failed because an authentication operation failed (error code 7)". What's wrong?

A: Check your /etc/grid-security/grid-mapfile file. It may be malformed or not exist (error code 10). The contents of this file are discussed above.

What can I do now?

While running globus-personal-gatekeeper as a user is a good test, you will want to configure your machine to run the globus-gatekeeper as root, so that other people will be able to use your gatekeeper. If you just run the personal gatekeeper, you won't have authority to su to other user accounts. To setup a full gatekeeper, please see the section Starting GRAM in the Admin Guide.

The Admin Guide also details setting up MDS and a GridFTP server.