Globus Toolkit 2.0 Installation Instructions

Packaging Overview

The Globus Toolkit 2.0 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 any of the software described here, visit the Globus Toolkit 2.0 download page.

How do I build and install these bundles?

To download the Globus Toolkit 2.0 software, visit the download page.

You will be presented with two options. One is to install precompiled binary bundles for your system type. If your system is not represented in the binary packages, or if you prefer to build the toolkit yourself, you may download source bundles instead.

Whether you are going to install precompiled binary bundles or build the source bundles, you will need to download and build the Grid Packaging Tools (GPT). This is covered below.

Requirements

The packaging tools are written in perl. An installation of Perl 5.005 or greater is required on your system. Perl can be downloaded from www.perl.com.

Setting Up a Packaging Environment

There is one environment variable (GLOBUS_LOCATION) required to use the packaging framework. This is the location where the output of builds/install of Globus packages will be placed. You can switch between multiple installations by changing the value of $GLOBUS_LOCATION.

There is an optional environment variable (GPT_LOCATION) that will effect the packaging infrastructure. This can be used to have the packaging tools installed in a separate location from Globus packages. You do not have to however, define GPT_LOCATION. If you do not, the packaging tools will be installed behind GLOBUS_LOCATION, as is most commonly done.

In the instructions below, we show how to build if you have set both GPT_LOCATION and GLOBUS_LOCATION. However, we do not expect that every user will want to maintain separate directories for Globus and its packaging toolkit. If you would like, simply replace GPT_LOCATION with GLOBUS_LOCATION throughout the instructions below to install both the packaging toolkit as well as the Globus toolkit in the same location, as is most commonly done. That way, you will only have to set one environment variable, GLOBUS_LOCATION.

Installing Globus Packaging Tools

This step is required for both binary and source bundles. Untar the distribution and enter the following commands.

   % cd gpt-1.0
   % ./build_gpt

Note: 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.

All of the perl libraries will be installed in $GPT_LOCATION/lib/perl. All of the scripts will be installed into $GPT_LOCATION/sbin. (If $GPT_LOCATION is not set, $GLOBUS_LOCATION will be used for both of the above locations.)

Building from a Binary Distribution

This section will show you how to install a bundle using the linux architecture binaries. Change names as appropriate for different platforms.

   % $GPT_LOCATION/sbin/globus-install \ 
      globus_data_management_bundle-server-linux-i686-gcc32.tar.gz

Note: Remember to replace GPT_LOCATION with GLOBUS_LOCATION if you did not create a separate packaging directory.

Once you have installed all of the binary bundles you wish to install with the above command, run the following command to complete your installation.

   % $GPT_LOCATION/sbin/gpt-postinstall

Building from a Source Distribution

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

For each source bundle that you download, use the following procedure to build and install the bundle.

  1. Download the bundle file from the download page.
  2. Enter the following command, substituting the bundle's filename and the options and flavors as recommended in the table below.

    Note: Remember to replace GPT_LOCATION with GLOBUS_LOCATION if you did not create a separate packaging directory.

       % $GPT_LOCATION/sbin/globus-build -install-only \ 
          bundle options flavors

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

        -log=./build.log

    This chart shows how to substitute in the above command. Use the actual name of the bundle (e.g., globus_api_bundle.tar.gz) in the command.

      BUNDLE OPTIONS   FLAVORS
      Data Management Client   gcc32dbg
      Data Management SDK gcc32dbg
      Data Management Server -static=1   gcc32dbg
      Information Services Client   gcc32dbgpthr
      Information Services Server   gcc32dbgpthr
      Resource Management Client   gcc32dbg
      Resource Management SDK gcc32dbg
      Resource Management Server -static=1   gcc32dbg


  3. Enter the following command.

    Note: Remember to replace GPT_LOCATION with GLOBUS_LOCATION if you do not have a separate packaging directory.

       % $GPT_LOCATION/sbin/gpt_verify 

  4. When you're done installing, enter the following command.

       % $GLOBUS_LOCATION/sbin/gpt-postinstall

