.\" $Id: distrib.man,v 5.18 2012/09/06 00:08:01 ksb Exp $
.\" $HTML: ${groff-groff} -tbl -man -Thtml %f
.\" $Compile: Display%h
.\" $Display: groff -tbl -Tascii -man %f | ${PAGER:-less}
.\" $Display(*): groff -tbl -T%s -man %f
.\" $Install: %b -mDeinstall %o %f && cp %f $DESTDIR/usr/local/man/man8/distrib.8
.\" $Deinstall: ${rm-rm} -f $DESTDIR/usr/local/man/[cm]a[nt]8/distrib.8*
.TH DISTRIB 8 LOCAL
.SH NAME
distrib - distribute customized files to remote hosts
.SH SYNOPSIS
.ds PN "distrib
.hlm 0
\fB\*(PN\fP \fB\-c\fP \fB\-E\fP [\fB\-I\fP | \fB\-a\fP | \fB\-m\fP\~\fImachine\fP | \fB\-t\fP\~\fItype\fP] [\fB\-S\fP] [\fB\-FMRbnqvxy\fP] [\fB\-C\fP\~\fIconfig\fP] [\fB\-D\fP\~\fIvar=value\fP] [\fB\-d\fP\~\fIvar=value\fP] [\fB\-G\fP\~\fIguard\fP] [\fB\-k\fP\~\fIkey\fP] [\fB\-s\fP\~\fIcmd\fP] [\fIhosts\fP]
.br
\fB\*(PN\fP \fB\-c\fP [\fB\-I\fP | \fB\-a\fP | \fB\-m\fP\~\fImachine\fP | \fB\-t\fP\~\fItype\fP] [\fB\-S\fP] [\fB\-HMRbnqvxy\fP] [\fB\-C\fP\~\fIconfig\fP] [\fB\-D\fP\~\fIvar=value\fP] [\fB\-d\fP\~\fIvar=value\fP] [\fB\-G\fP\~\fIguard\fP] [\fB\-k\fP\~\fIkey\fP] [\fB\-s\fP\~\fIcmd\fP] [\fIhosts\fP]
.br
\fB\*(PN\fP \fB\-E\fP [\fB\-I\fP | \fB\-a\fP | \fB\-m\fP\~\fImachine\fP | \fB\-t\fP\~\fItype\fP] [\fB\-S\fP] [\fB\-f\fP\~\fIdistfile\fP] [\fB\-FMRbnqvxy\fP] [\fB\-C\fP\~\fIconfig\fP] [\fB\-D\fP\~\fIvar=value\fP] [\fB\-d\fP\~\fIvar=value\fP] [\fB\-G\fP\~\fIguard\fP] [\fB\-k\fP\~\fIkey\fP] [\fIhosts\fP]
.br
\fB\*(PN\fP [\fB\-I\fP | \fB\-a\fP | \fB\-m\fP\~\fImachine\fP | \fB\-t\fP\~\fItype\fP] [\fB\-S\fP] [\fB\-f\fP\~\fIdistfile\fP] [\fB\-HMRbnqvxy\fP] [\fB\-C\fP\~\fIconfig\fP] [\fB\-D\fP\~\fIvar=value\fP] [\fB\-d\fP\~\fIvar=value\fP] [\fB\-G\fP\~\fIguard\fP] [\fB\-k\fP\~\fIkey\fP] [\fIhosts\fP]
.br
\fB\*(PN\fP \fB\-V\fP
.br
\fB\*(PN\fP \fB\-h\fP
.hlm -1
.SH DESCRIPTION
\fIDistrib\fP is a front end for \fBrdist\fP(1).
It has largely been replaced by
the \fBmsrc\fP(8l) structure, which is much better in every respect.
.P
\fIDistrib\fP
reads a configuration file that contains a list of host names and
host types then runs \fBrdist\fP for a subset of those hosts.  Host \fItypes\fP
are specified in a configuration file, and are used to group
machines of similar characteristics (such as CPU type) together.
By default, \fI\*(PN\fP updates all hosts with the same \fItype\fP
as the current host.
.PP
For each host \fI\*(PN\fP updates it runs \fBm4\fP(1) over a
\fIdistfile\fP with the
following macros (possibly) predefined:
.RS
.TP
.nf
\fBHOST\fP
.fi
Column one is the name of the host that is being updated.
.TP
.nf
\fBSHORTHOST\fP
.fi
Column two is the abbreviated host name of the host that is being updated.
This is generally used in \fBm4\fP \fBifelse\fP() calls to compare
hostnames (when required).
.TP
.nf
\fBHOSTTYPE\fP
.fi
Column three is the \fItype\fP of host that is being updated.
.TP
.nf
\fBHOSTOS\fP
.fi
Column four is the numeric revision of the operating system on this
host.  It is only numeric by (local) convention.
.TP
.nf
\fBHASSRC\fP
.fi
If this host has a /usr/src directory put something other than a dot (`.')
in the fifth column of the configuration file.
Such machines are the `platforms' that products are compiled on and send
from.
.TP
.nf
\fBMYTYPE\fP
.fi
The \fItype\fP of the host that is running \fI\*(PN\fP is provided for
comparison.
.TP
.nf
\fBMYOS\fP
.fi
The \fIos\fP of the host that is running \fI\*(PN\fP is provided for
comparison.
.RE
.sp
If any of these columns contain a period (\fB.\fP) the macro is left undefined
(or in the case of MYTYPE (MYOS) if the local machine is not
in \fIconfig\fP).
.PP
The configuration file may also contain comments given by starting a
line with the pounds (#) character.
Blank lines are ignored.
.PP
The current host should be in the configuration file so that \fI\*(PN\fP
may find the default type of host to update.
However, by default \fI\*(PN\fP does \fBnot\fP
attempt to update the local host,
even though it appears in the configuration file.
.PP
The default \fIdistfile\fP is ``\fIDistfile\fP'' in the current
working directory.
If that cannot be found, \fB\*(PN\fP uses ``\fIdistfile\fP'' (see \fB\-f\fP).
.PP
If a source filename in the processed \fIdistfile\fP is surrounded by
commercial at signs (@)
that file is processed by \fBm4\fP with the same macros defined
as were defined for the \fIdistfile\fP.
The resulting file is cached under a directory in /tmp,
such a file has the same modes as the source file.
The name of the cached file is substituted in place of
the \fB@\fP\fIfilename\fP\fB@\fP sequence in
the distfile sent to \fBrdist\fP.
.SH OPTIONS
\fIDistrib\fP recognizes the following command line options (only one of
\fB\-a\fP, \fB\-I\fP, \fB\-m\fP, or \fB\-t\fP may be given, and
\fB\-c\fP and \fP\-f\fP are mutually exclusive):
.TP
.nf
\fB\-a\fP
.fi
Update all of the hosts in the configuration file.
.TP
.nf
\fB\-c\fP
.fi
Use a command line distfile, very much like \fBrdist\fP's \-c option.
The command line distfile is still run through m4 for macro expansion.
If only one parameter is provided the destination machine is assumed to
be ``HOST''.
.TP
.nf
\fB\-C\fP \fIconfig\fP
.fi
Use \fIconfig\fP instead of the default configuration file.
If \fIconfig\fP
cannot be found, and \fIconfig\fP is not an absolute path,
then \fB\*(PN\fP will search for \fIconfig\fP in the directory
/usr/local/lib.
If the \fIconfig\fP's
name ends in ``.mcf'' then it is run though \fBm4\fP
with the hard compiled HOSTTYPE defined as "MYTYPE" and
any \fB\-D\fP options presented on the command line.
The specification of dash ("-") reads \fIstdin\fP, and may not be
used in combination with \fB\-f\fP with that same specification.
.TP
.nf
\fB\-D\fP \fIvar\fP=\fIvalue\fP
.fi
The \fIvar\fP is defined as \fIvalue\fP for \fBm4\fP during macro expansion.
If no \fIvalue\fP is given the empty string is used.
.TP
.nf
\fB\-E\fP
.fi
As in \fBcpp\fP(1) just expand the \fIdistfile\fP to \fIstdout\fP.
.TP
.nf
\fB\-F\fP
.fi
Force @file@ replacement in \fIdistfile\fP, under \fB\-E\fP, even if
the given file doesn\'t have the proper name.
.TP
.nf
\fB\-f\fP \fIdistfile\fP
.fi
An alternate \fIdistfile\fP may be given with this option.
A dash (\-) is taken as stdin, unless \fB\-C\fP has the same specification.
.TP
.nf
\fB\-G\fP \fIguard\fP
.fi
The m4 expression \fIguard\fP is evaluated (with the common macros
defined) to decide if each host should be included in the target list.
Only when the expression produces a non-empty string containing
any character other than white-space or the digit zero (0) is the host
included in the list.  This is intersected with the other host
limiting options.
.TP
.nf
\fB\-H\fP
.fi
Provide a list of the hosts to update (only) on stdout.  This
is shorthand for:
.sp 1
	echo HOST | \*(PN \-f \- \-E ....
.sp 1
and saves many processes.  The \fB\-E\fP option is forbidden,
since it is implied, any \fB\-f\fP option is ignored.
.TP
.nf
\fB\-h\fP
.fi
Provide a help message.
.TP
.nf
\fB\-I\fP
.fi
Include myself.  The local machine will be included in the
default update.
.TP
.nf
\fB\-k\fP \fIkey\fP
.fi
Specifies a selection macro other than "HOST".
This is for forward compatibility with \fBhxmd\fP, and is not
fully supported by .
.TP
.nf
\fB\-m\fP \fImachine\fP
.fi
Update only a single machine from those listed in the configuration file.
This option is most useful after a machine has been off-line for a while
to `catch up' on recent system upgrades.
.TP
.nf
\fB\-s\fP \fIcmd\fP
.fi
Insert a special command in the tiny distfile generated under \fB\-c\fP.
Other commands like \fBexcept_pat\fP are not accessible from the command
line \-\- this might be a bug.
.TP
.nf
\fB\-S\fP
.fi
Update only machines that have a HASSRC macro defined.
Use a ``.'' (dot) in the fifth column of a machine's
description to force this option to skip that machine
(any other string may have a meaning at the local site).
This option will work as an ``and''
with \fB\-m\fP or \fB\-t\fP (below).
.TP
.nf
\fB\-t\fP \fItype\fP
.fi
Update hosts only of the given \fItype\fP.
The \fItype\fP given may be a comma separated list of types.
In this case \fB\*(PN\fP will update only the hosts of each listed type.
.TP
.nf
\fB\-V\fP
.fi
Output version information about \fB\*(PN\fP.
This includes the default column headers and hard coded platform
type for this platform.  And the \fImktemp\fP(3) template used to
create temporary files.
.TP
.nf
\fB\-x\fP
.fi
Be more verbose with the output of approximate shell commands.
.PP
See the \fBrdist\fP(1) man page for a detailed description of purpose
of the following options, which are passed directly to \fBrdist\fP:
.TP
.nf
\fB\-b\fP
.fi
Perform binary comparisons to see if files differ
.TP
.nf
\fB\-d\fP \fIvar\fP=\fIvalue\fP
.fi
Pass the given command line definition on to \fBrdist\fP.
.TP
.nf
\fB\-M\fP
.fi
Use modes, groups and ownerships as criteria for deciding if a file or
directory is out of date
.TP
.nf
\fB\-n\fP
.fi
Print commands without actually executing them
.TP
.nf
\fB\-q\fP
.fi
Quiet mode.
.TP
.nf
\fB\-R\fP
.fi
Remove extraneous files.
.TP
.nf
\fB\-n\fP
.fi
Do not really execute \fBrdist\fP.
.TP
.nf
\fB\-v\fP
.fi
Verify that files are up to date on the remote hosts.
.TP
.nf
\fB\-y\fP
.fi
Only update files that are younger than the master copy.

.SH EXAMPLES
.TP
.nf
\*(PN nostromo staff pop.stat element
.fi
Send the files given in the local \fIdistfile\fP to the listed machines.
.TP
.nf
\*(PN \-c /bin/ls HOST
.fi
Send the binary for \fBls\fP to all hosts like this one.
.TP
.nf
\*(PN \-ac /etc/motd HOST
.fi
Send the message of the day to all hosts.
.TP
.nf
\*(PN \-tSUN5 \-G "eval(HOSTOS > 20501)" ...
.fi
Use a guard to limit distribution to hosts better than Solaris 2.5.1.
(Local convention is to use 2 digits for each portion of a dotted number.)
.TP
.nf
\*(PN \-Sc /usr/src/local/etc/distrib HOST
.fi
Send the source for \*(PN to all the source machines.
.TP
.nf
\*(PN \-E lv426
.fi
Examine the distfile that would be used to update \fIlv426\fP.
.\" Due to a bug in the .TP macro we can't use it with an @ in the top-line
.\"  so we make it look OK with raw nroff TNX to slt@softart.com
.PP
.nf
\*(PN \-ac @hostname@ HOST:/tmp/hostname
.fi
.in +5
Run \fBm4\fP on the file \*(lqhostname\*(rq for each host in the configuration
file, install it as \fI/tmp/hostname\fP on that host.
The hostname file might contain something like
.sp 1
.RS
	dnl  This is our local name after m4
.br
	HOST
.RE
.in -5
.PP
Here is a simple example configuration file:
.RS 5
.nf
#
# Sample Configuration File
#
.TS
l l l l l.
# Official	Short	CPU	OS	Has
# Hostname	Hostname	Type	Type	/usr/src
j.cc.purdue.edu	J	VAX780	403	yes
i.cc.purdue.edu	I	VAX780	403	.
mentor.cc.purdue.edu	MENTOR	S81	30012	yes
sage.cc.purdue.edu	SAGE	S81	30012	.
orphan.cc.purdue.edu	ORPHAN	.	.	kinda
.TE
.fi
.RE
.PP
Given those hosts and this Distfile:
.RS 5
.nf
#
# Sample Distfile
#
( . ) \-> ( HOST )
	except_pat ( /RCS /Makefile /Distfile ifelse(HOSTTYPE, `S81', `/vax-main.c') );
	install ${INTO} ;

( @Make.host@ ) \-> ( HOST )
	install \-b ${INTO}/Makefile ;
.fi
.RE
\fIDistrib\fP would send the current directory to ${INTO}, except for
``/vax-main.c'' which would not be sent to mentor, or sage.
The file ``Make.host'' will be filtered through \fBm4\fP before being
sent as the remote file ``Makefile''.
.PP
Note that the HOST value dot (".") is unlikely to occur (and should
be avoided); it is used as a sentinel value in some commands which
call \fI\*(PN\fP.

.SH FILES
.TS
l l.
/usr/local/lib/distrib/distrib.cf	default configuration file
/usr/local/lib/distrib/clients.cf	usually a configuration for local clients
/usr/local/lib/distrib.defs	macro include file (antiquated)
/usr/local/lib/local.defs	shell include file for master source builds
Distfile	default distfile
distfile	alternate name for Distfile
/tmp/fdist$$	directory for cache of \fBm4\fP processed files
.TE
.SH BUGS
.PP
The use of \fBm4\fP(1) shows questionable judgment.
.PP
Distrib is now dependent upon the new version of rdist (version 6).
.PP
The multiple uses of the HASSRC macro are unclear to the novice user.
.PP
\fIRdist\fP has a problem if the \fImachine\fP given for the \fB\-m\fP
option doesn't string compare exactly with the destination host (it
doesn't send any files).
\fIDistrib\fP replaces the \fImachine\fP given on the command line
with the value of HOST for that machine in the hopes that the \fIdistfile\fP
will use the HOST macro as the target machine, not SHORTHOST.
.PP
Under EPIX \fBhostname\fP(1) returns only the first part of the full
domain name for the host.  \fIDistrib\fP tries to make rdist do the
correct thing anyway (with little success).  To make \-m's to the current
host work, on such machines the HOST macro is the same string as the
SHORTHOST macro (for the local machine only) {what a kludge}.
.PP
The \fB\-s\fP hack under \fB\-c\fP is very convenient, but
a more general interface (like \fB\-o\fP) might be better.

.SH AUTHORS
Kevin S. Braunsdorf   Purdue University Computing Center  distrib swirl ksb.npcguild.org
.br
Michael J. Spitzer  Purdue University Computing Center
.br

.SH "SEE ALSO"
.hlm 0
cpp(1), m4(1), rdist(1), sh(1), hxmd(8l), efmd(8l), msrc(8l)