RDIST(1) | General Commands Manual | RDIST(1) |
rdist
— remote
file distribution client program
rdist |
[-DFnV ]
[-A num]
[-a num]
[-c mini_distfile]
[-d var=value]
[-f distfile]
[-L remote_logopts]
[-l local_logopts]
[-M maxproc]
[-m host]
[-o distopts]
[-P rsh-path]
[-p rdistd-path]
[-t timeout]
[name ...] |
rdist
is a program to maintain identical
copies of files over multiple hosts. It preserves the owner, group, mode,
and mtime of files if possible and can update programs that are
executing.
rdist
reads commands from
distfile to direct the updating of files and/or
directories. If distfile is ‘-’, the
standard input is used. If no -f
option is present,
the program looks first for distfile, then
Distfile, to use as the input. If no names are
specified on the command line, rdist
will update all
of the files and directories listed in distfile. If
the file /etc/Distfile exists, it will be run
automatically by the clock daemon
cron(8), via the system script
daily(8).
If name is specified, it is taken to be the name of a file to be updated or the label of a command to execute. If label and file names conflict, it is assumed to be a label. These may be used together to update specific files using specific commands.
rdist
uses a remote shell command to
access each target host. By default,
ssh(1) is used unless overridden
by the -P
option or the RSH
environment variable. If the target host is the string
“localhost” and the remote user name is the same as the local
user name, rdist
will run the command:
/bin/sh -c rdistd -S
Otherwise, rdist
will run the command:
ssh <host> -l <login_name> rdistd -S
host is the name of the target host; login_name is the name of the user to make the connection as.
On each target host rdist
will attempt to
run the command:
rdistd -S
Or if the -p
option was specified,
rdist
will attempt to run the command:
<rdistd path> -S
If no -p
option is specified, or
⟨rdistd path⟩ is a simple filename,
rdistd(1) or
⟨rdistd path⟩ must be somewhere in the
PATH
of the user running
rdist
on the remote (target) host.
The options are as follows:
-A
numrdist
to update or install a file.-a
numrdist
to update or install a file.-c
mini_distfilerdist
to interpret the remaining arguments
as a small distfile. The format is:
$ rdist -c name ... [login@]host[:dest]
The equivalent distfile is as follows:
( name ... ) -> [login@]host install [dest] ;
-D
-d
var=value-F
rdist
processes. All clients
are updated sequentially.-f
distfile-L
remote_logopts-l
local_logopts-M
maxprocrdist
processes to maxproc.
The default is 4.-m
host-m
arguments can be given to limit updates to a
subset of the hosts listed in distfile.-n
-o
distoptschknfs
chkreadonly
chksym
rdist
, but is present to allow compatibility
with older versions.compare
defgroup
[=groupname]defowner
[=owner]follow
history
savetargets
and
history
are both defined then the target file
that is updated is first renamed from file to
file.NNN where NNN increases for each
generation update. The first generation is 001, and the last is 999.
After 999 generations, the counter is reset and stuck to 001, and 001
will get overwritten all the time. This is undesirable behavior, so
some other method needs to be devised to clean up or limit the number
of generations.ignlnks
rdist
will normally
try to maintain the link structure of files being transferred and warn
the user if all the links cannot be found.nochkgroup
nochkmode
nochkowner
nodescend
rdist
will recursively check directories. If
this option is enabled, then any files listed in the file list in the
distfile that are directories are not recursively scanned. Only the
existence, ownership, and mode of the directory are checked.noexec
numchkgroup
numchkowner
quiet
remove
savetargets
sparse
updateperm
verify
whole
younger
rdist
not to update files
that are younger than the master copy. This can be used to prevent
newer copies on other hosts from being replaced. A warning message is
printed for files which are newer than the master copy.-P
rsh-path-p
rdistd-path-t
timeoutrdist
server. The default is 900
seconds.-V
The distfile contains a sequence of entries that specify the files to be copied, the destination hosts, and what operations to perform to do the updating. Each entry has one of the following formats.
<variable name> = <name list> [ label: ] <source list> -> <destination list> <command list> [ label: ] <source list> :: <timestamp file> <command list>
The first format is used for defining variables. The second format is used for distributing files to other hosts. The third format is used for making lists of files that have been changed since some given date. The source list specifies a list of files and/or directories on the local host which are to be used as the master copy for distribution. The destination list is the list of hosts to which these files are to be copied. Each file in the source list is added to a list of changes if the file is out of date on the host which is being updated (second format) or the file is newer than the timestamp file (third format).
Newlines, tabs, and blanks are only used as separators and are otherwise ignored. Comments begin with ‘#’ and end with a newline.
Variables to be expanded begin with ‘$’ followed by one character or a name enclosed in curly braces (see the examples at the end).
Labels are optional. They are used to identify a specific command to execute (for example, allowing an update of a subset of a repository).
The source and destination lists have the following format:
<name>
`(' <zero or more names separated by whitespace> `)'
These simple lists can be modified by using one level of set addition, subtraction, or intersection like this:
list - list
list + list
list & list
If additional modifications are needed (e.g. “all servers and client machines except for the OSF/1 machines”) then the list will have to be explicitly constructed in steps using “temporary” variables.
The shell meta-characters `[', `]', `{', `}', `*', and `?' are
recognized and expanded (on the local host only) in the same way as
ksh(1). They can be escaped with
a backslash. The `~' character is also expanded in the same way as
ksh(1) but is expanded
separately on the local and destination hosts. When the
-o
whole option is used with a
file name that begins with `~', everything except the home directory is
appended to the destination name. File names which do not begin with `/' or
`~' use the destination user's home directory as the root directory for the
rest of the file name.
The command list consists of zero or more commands of the following format:
install | <options> | opt_dest_name | ; |
notify | <name list> | ; | |
except | <name list> | ; | |
except_pat | <pattern list> | ; | |
special | <name list> | string | ; |
cmdspecial | <name list> | string | ; |
The install
command is used to copy
out-of-date files and/or directories. Each source file is copied to each
host in the destination list. Directories are recursively copied in the same
way. opt_dest_name is an optional parameter to rename
files. If no install
command appears in the command
list or the destination name is not specified, the source file name is used.
Directories in the path name will be created if they do not exist on the
remote host. The -o
distopts
option as specified above has the same semantics as on the command line
except distopts only applies to the files in the
source list. 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”.
The notify
command is used to mail the
list of files updated (and any errors that may have occurred) to the listed
names. If no `@' appears in the name, the destination host is appended to
the name (e.g. name1@host, name2@host, ...).
The except
command is used to
update all of the files in the source list
except for the
files listed in name list. This is usually used to
copy everything in a directory except certain files.
The except_pat
command is like the
except
command except that pattern
list is a list of basic regular expressions (see
re_format(7) for details).
If one of the patterns matches some string within a file name, that file
will be ignored. Note that since `\' is a quote character, it must be
doubled to become part of the regular expression. Variables are expanded in
pattern list but not shell file pattern matching
characters. To include a `$', it must be escaped with `\'.
The special
command is used to specify
sh(1) commands that are to be
executed on the remote host after the file in name
list is updated or installed. If the name list
is omitted then the shell commands will be executed for every file updated
or installed. string starts and ends with `"' and
can cross multiple lines in distfile. Multiple
commands to the shell should be separated by `;'. Commands are executed in
the user's home directory on the host being updated. The
special
command can be used, for example, to rebuild
private databases after a program has been updated. The following
environment variables are set for each special
command:
The cmdspecial
command is similar to the
special
command, except it is executed only when the
entire command is completed instead of after each file is updated. The list
of files is placed in the FILES
environment
variable. Each file name in FILES
is separated by a
‘:’ (colon).
If a hostname ends in a ‘+’ (plus sign), then the
plus is stripped off and NFS checks are disabled. This is equivalent to
disabling the -o
chknfs option
just for this one host.
rdist
uses a collection of predefined
message
facilities
that each contain a list of message
types
specifying which types of messages to send to that facility. The local
client and the remote server each maintain their own copy of what types of
messages to log to what facilities.
The -l
local_logopts
option specifies the logging options to use locally;
-L
remote_logopts specifies
the logging options to pass to the remote server.
Logging options should be of the form:
The valid facility names are:
file
file=/tmp/rdist.log=all,debug
notify
rdist
notify
facility. This facility is used in
conjunction with the notify
keyword in a
distfile to specify what messages are mailed to
the notify
address.stdout
syslog
types should be a comma separated list of message types. Each message type specified enables that message level. This is unlike the syslog(3) system facility which uses an ascending order scheme. The following are the valid types:
all
change
debug
ferror
info
nerror
notice
warning
nerror
type messages.Here is a sample command line option:
-l stdout=all:syslog=change,notice:file=/tmp/rdist.log=all
This entry will set local message logging to have all but debug messages sent to standard output, change and notice messages will be sent to syslog(3), and all messages will be written to the file /tmp/rdist.log.
rdist
command file.rdist
command file.The following is an example distfile:
HOSTS = ( matisse root@arpa) FILES = ( /bin /lib /usr/bin /usr/games /usr/include/{*.h,{stand,sys,vax*,pascal,machine}/*.h} /usr/lib /usr/man/man? /usr/ucb /usr/local/rdist ) EXLIB = ( Mail.rc aliases aliases.db crontab dshrc sendmail.cf sendmail.hf sendmail.st uucp vfont ) ${FILES} -> ${HOSTS} install -oremove,chknfs ; except /usr/lib/${EXLIB} ; except /usr/games/lib ; special /usr/lib/sendmail "/usr/lib/sendmail -bi" ; srcs: /usr/src/bin -> arpa except_pat ( \\.o\$ /SCCS\$ ) ; IMAGEN = (ips dviimp catdvi) imagen: /usr/local/${IMAGEN} -> arpa install /usr/local/lib ; notify ralph ; sendmail.cf :: stamp.cory notify root@cory ;
Using the above distfile:
Update everything that's out of date, making any relevant notifications:
$ rdist
Update files in /usr/src/bin to host “arpa”, except for files with names ending “.o” or “/SCCS”:
$ rdist srcs
Update sendmail.cf if it's older than timestamp file stamp.cory, notifying root@cory if an update has happened:
$ rdist sendmail.cf
rdistd(1), sh(1), ssh(1), re_format(7), daily(8), syslogd(8)
The options [-bhiNOqRrsvwxy
] are still
recognized for backwards compatibility.
If the basename of a file (the last component in the pathname) is
‘.’, rdist
assumes the remote
(destination) name is a directory. That is, /tmp/.
means that /tmp should be a directory on the remote
host.
Source files must reside on the local host where
rdist
is executed.
Variable expansion only works for name lists; there should be a general macro facility.
rdist
aborts on files which have a
negative mtime (before Jan 1, 1970).
If a hardlinked file is listed more than once in the same target,
rdist
will report missing links. Only one instance
of a link should be listed in each target.
The defowner
,
defgroup
, and updateperm
options are extensions to the 6.1.0 protocol and will not work with earlier
versions of rdist 6.
January 1, 2017 | OpenBSD-6.4 |