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