DISTRIB(8)                                                          DISTRIB(8)



NAME
       distrib - distribute customized files to remote hosts

SYNOPSIS
       distrib  -c  -E  [-I  |  -a  |  -m machine | -t type] [-S] [-FMRbnqvxy]
       [-C config] [-D var=value] [-d var=value] [-G guard] [-k key] [-s  cmd]
       [hosts]
       distrib  -c  [-I  |  -a  |  -m  machine  |  -t  type] [-S] [-HMRbnqvxy]
       [-C config] [-D var=value] [-d var=value] [-G guard] [-k key] [-s  cmd]
       [hosts]
       distrib  -E  [-I  |  -a  |  -m  machine  |  -t type] [-S] [-f distfile]
       [-FMRbnqvxy] [-C config]  [-D  var=value]  [-d  var=value]  [-G  guard]
       [-k key] [hosts]
       distrib  [-I  |  -a  |  -m  machine  |  -t  type]  [-S]  [-f  distfile]
       [-HMRbnqvxy] [-C config]  [-D  var=value]  [-d  var=value]  [-G  guard]
       [-k key] [hosts]
       distrib -h
       distrib -V

DESCRIPTION
       Distrib  is  a front end for rdist(1).  It has largely been replaced by
       the msrc(8l) structure, which is much better in every respect.

       Distrib reads a configuration file that contains a list of  host  names
       and host types then runs rdist for a subset of those hosts.  Host types
       are specified in a configuration file, and are used to  group  machines
       of  similar  characteristics  (such as CPU type) together.  By default,
       distrib updates all hosts with the same type as the current host.

       For each host distrib updates it runs m4(1) over a  distfile  with  the
       following macros (possibly) predefined:

       HOST
              Column one is the name of the host that is being updated.

       SHORTHOST
              Column  two  is  the  abbreviated  host name of the host that is
              being updated.  This is generally used in m4 ifelse()  calls  to
              compare hostnames (when required).

       HOSTTYPE
              Column three is the type of host that is being updated.

       HOSTOS
              Column  four  is the numeric revision of the operating system on
              this host.  It is only numeric by (local) convention.

       HASSRC
              Mark platform support instances with something other than a  dot
              (.)   in  the fifth column of the configuration file.  Each sup-
              port  host  usually  has  another   configuration   file   which
              enumerates its slave instances.  Each also has a /usr/src direc-
              tory to receive the platform  update,  produce  compiled  binary
              files, then project them to the cluster of slave instances.

              The support configuration file may be derived from the enclosing
              file via efmd (or the like), otherwise it is usually a  separate
              file sent to the platform manager, or even managed autonomously.

       MYTYPE
              The type of the host that is running  distrib  is  provided  for
              comparison.

       MYOS
              The  os of the host that is running distrib is provided for com-
              parison.

       If any of these columns contain a period (.) the macro  is  left  unde-
       fined  (or  in the case of MYTYPE (MYOS) if the local machine is not in
       config).

       The configuration file may also contain comments given  by  starting  a
       line with the pounds (#) character.  Blank lines are ignored.

       The  current  host  should be in the configuration file so that distrib
       may find the default type of host to update.  However, by default  dis-
       trib does not attempt to update the local host (see -I), even though it
       appears in the configuration file.

       The default distfile is "Distfile" in the  current  working  directory.
       If that cannot be found, distrib uses "distfile" (see -f).

       If a source filename in the processed distfile is surrounded by commer-
       cial at signs (@) that file is processed by m4  with  the  same  macros
       defined as were defined for the distfile.  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
       @filename@ sequence in the distfile sent to rdist.

OPTIONS
       Distrib recognizes the following command line options (only one of  -a,
       -I, -m, or -t may be given, and -c and -f are mutually exclusive):

       -a
              Update all of the hosts in the configuration file.

       -c
              Use  a  command line distfile, very much like rdist'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".

       -C config
              Use config instead of the default configuration file.  If config
              cannot  be  found, and config is not an absolute path, then dis-
              trib will search for config in the directory /usr/local/lib/hxmd
              and /usr/local/lib/distrib.  If the config's name ends in ".mcf"
              then it is run though m4 with the hard compiled HOSTTYPE defined
              as MYTYPE and any -D options presented on the command line.  The
              specification of dash (-) reads stdin, and may not  be  used  in
              combination with -f with that same specification.

       -D var=value
              The  var  is defined as value for m4 during macro expansion.  If
              no value is given the empty string is used.

       -E
              As in cpp(1) just expand the distfile to stdout.

       -F
              Force @file@ replacement in distfile,  under  -E,  even  if  the
              given file doesn?t have the proper name.

       -f distfile
              An alternate distfile may be given with this option.  A dash (-)
              is taken as stdin, unless -C has the same specification.

       -G guard
              The m4 expression guard 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 con-
              taining  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.

              Incompatibility note  the guard in all other master source tools
              yields a hostname, distrib's was an incompatibe prototype.

       -H
              Provide a list of the hosts to update (only) on stdout.  This is
              shorthand for:

                        echo HOST | distrib -f - -E ....

              and  saves many processes.  The -E option is forbidden, since it
              is implied, any -f option is ignored.

       -h
              Print only a brief help message.

       -I
              Include myself.  The local  machine  will  be  included  in  the
              update.

       -k key
              Specifies a selection macro other than "HOST".  This is for for-
              ward compatibility with hxmd, and  is  not  fully  supported  by
              distrib.

       -m machine
              Update only a single machine from those listed in the configura-
              tion file.  This option is most useful after a machine has  been
              off-line for a while to 'catch up' on recent system upgrades.

       -s cmd
              Insert  a  special  command in the tiny distfile generated under
              -c.  Other commands like except_pat are not accessible from  the
              command line -- this might be a bug.

       -S
              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 any local site policy meaning).  This option will  work  as
              an "and" with -m or -t (below).

       -t type
              Update  hosts  only  of the given type.  The type given may be a
              comma separated list of types.  In this case distrib will update
              only the hosts of each listed type.

       -V
              Output  version  information  about  distrib.  This includes the
              default column headers and hard coded  platform  type  for  this
              platform.   Also  output  the  mktemp(3) template used to create
              temporary files.

       -x
              Be more verbose with an additional output of  approximate  shell
              commands on stderr.

       See  the rdist(1) man page for a detailed description of purpose of the
       following options, which are passed directly to rdist:

       -b
              Perform binary comparisons to see if files differ

       -d var=value
              Pass the given command line definition on to rdist.

       -M
              Use modes, groups and ownerships as criteria for deciding  if  a
              file or directory is out of date

       -n
              Print commands without actually executing them

       -q
              Quiet mode.

       -R
              Remove extraneous files.

       -n
              Do not really execute rdist.

       -v
              Verify that files are up to date on the remote hosts.

       -y
              Only update files that are younger than the master copy.

