# $Id: README,v 1.11 2007/04/25 02:59:06 kst Exp $
# $Source: /projects/globus/kst/CVS/public_html/gx-map/README,v $
# [ Id: README,v 1.33.2.1 2007/03/02 09:23:02 kst Exp ]
# [ Source: /projects/globus/kst/CVS/tools/gx-map/README,v ]

This is gx-map, a system for automated updates of Globus grid-mapfiles
and CA files.  The current release is 0.5.3.3.  The primary documentation
is in the man pages (new in release 0.5.1) and on the gx-map web site,
<http://users.sdsc.edu/~kst/gx-map/>.

The "gx-request" command is used to request the addition or deletion
of an entry in the Globus grid-mapfile.  In the simplest case, users
can run "gx-request -quick-add"; this will generate a request to add
a mapping for the DN extracted from the user's default proxy or user
certificate, asking for verification before submitting the request.
"gx-request -quick-remove" generates a removal request.  For more
complex actions, users can run "gx-request -interactive" and follow
the instructions, or use other command-line options.  Run "gx-request
-help" or see the gx-request(1) man page for details.

(Prior to release 0.4.5, the "gx-request" command was called "gx-map";
it can still be invoked by the old name, but the "gx-map" command
will be removed in a future release.)

A user may map an arbitrary DN (distinguished name) to his own
Unix account.  An administrator (as specified in the config file)
may map any DN to any Unix account.

Some DNs may be mapped automatically without user intervention; in
particular, certificates issued by the NPACI and SDSC certificate
authorities (cacl) are automatically mapped to the corresponding user
account.  This is handled by a separate tool (not included here) that
watches for updates in the cacl index files and invokes gx-request.
This applies only to systems within SDSC.  Other sites may implement
similar tools.

All commands accept a "-help" option to print a brief usage message and
a "-version" option to display the current version.  The gx-request
command also accepts a "-long-help" option with information on
non-interactive use.

The 0.5.1 release adds support for propagation of information across
sites, using the optional gx-propagate command.

The 0.5.2 release, in addition to the gx-propagate command, adds an
optional TGCDB subsystem.  This is specifically intended for use with
the TeraGrid Central Database.  See README.TeraGrid for details.

The 0.5.3, and 0.5.3.X releases are compatible with the 0.5.2 release,
but are designed to be more convenient for administrators.  See the
Relnotes file for details.  0.5.3.2 is a TeraGrid-specific update.
0.5.3.3 is a security update; it can also be applied as a patch to an
existing 0.5.3.2 installation using the provided "patch-gx-map-0.5.3.2"
script.

The gx-ca-update command (added in release 0.4.0) handles automated
installation and maintenance of certificate, signing_policy, and CRL
files for CAs (Certificate Authorities).

    README              This file, general information
    README.TeraGrid     TeraGrid-specific information (which may also
                        be of interest for non-TeraGrid sites).
    README.Upgrade      Upgrading from gx-map 0.3 or 0.4.X to 0.5.X.

The README, README.*, and Relnotes files are installed in the
etc/gx-map subdirectory when you install gx-map.

                -- Keith Thompson <kst@sdsc.edu> Thu 2007-03-01