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: November 14, 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: November 14, 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: November 14, 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: November 14, 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: November 14, 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: November 14, 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: November 14, 2024
