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