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

Revision 25648, 5.7 KB checked in by jdreed, 12 years ago (diff)
In getcluster: * Add a "-p" flag to print out space-separated key/value pairs for things to parse by hand * Update man page for new option
[25648]1.TH GETCLUSTER 1 "20 July 2012" "debathena-clusterinfo" "Hesiod Cluster Information"
[12159]2.SH NAME
[25648]3getcluster \- retrieve service cluster info from Hesiod
[12159]4.SH SYNOPSIS
5.B getcluster
[25648]7.B \-b |
8.B \-p
[12159]9] [
10.B \-d
11] [
[19233]12.B -h
13.I hostname
14] version
[19233]17.B getcluster
[12159]18queries the Hesiod database for service cluster information associated
19with the workstation on which it is run.  It writes a set of environment
20variable assignments on its standard output in a format acceptable
21to the C shell, or, if the
22.B \-b
23flag is present, in Bourne shell syntax.
[25648]24If the
25.B \-p
26flag is present, the results are written in space-separated key-value
27pairs, suitable for parsing by things that are not shells. 
28.B \-p
30.B \-b
31are mutually exclusive.
[19233]32.B getcluster
[12159]33returns an exit status of 2 if no cluster information is available, or
341 if any other error was encountered.
36A cluster record contains between two and four fields: a
37variable name, a value, an optional version number, and an optional
38list of flags.  The version number is a dotted pair giving the major
39and minor numbers of the Athena release to which the variable
40definition applies.  Currently, the only defined flag is 't',
41indicating that the Athena release specified by the version is in
[19233]44By default,
45.B getcluster
46looks up cluster information for the current hostname.  This name may
47be overridden by the contents of the file
[25378]48.B /etc/cluster
[19233]49or via the command line using the
50.B \-h
51option.  A cluster name such as
52.B public-linux
53may be given in place of a hostname.
[25378]56.B /etc/cluster.fallback
[19233]57is present, that file is read and the cluster records in it are
58considered lower priority than the Hesiod cluster records.  For each
59variable name in the Hesiod cluster record, no record with the same
60variable name in the fallback file will be considered.  If
[25378]61.B /etc/cluster.local
[19233]62is present, that file is read and the cluster records in it are
63considered higher priority than the Hesiod cluster records and
64fallback cluster records.
66.B getcluster
[12159]67may discard a cluster record if it specifies a version which is
68higher than the current workstation version (as given by the
69.I version
70argument on the command line).  A record with a new version is
71rejected if any of the following are true:
72.TP 3
74The environment variable
76is not defined or has a value other than "true".
77.TP 3
79The record specifies the 't' flag.
80.TP 3
82The environment variable
84is not defined or specifies a Unix time value greater than the current
87After discarding records for the above reasons,
[19233]88.B getcluster
[12159]89outputs variable definitions for each of the variables mentioned in
90the remaining records.  For each variable,
[19233]91.B getcluster
[12159]92selects the value given in the record with the highest version number,
93or uses a record with no version number if no records with version
94numbers are present.
[19233]96.I getcluster
[12159]97may also output three special variable definitions:
99If any records were discarded because they contained the 't' flag and
100specified versions greater than the current workstation version,
102is set to the highest version number given in those records.
104If any records were discarded because they specified versions greater
105than the current workstation version and the
107environment variable was not "true,"
109is set to the highest version number given in those records.
111If any records specified higher version numbers than the current
112workstation version and were not discarded for the first two reasons,
114is set to a time at which the workstation should accept the new
115values.  The value is taken from the current value in the environment
116if it is present; otherwise a random Unix time value between the
117current time and four hours in the future is chosen.  The random
118number generator is seeded with the IP address given in the
119.B ADDR
120environment variable, or with a fixed value if none is specified.
122If the
123.B \-d
124flag is present,
125.I getcluster
126will ignore the hostname argument and instead read lines from standard
127input, treating each line as if it were an entry in the Hesiod
128database for the host's cluster information.
[19233]130.I getcluster
[12159]131is usually invoked from
132.I save_cluster_info (8),
133which places its output in the files
[25378]134.I /var/run/athena-clusterinfo.csh
[25378]136.I /var/run/
[12159]137to be accessed by the C shell in a user's .login file and the Bourne
138shell in a user's .profile, respectively.  It may also be invoked
139directly by any user.
[19233]141.B getcluster
142uses the Hesiod type
143.BR cluster .
145For compatibility with older versions of
146.BR getcluster ,
147a command-line argument may be given before the version number.  (This
148is how the hostname used to be specified; now it is ignored.)  The
149name of the fallback and local cluster files may be controlled using
151.B \-f
153.B \-l
154options, but there is no good reason to do so.
[12159]155.SH EXAMPLES
156# C shell example
[19233]158getcluster 5.3 > file; source file
160# Bourne shell example
[19233]162getcluster -b 5.3 > file; . file
[12159]163.SH "SEE ALSO"
164`Hesiod - Project Athena Technical Plan -- Name Service', save_cluster_info(8)
166Steve Dyer, IBM/Project Athena
168Greg Hudson, MIT Information Systems
170Copyright 1987, 1997, Massachusetts Institute of Technology
[25378]173If there exist two unversioned tags of the same name, getcluster will
174pick whichever one comes last (either in Hesiod output or in a local
175file).  This can be regarded as a feature instead of a bug.
177.B getcluster
178does not quote its shell output, nor does it do any checking
179of key names.  This means that if you have a key named "path" or have a
180value with the content of ";rm -rf *", you probably shouldn't eval or
181source its output.
Note: See TracBrowser for help on using the repository browser.