An Example Source Installation

Below are the install commands for a full installation of all four packages where the Grid Packaging Toolkit (GPT) has been installed in GLOBUS_LOCATION. Your install commands may look different if you do not install all of the packages or specify a GPT_LOCATION.

(command output has been omitted for brevity where necessary)

   % echo $GLOBUS_LOCATION 
   /usr/local/globus

   % $GLOBUS_LOCATION/sbin/globus-build -install-only \ 
      globus_data_management_bundle-client-src.tar.gz 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, use the gpt-postinstall command:

% $GLOBUS_LOCATION/sbin/gpt-postinstall

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


   % $GLOBUS_LOCATION/sbin/gpt_verify 
   

Next, we will verify our installation.

How do I verify a working installation?

Step 1: 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

Errata: Sourcing globus-user-env defines a MANPATH environment variable. On some linux distributions, this may cause your man utility to operate incorrectly if it uses a config file in /etc.

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 for 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 -host <FQDN> \
      -key /etc/grid-security/hostkey.pem \
      -cert /etc/grid-security/hostcert.pem \
      -req /etc/grid-security/host.req

Then, using your regular, user mail agent, send an email to ca@globus.org and copy and paste the contents of /etc/grid-security/host.req 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 titled "MDS Configuration" for details.

Step 2: Verifying 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 3: 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 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, you will need to make the following modifications as root:

In /etc/services, add the service name "globus-gatekeeper" to port 2119.


gsigatekeeper      2119/tcp                   # Globus Gatekeeper

Depending on whether your host is running inetd or xinetd, you will need to modify it's configuration. If the directory /etc/xinetd.d/ exists, then your host is likely running xinetd. If the directory doesn't exist, your host is likely running inetd. Follow the appropriate instructions below according to what your host is running.

    Inetd
    For inetd, add the following entry, all on one line, to /etc/inetd.conf. Be sure to replace GLOBUS_LOCATION below with the actual value of $GLOBUS_LOCATION in your environment.


       gsigatekeeper stream tcp nowait root
          GLOBUS_LOCATION/sbin/globus-gatekeeper globus-gatekeeper
          -conf GLOBUS_LOCATION/etc/globus-gatekeeper.conf

    Xinetd
    For xinetd, add a file called "globus-gatekeeper" to the /etc/xinetd.d/ directory that has the following contents. Be sure to replace GLOBUS_LOCATION below with the actual value of $GLOBUS_LOCATION in your environment.


       service gsigatekeeper
       {
          socket_type  = stream
          protocol     = tcp
          wait         = no
          user         = root
          server       = GLOBUS_LOCATION/sbin/globus-gatekeeper
          server_args  = -conf GLOBUS_LOCATION/etc/globus-gatekeeper.conf
          disable      = no
       }

After you have added the globus-gatekeeper service to either inetd or xinetd, you will need to notify inetd (or xinetd) that its configuration file has changed. To do this, follow the instructions for the server you are running below.

    Inetd
    On most linux systems, you can simply run `killall -HUP inetd`

    On other systems, the following has the same effect: ps aux | grep inetd | awk '{print $2;}' | xargs kill -HUP

    Xinetd
    On most linux systems, you can simply run `killall -USR1 xinetd`

    On other systems, the following has the same effect: ps aux | grep xinetd | awk '{print $2;}' | xargs kill -USR1

    Errata: During startup, xinetd checks to see which services are available. If none exist (or they are all commented out), then xinetd will exit. To start xinetd, run either "/etc/rc.d/init.d/xinetd start" or "/etc/init.d/xinetd start" depending on how your system is configured.

Next you need to add your certificate subject corresponding to your username to /etc/grid-security/grid-mapfile. To do this, run the following command as yourself:


   % grid-cert-info -subject
   % whoami

This will output something like "/O=Grid/O=Globus/CN=Your Name" and "user". Now, as root, create the file /etc/grid-security/grid-mapfile with an entry of:


   "/O=Grid/O=Globus/CN=Your Name" user