EXAMPLES
       distrib nostromo staff pop.stat element
              Send  the  files  given  in  the  local  distfile  to the listed
              machines.

       distrib -c /bin/ls HOST
              Send the binary for ls(1) to all hosts like this one.

       distrib -ac /etc/motd HOST
              Send the message of the day to all hosts.

       distrib -tSUN5 -G "eval(HOSTOS > 20501)" ...
              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.)

       distrib -Sc /usr/src/local/etc/distrib HOST
              Send the source for distrib to all the source machines.

       distrib -E lv426
              Examine the distfile that would be used to update lv426.

       distrib -ac @hostname@ HOST:/tmp/hostname
              Run m4 on the file "hostname" for each host in the configuration
              file,  install  it  as /tmp/hostname on that host.  The hostname
              file might contain something like
                        dnl  This is our local name after m4
                        HOST

       Here is a simple example configuration file:
            #
            # Sample Configuration File
            #

            # 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

       Given those hosts and this distfile:
            # $Id...
            # Sample Distfile
            #
            ( . ) -> ( HOST )
                      except_pat ( /RCS /Makefile /Distfile ifelse(HOSTTYPE, 'S81', '/vax-main.c') );
                      install ${INTO} ;

            ( @Make.host@ ) -> ( HOST )
                      install -b ${INTO}/Makefile ;
       Distrib 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 m4 before being sent as the remote
       file "Makefile".

       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
       distrib.

FILES
       /usr/local/lib/hxmd
              A shared configuration directory with hxmd.

       /usr/local/lib/distrib
              Our default configuration directory.

       /usr/local/lib/distrib/distrib.cf
              Distrib's default configuration file.

       /usr/local/lib/distrib/clients.cf
              The  common  name  for the configuration for clients of a HASSRC
              master.

       /usr/local/lib/distrib.defs
              Macro include file (antiquated).

       /usr/local/lib/local.defs
              The shell include file (via the .  command)  for  master  source
              builds.   This sets a known $PATH and possibly other environment
              varaibles.

       Distfile
              The default distfile.

       distfile
              An alternate name for distfile.

       /tmp/fdist*
              Created via mkdtemp(3) as a  cache  directory  of  m4  processed
              files.

BUGS
       The use of m4(1) shows questionable judgment.

       Distrib is now dependent upon  version 6 of rdist

       The multiple uses of the HASSRC macro are unclear to the novice user.

       Because  rdist  has  a  problem  if the machine given for the -m option
       doesn't string compare  exactly  with  the  destination  host,  distrib
       replaces  the  machine given on the command line with the value of HOST
       for that machine in the hopes that the distfile will use the HOST macro
       as the target machine, not SHORTHOST.

       Under  EPIX  hostname(1) returns only the first part of the full domain
       name for the host.  Distrib 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}.

       The  -s  hack under -c is very convenient, but a more general interface
       (like -o) might be better.

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

SEE ALSO
       cpp(1),  m4(1),  rdist(1),   sh(1),   hxmd(8l),   efmd(8l),   msrc(8l),
       msrcmux(7l)



                                     LOCAL                          DISTRIB(8)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXAMPLES | FILES | BUGS | AUTHORS | SEE ALSO