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

Revision 25438, 5.3 KB checked in by kaduk, 13 years ago (diff)
In getcluster: * Update date for getcluster.1 to reflect reality
Line 
1.TH GETCLUSTER 1 "11 August 2011"
2.SH NAME
3getcluster \- retrieve service cluster info from Hesiod as environment vars
4.SH SYNOPSIS
5.B getcluster
6[
7.B \-b
8] [
9.B \-d
10] [
11.B -h
12.I hostname
13] version
14.PP
15.SH DESCRIPTION
16.B getcluster
17queries the Hesiod database for service cluster information associated
18with the workstation on which it is run.  It writes a set of environment
19variable assignments on its standard output in a format acceptable
20to the C shell, or, if the
21.B \-b
22flag is present, in Bourne shell syntax.
23.B getcluster
24returns an exit status of 2 if no cluster information is available, or
251 if any other error was encountered.
26.PP
27A cluster record contains between two and four fields: a
28variable name, a value, an optional version number, and an optional
29list of flags.  The version number is a dotted pair giving the major
30and minor numbers of the Athena release to which the variable
31definition applies.  Currently, the only defined flag is 't',
32indicating that the Athena release specified by the version is in
33testing.
34.PP
35By default,
36.B getcluster
37looks up cluster information for the current hostname.  This name may
38be overridden by the contents of the file
39.B /etc/cluster
40or via the command line using the
41.B \-h
42option.  A cluster name such as
43.B public-linux
44may be given in place of a hostname.
45.PP
46If
47.B /etc/cluster.fallback
48is present, that file is read and the cluster records in it are
49considered lower priority than the Hesiod cluster records.  For each
50variable name in the Hesiod cluster record, no record with the same
51variable name in the fallback file will be considered.  If
52.B /etc/cluster.local
53is present, that file is read and the cluster records in it are
54considered higher priority than the Hesiod cluster records and
55fallback cluster records.
56.PP
57.B getcluster
58may discard a cluster record if it specifies a version which is
59higher than the current workstation version (as given by the
60.I version
61argument on the command line).  A record with a new version is
62rejected if any of the following are true:
63.TP 3
641.
65The environment variable
66.B AUTOUPDATE
67is not defined or has a value other than "true".
68.TP 3
692.
70The record specifies the 't' flag.
71.TP 3
723.
73The environment variable
74.B UPDATE_TIME
75is not defined or specifies a Unix time value greater than the current
76time.
77.PP
78After discarding records for the above reasons,
79.B getcluster
80outputs variable definitions for each of the variables mentioned in
81the remaining records.  For each variable,
82.B getcluster
83selects the value given in the record with the highest version number,
84or uses a record with no version number if no records with version
85numbers are present.
86.PP
87.I getcluster
88may also output three special variable definitions:
89.IP NEW_TESTING_RELEASE
90If any records were discarded because they contained the 't' flag and
91specified versions greater than the current workstation version,
92.B NEW_TESTING_RELEASE
93is set to the highest version number given in those records.
94.IP NEW_PRODUCTION_RELEASE
95If any records were discarded because they specified versions greater
96than the current workstation version and the
97.B AUTOUPDATE
98environment variable was not "true,"
99.B NEW_PRODUCTION_RELEASE
100is set to the highest version number given in those records.
101.IP UPDATE_TIME
102If any records specified higher version numbers than the current
103workstation version and were not discarded for the first two reasons,
104.B UPDATE_TIME
105is set to a time at which the workstation should accept the new
106values.  The value is taken from the current value in the environment
107if it is present; otherwise a random Unix time value between the
108current time and four hours in the future is chosen.  The random
109number generator is seeded with the IP address given in the
110.B ADDR
111environment variable, or with a fixed value if none is specified.
112.PP
113If the
114.B \-d
115flag is present,
116.I getcluster
117will ignore the hostname argument and instead read lines from standard
118input, treating each line as if it were an entry in the Hesiod
119database for the host's cluster information.
120.PP
121.I getcluster
122is usually invoked from
123.I save_cluster_info (8),
124which places its output in the files
125.I /var/run/athena-clusterinfo.csh
126and
127.I /var/run/athena-clusterinfo.sh
128to be accessed by the C shell in a user's .login file and the Bourne
129shell in a user's .profile, respectively.  It may also be invoked
130directly by any user.
131.PP
132.B getcluster
133uses the Hesiod type
134.BR cluster .
135.SH DEPRECATED SYNTAX
136For compatibility with older versions of
137.BR getcluster ,
138a command-line argument may be given before the version number.  (This
139is how the hostname used to be specified; now it is ignored.)  The
140name of the fallback and local cluster files may be controlled using
141the
142.B \-f
143and
144.B \-l
145options, but there is no good reason to do so.
146.SH EXAMPLES
147# C shell example
148.br
149getcluster 5.3 > file; source file
150.PP
151# Bourne shell example
152.br
153getcluster -b 5.3 > file; . file
154.SH "SEE ALSO"
155`Hesiod - Project Athena Technical Plan -- Name Service', save_cluster_info(8)
156.SH AUTHOR
157Steve Dyer, IBM/Project Athena
158.br
159Greg Hudson, MIT Information Systems
160.br
161Copyright 1987, 1997, Massachusetts Institute of Technology
162.br
163.SH BUGS
164If there exist two unversioned tags of the same name, getcluster will
165pick whichever one comes last (either in Hesiod output or in a local
166file).  This can be regarded as a feature instead of a bug.
Note: See TracBrowser for help on using the repository browser.