Note: Be sure to include the quotes around your certificate subject and not around your username.

Now you're ready to test the installation. As yourself, run:


   % grid-proxy-init
   % globusrun -o -r localhost '&(executable=/bin/date)'

You should see the current date and time.

MDS Configuration

Configuration of the MDS 2.1 release requires the following basic steps:

  1. Obtain required certificate
  2. Start MDS
  3. Send a test query to GRIS and GIIS

These steps are described in detail in the following paragraphs.

  1. Obtain required certificate

    MDS requires an X.509-compatible LDAP server certificate.

    A server certificate is needed by the LDAP service in order to run. To request a server certificate, use the grid-cert-request command below.


       % grid-cert-request -cn "ldap/<FQDN>" \ 
          -cert $GLOBUS_LOCATION/etc/server.cert \
          -key $GLOBUS_LOCATION/etc/server.key \
          -req $GLOBUS_LOCATION/etc/server.request -nopw \
          -dir $GLOBUS_LOCATION/etc

    Replace <FQDN> with the fully qualified domain name of the host that will run the ldap server.

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

    Within two business days, your LDAP certificate will be mailed to you. When it arrives, read the contents of the email and you may save the entire email to GLOBUS_LOCATION/etc/server.cert. You will need to be root as this file should be owned by root with permissions 600.

    Errata: I had to edit $GLOBUS_LOCATION/etc/grid-info-slapd.conf and change:

    modulepath /usr/local/globus/libexec/openldap/gcc32dbg

    to

    modulepath /usr/local/globus/libexec/openldap/gcc32dbgpthr

  2. Start MDS.

    Start MDS 2.1 with the following command:


       % GLOBUS_LOCATION/sbin/SXXgris start

    This command starts the OpenLDAP 2.0 slapd server for the GRIS. It does not require environment variables $GLOBUS_LOCATION to be set.

    Note that there is no longer an SXXgiis start. There is a single slapd instance for both GRIS and GIIS.

  3. Send a test query to GRIS and GIIS.

    Send a test query to GRIS on a local host, with the following command:


       % GLOBUS_LOCATION/bin/grid-info-search -anonymous -L

    If you have any questions, try the MDS FAQ.

Setting up a Grid-FTP server (wu-ftpd)

Setting up GridFTP is similar to setting up a gatekeeper. Make the following changes to your system as root:

Add an entry to /etc/services reading:


   gsiftp  2811/tcp

Depending on whether your host is running inetd or xinetd, you will need to modify it's configuration file.

    Inetd
    For inetd, add the following entry, all on one line, to /etc/inetd.conf. Be sure to replace GLOBUS_LOCATION below with the actual value of $GLOBUS_LOCATION in your environment.


        gsiftp  stream  tcp     nowait  root
        GLOBUS_LOCATION/sbin/in.ftpd in.ftpd -l -a

    Xinetd
    For xinetd, add a file called "gsi-wuftpd" to the /etc/xinetd.d/ directory that has the following contents. Be sure to replace GLOBUS_LOCATION below with the actual value of $GLOBUS_LOCATION in your environment.


        service gsiftp
        {
        instances               = 1000
        socket_type             = stream
        wait                    = no
        user                    = root
        server                  = GLOBUS_LOCATION/sbin/in.ftpd
        server_args             = -l -a -G GLOBUS_LOCATION
        log_on_success         += DURATION USERID
        log_on_failure         += USERID
        nice                    = 10
                disable                 = no
        }

After you have added the gridftp service to either inetd or xinetd, you will need to notify inetd (or xinetd) that its configuration file has changed. To do this, follow the instructions for the server you are running below.

    Inetd
    On most linux systems, you can simply run `killall -HUP inetd`

    On other systems, the following has the same effect: ps aux | grep inetd | awk '{print $2;}' | xargs kill -HUP

    Xinetd
    On most linux systems, you can simply run `killall -USR1 xinetd`

    On other systems, the following has the same effect: ps aux | grep xinetd | awk '{print $2;}' | xargs kill -USR1