.TH GETCLUSTER 1 "20 July 2012" "debathena-clusterinfo" "Hesiod Cluster Information" .SH NAME getcluster \- retrieve service cluster info from Hesiod .SH SYNOPSIS .B getcluster [ .B \-b | .B \-p ] [ .B \-d ] [ .B -h .I hostname ] version .PP .SH DESCRIPTION .B 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. If the .B \-p flag is present, the results are written in space-separated key-value pairs, suitable for parsing by things that are not shells. .B \-p and .B \-b are mutually exclusive. .B 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 By default, .B getcluster looks up cluster information for the current hostname. This name may be overridden by the contents of the file .B /etc/cluster or via the command line using the .B \-h option. A cluster name such as .B public-linux may be given in place of a hostname. .PP If .B /etc/cluster.fallback is present, 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. If .B /etc/cluster.local is present, that file is read and the cluster records in it are considered higher priority than the Hesiod cluster records and fallback cluster records. .PP .B 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, .B getcluster outputs variable definitions for each of the variables mentioned in the remaining records. For each variable, .B 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/run/athena-clusterinfo.csh and .I /var/run/athena-clusterinfo.sh 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 .B getcluster uses the Hesiod type .BR cluster . .SH DEPRECATED SYNTAX For compatibility with older versions of .BR getcluster , a command-line argument may be given before the version number. (This is how the hostname used to be specified; now it is ignored.) The name of the fallback and local cluster files may be controlled using the .B \-f and .B \-l options, but there is no good reason to do so. .SH EXAMPLES # C shell example .br getcluster 5.3 > file; source file .PP # Bourne shell example .br getcluster -b 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 If there exist two unversioned tags of the same name, getcluster will pick whichever one comes last (either in Hesiod output or in a local file). This can be regarded as a feature instead of a bug. .B getcluster does not quote its shell output, nor does it do any checking of key names. This means that if you have a key named "path" or have a value with the content of ";rm -rf *", you probably shouldn't eval or source its output.