source: trunk/athena/bin/getcluster/getcluster.1 @ 25648

.TH GETCLUSTER 1 "20 July 2012" "debathena-clusterinfo" "Hesiod Cluster Information"
.SH NAME
getcluster \- retrieve service cluster info from Hesiod 
.SH SYNOPSIS
.B getcluster
[
.B \-b | 
.B \-p
] [
.B \-d
] [
.B -h
.I hostname
] version
.PP
.SH DESCRIPTION
.B getcluster
queries the Hesiod database for service cluster information associated
with the workstation on which it is run.  It writes a set of environment
variable assignments on its standard output in a format acceptable
to the C shell, or, if the
.B \-b
flag is present, in Bourne shell syntax.
If the 
.B \-p
flag is present, the results are written in space-separated key-value
pairs, suitable for parsing by things that are not shells.  
.B \-p
and
.B \-b
are mutually exclusive. 
.B getcluster
returns an exit status of 2 if no cluster information is available, or
1 if any other error was encountered.
.PP
A cluster record contains between two and four fields: a
variable name, a value, an optional version number, and an optional
list of flags.  The version number is a dotted pair giving the major
and minor numbers of the Athena release to which the variable
definition applies.  Currently, the only defined flag is 't',
indicating that the Athena release specified by the version is in
testing.
.PP
By default,
.B getcluster
looks up cluster information for the current hostname.  This name may
be overridden by the contents of the file
.B /etc/cluster
or via the command line using the
.B \-h
option.  A cluster name such as
.B public-linux
may be given in place of a hostname.
.PP
If
.B /etc/cluster.fallback
is present, that file is read and the cluster records in it are
considered lower priority than the Hesiod cluster records.  For each
variable name in the Hesiod cluster record, no record with the same
variable name in the fallback file will be considered.  If
.B /etc/cluster.local
is present, that file is read and the cluster records in it are
considered higher priority than the Hesiod cluster records and
fallback cluster records.
.PP
.B getcluster
may discard a cluster record if it specifies a version which is
higher than the current workstation version (as given by the
.I version
argument on the command line).  A record with a new version is
rejected if any of the following are true:
.TP 3
1.
The environment variable
.B AUTOUPDATE
is not defined or has a value other than "true".
.TP 3
2.
The record specifies the 't' flag.
.TP 3
3.
The environment variable
.B UPDATE_TIME
is not defined or specifies a Unix time value greater than the current
time.
.PP
After discarding records for the above reasons,
.B getcluster
outputs variable definitions for each of the variables mentioned in
the remaining records.  For each variable,
.B getcluster
selects the value given in the record with the highest version number,
or uses a record with no version number if no records with version
numbers are present.
.PP
.I getcluster
may also output three special variable definitions:
.IP NEW_TESTING_RELEASE
If any records were discarded because they contained the 't' flag and
specified versions greater than the current workstation version,
.B NEW_TESTING_RELEASE
is set to the highest version number given in those records.
.IP NEW_PRODUCTION_RELEASE
If any records were discarded because they specified versions greater
than the current workstation version and the
.B AUTOUPDATE
environment variable was not "true,"
.B NEW_PRODUCTION_RELEASE
is set to the highest version number given in those records.
.IP UPDATE_TIME
If any records specified higher version numbers than the current
workstation version and were not discarded for the first two reasons,
.B UPDATE_TIME
is set to a time at which the workstation should accept the new
values.  The value is taken from the current value in the environment
if it is present; otherwise a random Unix time value between the
current time and four hours in the future is chosen.  The random
number generator is seeded with the IP address given in the
.B ADDR
environment variable, or with a fixed value if none is specified.
.PP
If the
.B \-d
flag is present,
.I getcluster
will ignore the hostname argument and instead read lines from standard
input, treating each line as if it were an entry in the Hesiod
database for the host's cluster information.
.PP
.I getcluster
is usually invoked from
.I save_cluster_info (8),
which places its output in the files
.I /var/run/athena-clusterinfo.csh
and
.I /var/run/athena-clusterinfo.sh
to be accessed by the C shell in a user's .login file and the Bourne
shell in a user's .profile, respectively.  It may also be invoked
directly by any user.
.PP
.B getcluster
uses the Hesiod type
.BR cluster .
.SH DEPRECATED SYNTAX
For compatibility with older versions of
.BR getcluster ,
a command-line argument may be given before the version number.  (This
is how the hostname used to be specified; now it is ignored.)  The
name of the fallback and local cluster files may be controlled using
the
.B \-f
and
.B \-l
options, but there is no good reason to do so.
.SH EXAMPLES
# C shell example
.br
getcluster 5.3 > file; source file
.PP
# Bourne shell example
.br
getcluster -b 5.3 > file; . file
.SH "SEE ALSO"
`Hesiod - Project Athena Technical Plan -- Name Service', save_cluster_info(8)
.SH AUTHOR
Steve Dyer, IBM/Project Athena
.br
Greg Hudson, MIT Information Systems
.br
Copyright 1987, 1997, Massachusetts Institute of Technology
.br
.SH BUGS
If there exist two unversioned tags of the same name, getcluster will
pick whichever one comes last (either in Hesiod output or in a local
file).  This can be regarded as a feature instead of a bug.

.B getcluster 
does not quote its shell output, nor does it do any checking
of key names.  This means that if you have a key named "path" or have a
value with the content of ";rm -rf *", you probably shouldn't eval or
source its output.