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

.TH GETCLUSTER 8 "3 July 1997"
.SH NAME
getcluster \- retrieve service cluster info from Hesiod as environment vars
.SH SYNOPSIS
.B getcluster
[
.B \-b
] [
.B \-d
] [
.B -l local
] [
.B -f fallback
] hostname version
.PP
.SH DESCRIPTION
.I 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.
.I 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
If a fallback cluster information file is specified with the
.B \-f
flag, 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. Similarly, if a local
cluster information file is specified with the
.B \-l
flag, that file is read and the cluster records in it are considered
higher priority than the Hesiod cluster records and fallback cluster
records.
.PP
.I 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,
.I getcluster
outputs variable definitions for each of the variables mentioned in
the remaining records.  For each variable,
.I 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/athena/clusterinfo
and
.I /var/athena/clusterinfo.bsh
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
Getcluster uses the Hesiod type "cluster".
.SH EXAMPLES
# C shell example
.br
getcluster `hostname` 5.3 > file; source file
.PP
# Bourne shell example
.br
getcluster -b `hostname` 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