packages icon



 CODA(1)                                                             CODA(1)
                                    LOCAL



 NAME
      coda - Code distribution aid

 SYNOPSIS
      coda [ -c ] [ -ddir ] [ -rdir ] [ -hhost ] [ -pport# ] [ -ffile ] [
           -uname ] [ -xpass ] [ -sy_or_n ] [ -yy_or_n ] [ -oy_or_n ] [ -n ]
           [ -t ] [ -v # ] [ names... ]

 DESCRIPTION
      Coda is used to keep source distributions  current  across  a  set  of
      machines.   It is not as flexible as rdist(1), but it requires less of
      the client machines because they do not have to be running Unix or the
      Berkeley networking programs.  The other difference is that when using
      rdist, the server ``pushes'' files out to the clients, while with coda
      the  clients  ``pull''  files from the server as they need them.  Coda
      was designed to have a simple client  that  easily  ports  to  a  wide
      variety of systems.

      The most common way of using coda is to create a configuration file in
      your home directory.  On UNIX systems, the file is named $HOME/.codarc
      while on VMS machines  it  is  named  SYS$LOGIN:CODA.DAT.   On  either
      system,  to use a different file, set the environment variable CODA to
      the name of the file.  This is useful to share a common a  file  among
      project members.  The config file identifies where the server host is,
      your name (and password) on the server, and  where  the  Codafile  and
      sources are to be found.

      The config file is a set of lines that make name-value  pairs.   Lines
      starting  with  a  pound  sign are ignored.  The following is a sample
      configuration file; the field names are explained below:
           ##  Server host and port number
           host      papaya.bbn.com
           port      1999
           ##  Our name and password on the server host
           user      rsalz
           pass      doubtful
           ##  Directory to start from, name of the file to read
           dir       /usr/cronus
           file      src/make_all/Codafile
           ##
           #root     /nfs/papaya/u1/cronusbuild/cronus
           slow      n
           verbose   1
           ##  Can client have newer files?  Yes, while porting to it
           younger   y

      In addition to using the config file, it is possible  to  specify  the
      parameters  by  using  command  line  flags.   Any values set by flags
      override the values in the config file.  The following tables  matches
      names in the config file to command line flags.
           File     Flag    Meaning



                                    - 1 -         Formatted:  March 28, 2024






 CODA(1)                                                             CODA(1)
                                    LOCAL



           __________________________________________________
           host     -h      Name of the server host
           port     -p      Port to connect to; default is 1999
           user     -u      Your login name on the server
           pass     -p      Your password on the server; see below
           dir      -d      Directory for server to change to
           file     -f      File to read (if not Codafile) in the directory given above
                    -n      No action, just report what would be changed
           root     -r      Path to find files in; overrides what the Codafile declared
           slow     -s      Do byte-for-byte comparisons
                    -t      Trace the protocol
           verbose  -v      How much information to show
           younger  -y      Allow newer files to be on the client
           owner    -o      Retain original ownership

      If your password is not listed in the config file, or specified on the
      command  line,  coda will ask you for it.  If you do put your password
      in the config file, make sure that nobody else can read the file!

      Once the file has been read, the server will send over a list of files
      and  directories.  Coda will parse this list, and update any files and
      directories it has to.

      For efficiency, coda normally just checks the sizes of the  local  and
      master  copy,  and  will  only  update  the  local  copy  if  they are
      different.  If the modification dates are different, coda will  get  a
      copy of the file and do a byte-for-byte comparison to see if the files
      actually are different.  If the ``-s'' flag is used, coda will  ignore
      the  time check, and will get every file and compare it with the local
      copy.

      If you use the ``-n'' flag, coda will not do work,  but  will  instead
      just report what files and directories are out of date.

      During a port, a client will often have files that have been  modified
      after  they have been obtained from the server, but before the changes
      have been integrated into the master sources.  On  systems  where  the
      client's  timestamp  can be trusted (e.g., not on VMS because there is
      no equivalent of the utime(2) call), the ``-y'' flag may  be  used  to
      specify  that  the  client  might have files that are younger, or more
      recent, than those on the server.  The default  option,  ``-yn''  will
      cause coda to check if the files are different, and overwrite them, if
      the timestamps are different in any way.

      By default the person who runs coda will be the owner  of  the  files.
      To  make  the  ownerships  match  those on the server, use the ``-oy''
      flag.  This is probably more correct in a production environment  than
      when porting.

      If you use the ``-v'' flag, coda will give  more  verbose  information
      about  what it is doing.  For example, ``-v1'' will list all files and



                                    - 2 -         Formatted:  March 28, 2024






 CODA(1)                                                             CODA(1)
                                    LOCAL



      directories that have to be created.  If you  use  the  ``-v2''  flag,
      coda  will report when it has to change the ownership or permission on
      files, such as when a file has the right time and size, but  is  owned
      by  the  wrong  person.  Since it is normally not a big problem if the
      wrong person owns a file, or if it has  the  wrong  permissions,  coda
      does  not  complain  if  something  cannot  be fixed.  You can use the
      ``-v3'' flag to see a message whenever the program cannot set the file
      mode  or  ownership.   If you use the ``-v4'' flag coda will report on
      every file as it does the byte-for-byte comparison of slow mode.   You
      should probably always use either ``-v1'' or ``-v3.''

      To trace all interactions with the server, use the ``-t''  flag;  this
      will provide output like the following:
           prompt% coda -d/usr/rsalz -f coda/Codafile -h papaya -u rsalz -x ... -t misc
           <<<ACK-Hello FIG.BBN.COM; how are you today?
           >>>USER rsalz ...
           <<<ACK-Logged in rsalz
           >>>GOTO /usr/rsalz
           <<<ACK-Done
           >>>READ coda/Codafile
           <<<ACK-Done
           Doing misc...
           >>>LIST misc
           <<<DAT ITEM W=d N=cbin U=-2 G=121 M=511 S=512 T=609796129
           <<<DAT ITEM W=f N=cbin/dcc U=-2 G=121 M=493 S=150 T=603474106
                    ...
           <<<ACK-Found 105 files
           Found 105 files
           mkdir cbin
           Update cbin/dcc
                    ...
           >>>QUIT
           prompt%
      (Lines without the angle brackets are the coda's normal output.)  This
      is  detailed  information  and  generally  nobody  but your local coda
      maintainer will care.

      The ``-c'' flag prints out copyright and version information.

 CODAFILES
      The coda server reads a file to determine what parts of a distribution
      get  sent  to which hosts.  The file is normally named Codafile.  This
      section explains how to write codafiles, and does not have to be  read
      by everyone.

      Blank  lines  are  ignored,  as  is  anything  after  a  pound   sign.
      Whitespace  is  not  significant.   There are a few keywords, and they
      appear in bold in the examples below.  To use a keyword as a  filename
      (e.g.,  if you have a directory named class), put it in quotes.  It is
      also necessary to quote words if they  contain  any  characters  other
      than letters, numbers, or the characters period, slash, or underscore.



                                    - 3 -         Formatted:  March 28, 2024






 CODA(1)                                                             CODA(1)
                                    LOCAL



      There are four constructs in a Codafile:  parameter definitions,  host
      definitions,  class definitions, and file definitions or blocks.  They
      may appear in any order.

      Parameter definitions are a catch-all  for  miscellaneous  parameters.
      There  are  currently  three parameters.  Most pathnames in a Codafile
      will be relative paths, the ``root'' is used for  any  directories  or
      files that do not start with a slash.  For example:
           define root = /usr/cronus ;
      This is most useful when the Codafile for a system is not at  the  top
      of the directory tree, or when it exists in someone's home directory.

      At times it is useful to use the same Codafile for  several  different
      source  trees.  The easiest way to do this is to not allow the clients
      to specify the different roots.  Since this can be a security hole,  a
      Codafile can specify that the root directory specified in the file may
      not be overridden by the client.  To do this, use the following line:
           define rooted = yes ;
      The value can be any word starting with the  letter  y.   The  default
      value is no

      The final parameter controls whether or not  binary  files  are  sent.
      When  preparing  a  list  of  files, the server can read the first few
      bytes to see if a file is an ``a.out'' file, and if so,  it  will  not
      list it.  To suppress this check, add a line like this:
           define binaries = yes ;
      The value can be any word starting with the  letter  y.   The  default
      value is yes

      Host definitions are used to  name  the  hosts  that  are  allowed  to
      receive  the  distribution, and to identify the system type.  Both the
      names and types are arbitrary text strings; host names  are  converted
      to all uppercase.  A client's hostname must be defined in the Codafile
      before the server will send any files to it.
           host  citron.bbn.com     = VMS ;
           host  pineapple.bbn.com  = ultrix ;
           host  doe.bbn.com        = sun4 ;
           host  papaya.bbn.com     = sun3 ;
      If for some reason the server cannot determine the client's host name,
      then the name _ANYHOST is used.

      In order to make the Codafile shorter, hosts are grouped into classes.
      For  example,  it  is convenient to be able to say ``give all the Unix
      machines the files in foo.'' Classes are defined in two ways, by being
      named  as  a  system  type  in  a  host  definition, like above, or by
      appearing in a class definition, like this:
           class     SUN  = sun3, sun4 ;
           class     UNIX = SUN, ultrix ;
      Note that classes can be nested and can  contain  other  classes.   In
      particular,  it  is possible to make loops that will tie the server up
      in knots.  Unlike host names, case is significant in class names.   By



                                    - 4 -         Formatted:  March 28, 2024






 CODA(1)                                                             CODA(1)
                                    LOCAL



      convention,  classes  defined  as  host  types are in lowercase, while
      those defined as class types are in uppercase.  The  special  built-in
      class  _ALL  contains  all  hosts  except  _ANYHOST.  A Codafile for a
      public archive might start off like this:
           define  root       = /usr/spool/ftp ;
           define  binaries   = no ;
           host    _ANYHOST   = guest ;
           class   WORLD      = _ALL, _ANYHOST ;

      The most important part of a Codafile  is  the  file  definitions,  or
      blocks.   These have the following syntax (optional items are shown in
      square brackets):
           [ only_explicitly ] name : class {
                item
                     [ except [directory] class pattern, ... ; ]
                     [ except [directory] class pattern, ... ; ]
                item
                     ...
                directory item
                     [ except [directory] class pattern, ... ; ]
           }
      The name is used by client programs to limit the  set  of  files  they
      want to receive, while the class is used by the server to determine if
      the client has any access to the block at all.  If a client  does  not
      name  specific blocks, then all blocks in the file are examined.  If a
      block starts  with  the  only_explicitly  keyword,  than  it  must  be
      explicitly  named  by the client, otherwise it is not listed.  This is
      useful, for example, when the default  is  to  distribute  a  complete
      system without test data.

      Within the block, each item names either a file or  a  directory.   If
      the  item does not start with a slash, then the root is prepended.  If
      the item is a directory, than the server will walk down all the  files
      and directories beneath the named item.  To name just a directory, put
      the word directory before the item name.  For example:
           headers : _ALL {
                include
                directory cetc
                cetc/hostfile
                cetc/typefile
                /etc/motd
           }
      This specifies that all hosts get the directory named include and  all
      files  and  directories  within it.  The next three lines specify that
      all clients should have the cetc directory and the two files  hostfile
      and  typefile  within  it.   The actual location of these files on the
      server depends on the value of the root parameter.  Their location  on
      the  client is relative to the directory from which the coda was first
      invoked.  The last line specifies that the motd file should exist with
      the  indicated  full  pathname,  regardless  of  the value of the root
      parameter, or where the client is being run from.



                                    - 5 -         Formatted:  March 28, 2024






 CODA(1)                                                             CODA(1)
                                    LOCAL



      Items can be given exception  lists.   Exception  lists  are  patterns
      similar to shell wildcards:
           Character  Meaning
           ?          Any single character
           *          Zero or more characters
           [abc..09]  Any single character inside the brackets
                      The sequence ``a-z'' can be used to mean ``abcdefghijklmnopqrstuvwxyz''
           [^a-z]     Any single character not inside the brackets.
           \x         The character ``x'' has no special meaning (e.g., \?)
      Exception patterns only match against the last part of  the  pathname.
      That  is,  mgr.c and not /usr/cronus/src/lib/asynclib/mgr.a.  To match
      against the whole pathname, precede the pattern with an uparrow.  This
      can  be  necessary when you want to exclude a particular file that has
      the same part of name as a directory further up in the source tree.

      For example, with the following hierarchy:
           clib/commandfile
           clib/cronus.a
           clib/diamond/fonts/helvetica10.font
           clib/diamond/fonts/tv8b.font
           clib/diamond/lib.a
           clib/diamond/config
           clib/editkeysfile
           clib/lint/llib-lasync
           clib/lint/llib-lasync.ln
           clib/lint/llib-lulib
           clib/lint/llib-lulib.ln
           clib/malloctool.a
      And the following block definition:
           library : _ALL {
               clib
                      except _ALL "*.a", "*.ln" ;
                      except directory VMS diamond, lint ;
           }
      Then, no clients will get the compiled libraries or lint(1) libraries,
      and  VMS  clients  will  not  get  any  files  in  the lint or diamond
      directories.  All clients will get the (presumably text)  files  named
      commandfile, and editkeysfile.

      With a good set of  classes  it  is  quite  easy  to  tersely  specify
      distributions.  The following example suffices to distribute the major
      part of the Cronus source tree:
           sources : _ALL {
                      src
                      exceptVMSMakefile, "*.sh", "*.s", "llib-l*" ;
                      exceptUNIXdescrip.mms,  "*.opt", "*.com", "*.mar" ;
                      except_ALL"*.[oa]", "*.ln" ;
                      except_ALLa.out, core, foo, tags ;
           }





                                    - 6 -         Formatted:  March 28, 2024






 CODA(1)                                                             CODA(1)
                                    LOCAL



 AUTHOR
      This program was written by Rich $alz  <rsalz@bbn.com>.   It  has  the
      following copyright:
           Copyright 1989 BBN Systems and Technologies Corporation.
           All Rights Reserved.
           This is free software, and may be distributed under the terms of the
           GNU Public License; see the file COPYING for more details.

           $Header: coda.1,v 2.0 90/03/23 15:01:50 rsalz Exp $

 SEE ALSO
      codaserver(8).










































                                    - 7 -         Formatted:  March 28, 2024