gpt-wizard.1 man page, release 0.7.6
NAME
gpt-wizard - Build and install GPT bundles and packages
SYNOPSIS
gpt-wizard -help
gpt-wizard [options] config-file
VERSION
This documentation is for release 0.7.6 of gpt-wizard.
DESCRIPTION
The gpt-wizard command builds and installs a specified set
of GPT bundles and packages, driven by a simple ASCII confi-
guration file. (GPT is the Grid Packaging Toolkit.) The
intent is to automate as much as possible of the process of
installing Globus and other software components, and start-
ing up the services they provide.
Note that some things are difficult or impractical to auto-
mate. (For example, gpt-wizard doesn't attempt to automati-
cally update the /etc/inetd.conf file; there are too many
local conventions to worry about, and many sites manage it
in such a way that any changes would be clobbered.) The
gpt-wizard command keeps track of these manual steps and
prints a summary. This summary is printed in a single
well-marked block at the end of the output.
If the gpt-wizard command is executed from the root account,
most of the installation steps will actually be performed by
a non-root account such as "globus" (see the INSTALLER_USER
configuration option). If it's executed from a non-root
account, all installation steps will of course be performed
by that account; any steps that require root access will be
included in the summary of manual steps to be performed
later.
The gpt-wizard command creates a directory called
.gpt-wizard under the $GLOBUS_LOCATION directory. This
directory will contain a copy of the configuration file and
a plain text file called info, which contains summary infor-
mation about the build, including any manual steps to be
executed.
I highly recommend capturing the output of each gpt-wizard
run in a log file for later perusal.
The web page for the gpt-wizard command is
<http://users.sdsc.edu/~kst/gpt-wizard/>.
The current version of the gpt-wizard command should be
available at
<ftp://ftp.sdsc.edu/pub/sdsc/globus/software/gpt-wizard/>.
Older versions, which are not recommended, are in the OLD
subdirectory.
BACKGROUND
This command is a Perl script which incorporates much of the
experience I've acquired in doing multiple installations of
Globus and NMI software. Rather than keeping track of the
various steps and system-specific exceptions in an
error-prone checklist, I decided to write this Perl script
to do as much of the work as possible for me (lazy bum that
I am).
gpt-wizard is not a "wizard" in the sense used in Microsoft
Windows, i.e., an interactive program that leads the user
through a configuration process step by step. It is a batch
mode configuration and build program; gpt-wizard was just
the cool name I came up with. (Some early unreleased ver-
sions were called install-nmi.)
OPTIONS
gpt-wizard uses Perl's Getop::Long module to parse its
command-line arguments.
Options may be prefixed with either "-" or "--".
Option names may be abbreviated uniquely.
-help
Display a brief help message on stdout and exit.
-version
Display version information and exit.
-validate-only
Validate the configuration file, display some informa-
tion, and exit without building anything. Useful to
detect errors in a configuration file.
-temp-dir DIR
Location for gpt-wizard's temporary working directory.
The temporary directory will be created under the
specified directory. This overrides the TEMP_DIR con-
figuration option. If neither is specified, the
default is /tmp.
-cleanup
Delete the temporary working directory on completion.
Its name will be something like
/tmp/gpt-wizard-1079632649-17640. To use a directory
other than /tmp, specify the "-temp-dir" command-line
option or the TEMP_DIR configuration option. (Prior to
release 0.7.6, "-cleanup" was the default.)
-postinstall
Run the gpt-postinstall command. This is the default
behavior; use "-nopostinstall" if you don't want to run
gpt-postinstall.
-startup
Update system files and start services. This is
allowed only when gpt-wizard is run as root. The
default is "-nostartup". (In some early releases,
"-startup" was the default.)
NOTE: This is currently supported only on Linux sys-
tems.
-gpt-verbose
Pass the "-verbose" option to gpt-install and/or
gpt-build. This will produce voluminous output, espe-
cially when building source bundles and packages. This
is the default; use "-nogpt-verbose" to disable it.
(Prior to release 0.7.6, the "-gpt-verbose" option was
disabled by default.)
-gpt-ignore-errors
Ignore errors from gpt-install and gpt-build. Not
recommended.
-aix-kludge
Use an existing GPT installation. This was implemented
to work around some obscure problems on an AIX system.
Not recommended unless you know what you're doing.
-force-arch
Override the check for supported architectures. This
option is meant for internal development. Not recom-
mended unless you know what you're doing.
-debugging
Enable debugging output.
CONFIGURATION FILE
The gpt-wizard command requires a configuration file to be
specified on the command line. The name of the file is
irrelevant, but for consistency I suggest using a ".gptw"
suffix. I typically use something like
<machine-name>-globus-<version>-<whatever>.gptw
for example,
tg-login1.sdsc.teragrid.org-globus-2.4.3-gcc-r3.gptw
but if you want to call it foobar.baz I won't complain.
The configuration file is a plain text file with a simple
syntax. A '\' character at the end of a line (possibly fol-
lowed by whitespace) indicates a line continuation. Every-
thing from a '#' character to the end of the line is treated
as a comment and ignored. (This means that an option value
cannot include a '#' character; there is no mechanism for
specifying a literal '#'.) Leading whitespace, trailing
whitespace, and empty lines are also ignored. The effect of
combining '\' and '#' characters on the same physical line
is undefined; don't try it.
Each line consists of an option name, followed by whi-
tespace, followed by the value of the option. All option
names must be specified in upper case. The value is gen-
erally an arbitrary string, which may include embedded
blanks. There may be restrictions depending on the type of
the option (see below). String values are not enclosed in
quotation marks; any quotation marks are simply taken as
part of the value. For Boolean option a false value may be
specified as "0", "no", or "false", and a true value may be
specified as "1", "yes", or "true" (without the quotation
marks, of course); the value is case-insensitive. Some con-
figuration options are optional, some are mandatory, and
some may appear multiple times. Certain options may also
have attributes associated with them; these are given in the
form "name=value" on the same line.
If a value starts with ~user, and user has an account on the
system, ~user is replaced with user's home directory. If
there is no such user, it's considered an error. (Replace-
ment of a standalone ~ by the value of $HOME is not sup-
ported.)
Previous versions of gpt-wizard, up to release 0.4, sup-
ported specification of URLs (starting with either "ftp://"
or "http://") for some files. This is no longer supported;
all files must be directly visible. (This feature wasn't
being used, and I'm not certain that it worked properly.)
The DOWNLOAD_DIR and WGET configuration options are no
longer supported.
CONFIGURATION OPTIONS
.PARAM
This is a pseudo-option. It provides a simple macro
facility, particularly useful for creating a set of
similar configuration files for installing the same set
of software at different site.
A .PARAM directive has the form
.PARAM NAME value
Any occurrence of $NAME or ${NAME} will be replaced by
the specified value. The NAME can be any sequence of
upper or lower case letters, digits, or underscores;
upper case letters are recommended. Occurrences of
$NAME or ${NAME} where NAME is not defined as a PARAM
are not replaced.
.PREFIX
This is a pseudo-option. It specifies a default prefix
to be prepended, with a '/' character, to any following
file or directory name given as a relative path name.
It can be used to avoid extremely long lines in confi-
guration files.
CONFIG_FILE_REVISION
Typically an RCS or CVS "Revision" tag, but it can be
any arbitrary string.
Example:
CONFIG_FILE_REVISION $Revision: 1.10 $
Type: string
Optional.
IS_UPDATE
Specifies that this configuration file is for an update
to an existing Globus installation. If this is speci-
fied, the GLOBUS_LOCATION directory must already exist
and should contain a Globus installation; also, the
GPT_TARBALL and GLOBUS_LOCAL_DIRECTORY variables may
not be specified. This feature is new in release
0.7.0, and should be used with some caution.
(This is not to be confused with the UPDATE option,
which specifies an update package. UPDATE options may
be given either for new Globus installations or for
updates to existing ones.) Type: boolean
Optional. Default is 0.
TEMP_DIR
Location for gpt-wizard's temporary working directory.
The temporary directory will be created under the
specified directory. This can be overridden with the
"-temp-dir" command-line option.
Type: existing directory
Optional. Default is "/tmp". This must be specified
as an absolute pathname; it is not affected by .PREFIX.
TAR The full path name of the tar command.
Type: executable file
Optional. This is only necessary if the tar command
does not appear in the PATH specified in the configura-
tion file.
GZIP The full path name of the gzip command.
Type: executable file
Optional. This is only necessary if the gzip command
does not appear in the PATH specified in the configura-
tion file.
PATH The value for the $PATH environment variable.
Mandatory.
ENV An environment variable setting, of the form "VAR" or
"VAR=value". If no value is specified, the variable is
set to the empty string. See also the GLOBUS_HOSTNAME
and INHERIT_ENV options.
Type: string
Optional. May occur multiple times.
INHERIT_ENV
The name of an environment variable to be retained in
the build environment. Environment variables other
than HOME, LOGNAME, SHELL, and USER are deleted to
avoid subtle dependencies on the environment in which
gpt-wizard is executed. It's usually better to use the
ENV option to specify the value of a variable (this
documents the actual value used), but the INHERIT_ENV
option can be used if it's necessary to use whatever
value happens to be in the invoking environment.
MPICH-G2 configuration sometimes requires a valid
$DISPLAY for Java Swing; in this case, use
INHERIT_ENV DISPLAY
See also the ENV option.
Type: string
Optional. May occur multiple times.
INSTALLER_USER
The name of the Unix account to use for the installa-
tion.
Type: string (must be a valid user name)
Optional. Default is "globus" if running as root, the
current user otherwise. If you run gpt-wizard from a
non-root account, you may not specify an INSTALLER_USER
other than your current account; in this case, it may
be best not to specify an INSTALLER_USER at all.
INSTALLER_GROUP
The name of the Unix group to use for the installation.
Type: string (must be a valid group name)
Optional. Default is "globus" if running as root, the
current primary group otherwise. If you run gpt-wizard
from a non-root account, you may not specify an
INSTALLER_GROUP other than your current primary group,
even if you are a member of the specified group; in
this case, it may be best not to specify an
INSTALLER_GROUP at all.
USE_SDSC_SU
Use the non-standard "su" command in use at SDSC.
Probably not useful for sites other than SDSC.
Type: boolean
Optional. Default is 0.
UMASK
Specify an octal umask for the installation. The
default value is almost always best.
Type: string (must be a valid octal number)
Optional. Default is 022.
GPT_TARBALL
The location of the source tarball (*.tar.gz) file for
GPT. Binary and RPM distributions of GPT are not yet
supported though binary and RPM GPT bundles are sup-
ported).
As of gpt-wizard release 0.5, GPT 1.X is no longer sup-
ported; all current Globus releases include GPT 2.X or
better.
Type: file name
Mandatory unless IS_UPDATE is specified.
MPI_FLAVORS_ARE_STATIC
Use the "-static" option when building bundles, pack-
ages, or updates with MPI flavors (such as mpicc32dbg).
This is a workaround for a bug that has shown up on the
TeraGrid. Static flavors are built first so the
default executables in the bin, sbin, and libexec
directories will be non-static.
Type: boolean
Optional. Default is 0.
INTEL_WORKAROUND
Implement a workaround for a problem with the Intel
version 8 compiler (vendorcc flavors). Create a tem-
porary file containing the string "-no-gcc", and set
the $ICCCFG environment variable to the name of the
file. See Globus Bugzilla # 1651,
<http://bugzilla.globus.org/bugzilla/show_bug.cgi?id=1651>.
(This is a bug in the Globus build procedure, not in
Intel's compiler.)
Type: boolean
Optional. Default is 0.
BUNDLE
A GPT bundle or package. It may be a source, binary,
or rpm bundle. (In a future release, gpt-wizard may
require a separate PACKAGE option for packages.) Mul-
tiple bundles may be (and typically are) specified in a
single config file. If necessary, the same bundle may
be specified multiple times with different attributes,
for example if it's necessary to build a bundle with
"-static" for some flavors and without "-static" for
others.
Attributes:
kind=binary or kind=source or kind=rpm
flavor=<flavor>
option=<option>
If a kind is not specified, gpt-wizard attempts to
guess based on the file name.
Multiple flavors may be specified, separated by commas,
e.g., "flavor=gcc32dbg,gcc32".
Options are passed to gpt-install or gpt-build, after
expanding commas to blanks.
Type: file name
Mandatory unless IS_UPDATE is specified. Multiple bun-
dles may be specified.
UPDATE
A GPT update package. This is normally a source pack-
age. The same attributes may be specified as for bun-
dles, but it's not usually necessary to specify fla-
vors. gpt-wizard will determine the necessary flavors
by examining the existing copy of the specified pack-
age. Some heuristics are applied to determine the best
order of flavors (since the last flavor built deter-
mines the default executable in the bin, sbin, or
libexec directory). See the By_Flavors and
Get_Update_Flavors functions if you're curious about
the heuristics.
gpt-wizard cannot currently determine which flavors
need to be built with the "-static" option and which do
not. As a workaround, you can specify the "flavor=..."
and "option=..." attributes explicitly. If some fla-
vors need to be built with different options (particu-
larly "-static"), you can specify the same update pack-
age twice with different attributes. As a special
case, the MPI_FLAVORS_ARE_STATIC option specifies that
all flavors whose names start with "mpi" (such as
"mpicc32dbg") are to be built with "-static".
Type: file name
Optional. Multiple update packages may be specified.
PRE_POSTINSTALL
An ugly kludge to specify a command to be executed
before running gpt-postinstall. So far, I have only
used this on AIX to run mds-aix-relink.sh, which works
around some AIX-specific libtool problems. Any
occurrence of the string "BUILD_DIR" is replaced with
the name of the temporary build directory.
Not recommended unless you know what you're doing.
Type: string (must be a valid command).
Optional.
GPT_LOCATION
The location in which to install GPT, the Grid Packag-
ing Toolkit. If this is not specified, use the same
directory as GLOBUS_LOCATION.
Type: new directory (must be empty if it already
exists).
Optional.
GLOBUS_LOCATION
The location in which to install the Globus toolkit and
other components.
Type: new directory (must be empty if it already
exists).
Mandatory.
GLOBUS_LOCAL_DIRECTORY
A local directory in which to install the "var" and
"tmp" directories and certain files under the "etc"
directory. If GLOBUS_LOCATION is on an NFS-mounted
file system, the gatekeeper (which runs as root) will
often not be able to write to its log file,
$GLOBUS_LOCATION/var/globus-gatekeeper.log. Also, some
files need to be unique for each system on which Globus
services are running. See Globus Bugzilla #660,
<http://bugzilla.globus.org/bugzilla/show_bug.cgi?id=660>.
If GLOBUS_LOCAL_DIRECTORY is specified (normally on a
local filesystem), certain subdirectories and files
will be created as symbolic links into the specified
directory.
Type: new directory (must be empty if it already
exists).
Optional.
Note: This replaces and generalizes the
GLOBUS_VAR_DIRECTORY configuration option from earlier
versions of gpt-wizard.
GLOBUS_HOSTNAME
Set the environment variable $GLOBUS_HOSTNAME to the
specified value. If the system host name (the value
printed by the hostname(1) command) doesn't match the
primary name by which the system is known on the net-
work (via a reverse DNS lookup), GLOBUS_HOSTNAME should
be set to the network name. If the system host name is
the local portion of the network name (for example, if
the hostname(1) command prints "foobar", and the net-
work name is "foobar.bigschool.edu"), it's probably not
necessary to set GLOBUS_HOSTNAME. This option is not
exactly equivalent to
ENV GLOBUS_HOSTNAME=...
since it also causes the $GLOBUS_HOSTNAME environment
variable to be set in inetd or xinetd.
Type: string
Optional.
GRID_MAPFILE
The name of a file to be copied to
/etc/grid-security/grid-mapfile if the "-startup"
option is specified. This is a text file mapping
Globus certificate subject names to Unix account names.
See the Globus documentation for more information.
Type: file name
Optional.
HOST_CERT
The name of a file containing the Globus host certifi-
cate, also known as the gatekeeper certificate. It
will be copied to /etc/grid-security/hostcert.pem if
the "-startup" option is specified.
Type: file name
Optional.
HOST_KEY
The name of a file containing the Globus host private
key, also known as the gatekeeper key. It will be
copied to /etc/grid-security/hostkey.pem if the
"-startup" option is specified.
Type: file name
Optional.
LDAP_CERT
The name of a file containing the Globus LDAP certifi-
cate, to be used for non-anonymous MDS queries (see the
grid-info-search command). It will be copied to
/etc/grid-security/ldap/ldapcert.pem if the "-startup"
option is specified.
Type: file name
Optional.
LDAP_KEY
The name of a file containing the Globus LDAP private
key, to be used for non-anonymous MDS queries (see the
grid-info-search command). It will be copied to
/etc/grid-security/ldap/ldapkey.pem if the "-startup"
option is specified.
Type: file name
Optional.
BATCH_SYSTEM
For Globus 2.X releases prior to 2.2, this specifies a
batch system to be used. Allowed values are condor,
easymcs, fork, glunix, grd, loadleveler, lsf, nqe,
nswc, pbs, pexec, and prun. Starting with Globus 2.2,
batch systems are configured by installing an addi-
tional package, making this option obsolete.
Type: string
Optional.
JOB_MANAGER
For Globus 2.X releases starting with 2.2, specify a
job manager. The first argument is the name of the
batch system; other arguments are passed to the setup
script.
Example:
JOB_MANAGER pbs -cpu-per-node 2 -remote-shell ssh
Type: job_manager
Optional.
MPICH-G2
The name of a tarball file (*.tar.gz) containing
sources for MPICH, used to build and install MPICH-G2.
A .globus_location file will be created in the MPICH-G2
installation directory, containing the full path for
$GLOBUS_LOCATION.
This option is newly implemented; use with caution.
See <http://www3.niu.edu/mpi/> for more information on
MPICH-G2. Attributes:
flavor=<flavor>
install=<installation-directory>
arch=<arch>
The mandatory "flavor" attribute specifies the Globus
flavor to be used to build MPICH-G2.
The mandatory "install" attribute specifies the instal-
lation directory for MPICH-G2. If this is a relative
path, it specifies a subdirectory of $GLOBUS_LOCATION.
The optional "arch" attribute specifies the architec-
ture, to be passed to the MPICH "configure" script;
this is usually not necessary.
For example, the following line:
MPICH-G2 mpich-1.2.5.2.tar.gz \
flavor=mpicc32dbg \
install=mpich-g2-1.2.5.2
causes the MPICH "configure" script to be invoked as
follows:
./configure \
-device=globus2:-flavor=mpicc32dbg \
-prefix=$GLOBUS_LOCATION/mpich-g2-1.2.5.2
Type: mpich-g2
Optional.
CA_CERT_TARBALL
The name of a tarball file (*.tar.gz) containing certi-
ficates and signing policies for one or more certifi-
cate authorities. The certificate (*.0) and policy
(*.signing_policy) files should be at the top level of
the tarball. By default, only the Globus CA is recog-
nized; since the Globus CA has expired, it will be
necessary to install one or more others. One possible
value is a local copy of
ftp://ftp.sdsc.edu/pub/sdsc/globus/CA/certificates.tar.gz
(but be sure to read the enclosed README file before
deciding to use it).
Type: file name
Optional.
SECURITY
Much of the Globus Toolkit is concerned with security. This
doesn't necessarily mean that using Globus makes your system
secure; in fact, there are a number of things you can do
wrong that can make your system or your account less secure.
Globus certificates, such as hostcert.pem, ldapcert.pem, and
usercert.pem, may be made publicly visible without any
danger. The corresponding private key files, however, must
be kept secret. If any of these files are revealed, a mali-
cious user could possibly masquerade as your system or as
you.
The file /etc/grid-security/grid-mapfile specifies the map-
ping of Globus subject names to user names. This file can
be publicly visible, but must be modifiable only by trusted
users.
This section does not purport to be a complete summary of
Globus security issues. It may not even be entirely
correct.
The gpt-wizard command attempts to install files with the
correct ownership and permissions, but does not otherwise
deal directly with security issues. If you think you've
found a security-related problem in gpt-wizard, please let
me know as soon as possible by e-mail to kst@sdsc.edu.
REFERENCES
GPT GPT is the Grid Packaging Toolkit, developed at NCSA.
It is the method used to install Globus for releases
2.0 and later. A version is provided with the Globus
Toolkit; see also <http://www.gridpackagingtools.org/>.
Globus Project
The Globus Project develops the Globus Toolkit. If
you've read this far, you probably already know what
that is.
See <http://www.globus.org>.
NMI NMI, or NSF Middleware Infrastructure, is a project
sponsored by the National Science Foundation. The pro-
ject packages and distributes Globus and other
grid-related software components.
See <http://www.nsf-middleware.org>.
SDSC The San Diego Supercomputer Center,
<http://www.sdsc.edu>. The author of gpt-wizard works
there. Hi.
NCSA The National Center for Supercomputing Applications,
<http://www.ncsa.uiuc.edu>. GPT, the Grid Packaging
Toolkit, was developed there.
EXIT STATUS
The gpt-wizard command returns an exit status of zero if it
succeeds, non-zero if it fails.
BUGS
The "TO DO" section in the gpt-wizard script itself includes
a number of ideas for features that I intend to implement.
There are undoubtedly many other good ideas that I haven't
thought of yet, and bugs that I haven't yet found.
This documentation would probably benefit from some outside
review. If anything here is unclear, it's probably the
author's fault, not the reader's fault.
Please send any bug reports or suggestions to the author by
e-mail.
AUTHOR
Keith Thompson, San Diego Supercomputer Center,
<kst@sdsc.edu>
Man(1) output converted with
man2html