TeraGrid Client Toolkit
=======================


Installing
----------

To install the TCT, simply unpack the archive, change into the top-level
unpacked directory, and run the installer script:

$ tar xzf teragrid-client-*.tgz
$ cd teragrid-client-*
$ ./install-teragrid-client

The installer will take some time to complete, as it downloads needed
packages and lays out files on disk. A progress bar will give a rough
indication how the install is proceeding.
If the machine you are installing on requires a proxy in order to access
the Web, you can use the TERAGRID_CLIENT_HTTP_PROXY envrionment variable
to specify the proxy when invoking the installer:

$ TERAGRID_CLIENT_HTTP_PROXY=http://squid.cs.wisc.edu:3128 \
  ./install-teragrid-client

The installer output is terse, but a detailed log of its actions is written
to a file named install.log. If the installation fails, this file is the
place to look for more detailed information.

A common problem during installation occurs if your operating system is either
not supported by Pacman (the package management utility used by TCT), or not
directly supported by the TCT's online package repository. You may see an
error like this in your install.log file:

- Platform [Ubuntu-8] is not yet supported.
- Contact Pacman headquarters at http://physics.bu.edu/pacman/ to request a new platform.
- Use [% pacman -pretend-platform <platform>] to override.

On Linux, the environment variable TERAGRID_CLIENT_PLATFORM can often be set
to a compatible platform name in order to work around this problem. For example:

$ TERAGRID_CLIENT_PLATFORM=linux-rhel-5 ./install-teragrid-client


Preparing For Use
-----------------

To use the TCT once installed, some environment variables need to be set.
This can be done as follows:

# for bash
$ source /path/to/teragrid-client-*/setup.sh

# for tcsh
% source /path/to/teragrid-client-*/setup.csh

Of course, the "source" command can be added to the appropriate login script
for your shell so that it is not necessary to execute it again every time you
login.

Once the environment is set up, the commands provided by the TCT (such as
myproxy-logon, gsissh, and globus-job-run) will be available.


Single Sign-On
--------------

One benefit of installing the TCT is that you can take advantage of TeraGrid's
single sign-on mechanism. This is done using the myproxy-logon program. For
example:

$ myproxy-logon -l gregquin
Enter MyProxy pass phrase:
A credential has been received for user gregquin in /tmp/x509up_u1000.

You'll want to use the same username/password combination that you use for
accessing the TeraGrid User Portal. One you have logged in, use of other
tools provided by the TCT to interact with TeraGrid resources will not
require you to reenter your login information.


Capabilities
------------

Currently supported capabilities provided by the TCT include single sign-on
(described above), remote login, remote data movement, and remote data
movement. More capabilities will be provided as the toolkit matures. Please
refer to the following resources for more information on supported
capabilities.

* Remote Login: http://www.teragrid.org/userinfo/access/ssh.php
    (See "GSI-Enabled SSH section.)

* Remote Data Movement: http://www.teragrid.org/userinfo/data/transfer.php
    (Currenly, globus-url-copy and uberftp are in the TCT, but not tgcp.)

* Remote Job Submission: http://www.teragrid.org/userinfo/jobs/gram.php


Uninstalling
------------

To completely remove the TCT from a system, simply remove its directory:

$ rm -rf /path/to/teragrid-client-*

Alternatively, only the files that were downloaded and installed over the
network when the installer script was run can be removed as follows:

$ cd /path/to/teragrid-client-*
$ ./uninstall-teragrid-client
