Manual page for RDIST(1)
rdist - remote file distribution program
SYNOPSIS
rdist
[
-b
]
[
-h
]
[
-i
]
[
-n
]
[
-q
]
[
-R
]
[
-v
]
[
-w
]
[
-y
]
[
-d macro = value
]
[
-f distfile
]
[
-m host
] ... [
package
...
]
rdist
[
-b
]
[
-h
]
[
-i
]
[
-n
]
[
-q
]
[
-R
]
[
-v
]
[
-w
]
[
-y
]
-c
pathname ...
[login@]hostname[:destpath]
AVAILABILITY
This command is available with the
Networking
software installation option.
See
[a manual with the abbreviation INSTALL]
for information about installing optional software.
DESCRIPTION
rdist
maintains copies of files on multiple hosts.
It preserves the owner, group, mode, and modification time of the
master copies, and can update programs that are executing.
Normally, a copy on a remote host is updated if its size
or modification time differs from the original on the local host.
rdist
reads the indicated
distfile
for instructions on updating files and/or directories.
If
distfile
is
`-',
the standard input is used.
If no
-f
option is present,
rdist
first looks in its working directory for
distfile,
and then for
Distfile,
for instructions.
rdist
updates each
package
specified on the command line; if none are given, all packages
are updated according to their entries in the
distfile.
OPTIONS
- -b
-
Binary comparison.
Perform a binary comparison and update files if they differ,
rather than merely comparing dates and sizes.
- -h
-
Follow symbolic links.
Copy the file that the link points to rather than the link itself.
- -i
-
Ignore unresolved links.
rdist
will normally try to maintain the link structure of files being transffered
and warn the user if all the links cannot be found.
- -n
-
Print the commands without executing them.
This option is useful for debugging a distfile.
- -q
-
Quiet mode. Do not display the files being updated on the standard output.
- -R
-
Remove extraneous files.
If a directory is being updated, remove files on the remote host that do not
correspond to those in the master (local) directory.
This is useful for maintaining truly identical copies of directories.
- -v
-
Verify that the files are up to date on all the hosts.
Any files
that are out of date are displayed, but no files are updated, nor is
any mail sent.
- -w
-
Whole mode.
The whole file name is appended to the destination directory name.
Normally, only the last component of a name is used when renaming files.
This preserves the directory structure of the files being copied, instead
of flattening the directory structure.
For instance, renaming a list of files such as
( dir1/f1 dir2/f2 )
to
dir3
would create files
dir3/dir1/f1
and
dir3/dir2/f2
instead of
dir3/f1
and
dir3/f2.
When the
-w
option is used with a filename that begins with
~,
everything except the home directory is appended to the destination name.
- -y
-
Younger mode.
Do not update remote copies that are younger than the master copy, but
issue a warning message instead.
- -d macro=value
-
Define
macro
to have
value.
This option is used to define or override macro definitions in the distfile.
value
can be the empty string, one name, or a list of names surrounded by
parentheses and separated by white space.
- -c
pathname ...
[login@]hostname[:destpath]
-
Update each
pathname
on the named host. (Relative filenames are taken as relative to your
home directory.)
If the
`login@'
prefix is given, the update is performed with the user ID of
login.
If the
`:destpath'
is given, the remote file is installed as that pathname.
- -f distfile
-
Use the description file
distfile.
A
`-'
as the
distfile
argument denotes the standard input.
- -m host
-
Limit which machines are to be updated.
Multiple
-m
arguments can be given to limit updates to a subset of the hosts
listed in the distfile.
USAGE
Packages
A typical package begins with a label composed of the package
name followed by a colon:
package:
This label allows you to group any number of file-to-host and
file-to-timestamp mappings into a single distribution package.
If no package label appears in the distfile, the default package
includes all mappings in the file.
A file-to-host mapping specifies a list of files or directories
to distribute, their destination host(s), and any
rdist
primitives to use in performing the update. A mapping of this
sort takes the form:
( pathname ... )
->
( hostname ... )
primitive
;
[primitive
;]...
In this case, each
pathname
is the full pathname of a local file or directory to distribute; each
hostname
is the name of a remote host on which those files are to be copied,
and
primitive
is one of the
rdist
primitive listed under
Primitives,
below. If there is only one
pathname
or
hostname,
the surrounding parentheses can be omitted. A
hostname
can also take the form:
login@hostname
in which case the update is performed as the user named
login.
A file-to-timestamp mapping is used to monitor which local files are
updated with respect to a local ``timestamp'' file. This mapping
takes the form:
( filename ... )
::
timestamp-file
primitive
;
[primitive
;]...
In this case,
timestamp-file
is the name of a file, the modification time of which is compared with
each named file on the local host. If a file is newer than
time-stamp-file,
rdist
displays a message to that effect. If there is only one
filename,
the parentheses can be omitted.
White Space Characters
NEWLINE,
TAB,
and
SPACE
characters are all treated as white space; a mapping
continues across input lines until the start of the next mapping:
either a single
filename
followed by a
`->'
or the opening parenthesis of a filename list.
Comments
Comments begin with
#
and end with a
NEWLINE.
Macros
rdist
has a limited macro facility. Macros are only expanded in filename or
hostname lists, and in the argument lists of certain primitives. Macros
cannot be used to stand for primitives or their options, or the
`->'
or
`::'
symbols.
A macro definition is a line of the form:
macro = value
A macro reference is a string of the form:
${macro}
although (as with
make.1
the braces can be omitted if the macro name consists of just one
character.
Metacharacters
The shell meta-characters:
[,
],
{,
},
*
and
?
are recognized and expanded (on the local host only) just as
they are with
csh.1
Metacharacters can be escaped by prepending a backslash.
The
~
character is also expanded in the same way as with
csh,
however, it is expanded separately on the local and destination hosts.
Filenames
File names that do not begin with
/
or
~
are taken to be relative to user's home directory on each
destination host. Note that they are
not
relative to the current working directory.
Primitives
The following primitives can be used to specify actions
rdist
is to take when updating remote copies of each file.
- install
[
-b
]
[
-h
]
[
-i
]
[
-R
]
[
-v
]
[
-w
]
[
-y
]
[newname]
-
Copy out-of-date files and directories (recursively).
If no
install
primitive appears in the package entry, or if
no
newname
option is given, the name of the local file is given to the
remote host's copy.
If absent from the remote host, parent directories in a
filename's path are created.
To help prevent disasters, a non-empty directory on a target host is
not replaced with a regular file or a symbolic link by
rdist.
However, when using the
-R
option, a non-empty directory is removed if the corresponding filename
is completely absent on the master host.
The options for
install
have the same semantics as
their command line counterparts, but are limited
in scope to a particular map.
The login name used on the destination host is the same as the local host
unless the destination name is of the format
login@host.
In that case, the update is performed under the username
login.
- notify address ...
-
Send mail to the indicated
TCP/IP
address
of the form:
user@host
that lists the files updated and any errors that may have occurred.
If an address does not contain a
`@host'
suffix,
rdist
uses the name of the destination host to complete the address.
- except filename ...
-
Omit from updates the files named as arguments.
- except_patpattern ...
-
Omit from updates the filenames that match each regular-expression
pattern
(see
ed.1
for more information on regular expressions.
Note that
\
and
$
characters must be escaped in the distfile.
Shell variables can also be used within a pattern, however
shell filename expansion is not supported.
- special
[filename] ...
"command-line"
-
Specify a Bourne shell,
sh.1
command line to execute on the remote host after each named file is updated.
If no
filename
argument is present, the
command-line
is performed for every updated file, with the shell variable
FILE
set to the file's name on the local host. The quotation marks allow
command-line
to span input lines in the distfile; multiple shell commands must be
separated by semicolons
(;).
The default working directory for the shell executing each
command-line
is the user's home directory on the remote host.
EXAMPLES
The following sample distfile instructs
rdist
to maintain identical copies of a shared
library, a shared-library initialized data file, several
include files, and a directory, on hosts named
hermes
and
magus.
On
magus,
commands are executed as root.
rdist
notifies
merlin@druid
whenever it discovers that a local file has changed relative to
a timestamp file.
HOSTS = ( hermes root@magus )
FILES = ( /usr/local/lib/libcant.so.1.1
/usrlocal/lib/libcant.sa.1.1 /usr/local/include/{*.h}
/usr/local/bin )
${FILES} -> ${HOSTS}
install -R ;
${FILES} :: /usr/local/lib/timestamp
notify merlin@druid ;
FILES
- /tmp/rdist*
-
temporary file for update lists
SEE ALSO
csh.1
ed.1
sh.1
stat.2v
DIAGNOSTICS
A complaint about mismatch of
rdist
version numbers may really stem
from some problem with starting your shell,
for example, you are in too many groups.
BUGS
Source files must reside or be mounted on the local host.
There is no easy way to have a special command executed only once after
all files in a directory have been updated.
Variable expansion only works for name lists;
there should be a general macro facility.
rdist
aborts on files that have a negative modification time (before Jan 1, 1970).
There should be a ``force'' option to allow replacement of
non-empty directories by regular files or symlinks.
A means of updating file modes and owners
of otherwise identical files is also needed.
WARNINGS
root
does not have its accustomed access privileges on NFS mounted
file systems. Using
rdist
to copy to such a file system may fail, or the copies may be
owned by user ``nobody.''
Created by unroff & hp-tools.
© somebody (See intro for details). All Rights Reserved.
Last modified 11/5/97