The first thing distrib does is select a set of machines. At least, that's what it thinks it's doing.
In reality, it selects some lines of a configuration file. That file, by convention called "distrib.cf", lists all the machines and their atttributes. But those entries needn't actually be machines. They're just lines in a file.
By default, distrib uses the distrib.cf in the current directory, or in the compiled-in default directory if there's not one there. That can be overridden by the -C option, which can be used to specify another file. It is not unusual (and is fantastically useful) to have many different configuration files for different tasks and situations.
A configuration file is a list of machines and their attributes. It consists of whitespace-separated columns (if you need whitespace in a value, put the column's value in double quotes). The items in the columns may be used to select machines and will be set to m4 macros for further processing.
The macro name used for each column can be specified by a line beginning with a '%'. There is a default set of columns compiled into distrib. It can be displayed with the -V option, and is "%HOST SHORTHOST HOSTTYPE HOSTOS HASSRC" in every binary I've seen. You can have more than one '%' line if you want to change the columns' meanings within a configuration file.
There's little magic about the names used- other than distrib relies on some of them to make its decisions. If you accidently misspell "HOSTTYPE" as "HOSTYPE", things might not work out for you.
If you want to add your own columns but are primarily using distrib as "a front end for rdist", we suggest you add them after the existing default columns. If you're doing something else, feel free to replace them. No sense carrying around columns you never use.
Lines beginning with '#" (comments, ideally) and empty lines are ignored. Beware of lines containing only whitespace!
Which lines ("machines") are selected? By default, lines that have a HOSTTYPE that matches MYTYPE but are not the current machine (the one that distrib is being run on as decided by HOST) are selected. MYTYPE is compiled into distrib when it's built and can be shown with the -V option. Setting MYTYPE from the distrib command line won't select different machines- use -t to do that. (But if you really want to do that, you can do it with -G.)
You needn't live with the default set of machines, though. The following options change the set:
| -a | all machines in the configuration (can't use with anything but -G, but it's redundant in those cases) |
| -G | specifies m4 code to select machines from the list distrib picks with the other options (wait for more info) |
| -I | also includes the machine we're on (only used by itself to augment the default set) |
| -m | specify one machine |
| -S | restrict to only machines that have HASSRC set (not just a dot) |
| -t | restrict to machines having specified HOSTTYPE(s) |
Hostnames specified with -m (or by themselves) refer to HOSTs in the configuration. They need not be real resolvable names. Short forms up to any '.' are allowed. Do not be fooled, SHORTHOST isn't used in these selections.
Notice that of the default columns, you can easily select on several of them:
| HOST | -m or by names |
| HOSTTYPE | -t |
| HASSRC | -S |
If you want to select on any other column (default or defined), you need to use -G and write some m4 code. We'll cover that later when we talk about m4.
Why select lines in a configuration file at all? Because once the lines are selected, they are used to set the macros specified for the columns. These can then be used for several purposes we'll describe in the following sections.