mailto(rsync-bugs@samba.org)
-manpage(rsync)(1)(29 May 2001)()()
+manpage(rsync)(1)(25 Jan 2002)()()
manpagename(rsync)(faster, flexible replacement for rcp)
manpagesynopsis()
rsync is a program that behaves in much the same way that rcp does,
but has many more options and uses the rsync remote-update protocol to
-greatly speedup file transfers when the destination file already
+greatly speed up file transfers when the destination file already
exists.
The rsync remote-update protocol allows rsync to transfer just the
to. rsync uses rsh for its communications, unless both the source and
destination are local.
-You can also specify an alternative to rsh, by either using the -e
+You can also specify an alternative to rsh, either by using the -e
command line option, or by setting the RSYNC_RSH environment variable.
One common substitute is to use ssh, which offers a high degree of
transport. In this case you will connect to a remote rsync server
running on TCP port 873.
-You may establish the connetcion via a web proxy by setting the
+You may establish the connection via a web proxy by setting the
environment variable RSYNC_PROXY to a hostname:port pair pointing to
-your web proxy. Note that your web proxy must allow proxying to port
-873, this must be configured in your proxy servers ruleset.
+your web proxy. Note that your web proxy's configuration must allow
+proxying to port 873.
Using rsync in this way is the same as using it with rsh or ssh except
that:
--backup-dir make backups into this directory
--suffix=SUFFIX override backup suffix
-u, --update update only (don't overwrite newer files)
- -l, --links preserve soft links
- -L, --copy-links treat soft links like regular files
+ -l, --links copy symlinks as symlinks
+ -L, --copy-links copy the referent of symlinks
--copy-unsafe-links copy links outside the source tree
--safe-links ignore links outside the destination tree
-H, --hard-links preserve hard links
-S, --sparse handle sparse files efficiently
-n, --dry-run show what would have been transferred
-W, --whole-file copy whole files, no incremental checks
+ --no-whole-file turn off --whole-file
-x, --one-file-system don't cross filesystem boundaries
-B, --block-size=SIZE checksum blocking size (default 700)
-e, --rsh=COMMAND specify rsh replacement
--rsync-path=PATH specify path to rsync on the remote machine
-C, --cvs-exclude auto ignore files in the same way CVS does
--existing only update files that already exist
+ --ignore-existing ignore files that already exist on the receiving side
--delete delete files that don't exist on the sending side
--delete-excluded also delete excluded files on the receiving side
--delete-after delete after transferring, not before
--include-from=FILE don't exclude patterns listed in FILE
--version print version number
--daemon run as a rsync daemon
- --address bind to the specified address
+ --no-detach do not detach from the parent
+ --address=ADDRESS bind to the specified address
--config=FILE specify alternate rsyncd.conf file
--port=PORT specify alternate rsyncd port number
--blocking-io use blocking IO for the remote shell
+ --no-blocking-io turn off --blocking-io
--stats give some file transfer stats
--progress show progress during transfer
--log-format=FORMAT log file transfers using specified format
--password-file=FILE get password from FILE
--bwlimit=KBPS limit I/O bandwidth, KBytes per second
- -f, --read-batch=FILE read batch file
- -F, --write-batch write batch file
+ --read-batch=PREFIX read batch fileset starting with PREFIX
+ --write-batch=PREFIX write batch fileset starting with PREFIX
-h, --help show this help screen
destination file already exists and has a date later than the source
file.
-dit(bf(-l, --links)) This tells rsync to recreate symbolic links on the
-remote system to be the same as the local system. Without this
-option, all symbolic links are skipped.
+dit(bf(-l, --links)) When symlinks are encountered, recreate the
+symlink on the destination.
-dit(bf(-L, --copy-links)) This tells rsync to treat symbolic links just
-like ordinary files.
+dit(bf(-L, --copy-links)) When symlinks are encountered, the file that
+they point to is copied, rather than the symlink.
-dit(bf(--copy-unsafe-links)) This tells rsync to treat symbolic links that
-point outside the source tree like ordinary files. Absolute symlinks are
-also treated like ordinary files, and so are any symlinks in the source
-path itself when --relative is used.
+dit(bf(--copy-unsafe-links)) This tells rsync to copy the referent of
+symbolic links that point outside the source tree. Absolute symlinks
+are also treated like ordinary files, and so are any symlinks in the
+source path itself when --relative is used.
dit(bf(--safe-links)) This tells rsync to ignore any symbolic links
which point outside the destination tree. All absolute symlinks are
"disk" is actually a networked file system). This is the default when both
the source and target are on the local machine.
+dit(bf(--no-whole-file)) Turn off --whole-file, for use when it is the
+default.
+
dit(bf(-p, --perms)) This option causes rsync to update the remote
permissions to be the same as the local permissions.
-dit(bf(-o, --owner)) This option causes rsync to update the remote owner
-of the file to be the same as the local owner. This is only available
-to the super-user. Note that if the source system is a daemon using chroot,
-the --numeric-ids option is implied because the source system cannot get
-access to the usernames.
+dit(bf(-o, --owner)) This option causes rsync to set the owner of the
+destination file to be the same as the source file. On most systems,
+only the super-user can set file ownership.
-dit(bf(-g, --group)) This option causes rsync to update the remote group
-of the file to be the same as the local group. If the receving system is
-not running as the super-user, only groups that the receiver is a member of
-will be preserved (by group name, not group id number).
+dit(bf(-g, --group)) This option causes rsync to set the group of the
+destination file to be the same as the source file. If the receiving
+program is not running as the super-user, only groups that the
+receiver is a member of will be preserved (by group name, not group id
+number).
dit(bf(-D, --devices)) This option causes rsync to transfer character and
block device information to the remote system to recreate these
dit(bf(--existing)) This tells rsync not to create any new files -
only update files that already exist on the destination.
+dit(bf(--ignore-existing))
+This tells rsync not to update files that already exist on
+the destination.
+
dit(bf(--max-delete=NUM)) This tells rsync not to delete more than NUM
files or directories. This is useful when mirroring very large trees
to prevent disasters.
even when there are IO errors.
dit(bf(--force)) This options tells rsync to delete directories even if
-they are not empty. This applies to both the --delete option and to
-cases where rsync tries to copy a normal file but the destination
-contains a directory of the same name.
-
-Since this option was added, deletions were reordered to be done depth-first
-so it is hardly ever needed anymore except in very obscure cases.
+they are not empty when they are to be replaced by non-directories. This
+is only relevant without --delete because deletions are now done depth-first.
+Requires the --recursive option (which is implied by -a) to have any effect.
dit(bf(-B , --block-size=BLOCKSIZE)) This controls the block size used in
the rsync algorithm. See the technical report for details.
then files listed in a $HOME/.cvsignore are added to the list and any
files listed in the CVSIGNORE environment variable (space delimited).
-Finally in each directory any files listed in the .cvsignore file in
-that directory are added to the list.
+Finally, any file is ignored if it is in the same directory as a
+.cvsignore file and matches one of the patterns listed therein. See
+the bf(cvs(1)) manual for more information.
dit(bf(--csum-length=LENGTH)) By default the primary checksum used in
rsync is a very strong 16 byte MD4 checksum. In most cases you will
0 are never mapped via user/group names even if the --numeric-ids
option is not specified.
-If the source system is a daemon using chroot, or if a user or group name
-does not exist on the destination system, then the numeric id from the
-source system is used instead.
+If the source system is a daemon using chroot, or if a user or group
+name does not exist on the destination system, then the numeric id
+from the source system is used instead.
dit(bf(--timeout=TIMEOUT)) This option allows you to set a maximum IO
timeout in seconds. If no data is transferred for the specified time
then rsync will exit. The default is 0, which means no timeout.
-dit(bf(--daemon)) This tells rsync that it is to run as a rsync
-daemon. If standard input is a socket then rsync will assume that it
-is being run via inetd, otherwise it will detach from the current
-terminal and become a background daemon. The daemon will read the
-config file (/etc/rsyncd.conf) on each connect made by a client and
-respond to requests accordingly. See the rsyncd.conf(5) man page for more
-details.
+dit(bf(--daemon)) This tells rsync that it is to run as a daemon. The
+daemon may be accessed using the bf(host::module) or
+bf(rsync://host/module/) syntax.
+
+If standard input is a socket then rsync will assume that it is being
+run via inetd, otherwise it will detach from the current terminal and
+become a background daemon. The daemon will read the config file
+(/etc/rsyncd.conf) on each connect made by a client and respond to
+requests accordingly. See the rsyncd.conf(5) man page for more
+details.
+
+dit(bf(--no-detach)) When running as a daemon, this option instructs
+rsync to not detach itself and become a background process. This
+option is required when running as a service on Cygwin, and may also
+be useful when rsync is supervised by a program such as
+bf(daemontools) or AIX's bf(System Resource Controller).
+bf(--no-detach) is also recommended when rsync is run under a
+debugger. This option has no effect if rsync is run from inetd or
+sshd.
dit(bf(--address)) By default rsync will bind to the wildcard address
when run as a daemon with the --daemon option or when connecting to a
non-blocking IO. You may find the --blocking-io option is needed for some
remote shells that can't handle non-blocking IO. Ssh prefers blocking IO.
+dit(bf(--no-blocking-io)) Turn off --blocking-io, for use when it is the
+default.
+
dit(bf(--log-format=FORMAT)) This allows you to specify exactly what the
rsync client logs to stdout on a per-file basis. The log format is
specified using the same format conventions as the log format option in
result is an average transfer rate equalling the specified limit. A value
of zero specifies no limit.
-dit(bf(--read-batch)) Apply a previously generated change batch.
+dit(bf(--write-batch=PREFIX)) Generate a set of files that can be
+transferred as a batch update. Each filename in the set starts with
+PREFIX. See the "BATCH MODE" section for details.
-dit(bf(--write-batch)) Generate a set of files that can be transferred
-as a batch update.
+dit(bf(--read-batch=PREFIX)) Apply a previously generated change batch,
+using the fileset whose filenames start with PREFIX. See the "BATCH
+MODE" section for details.
enddit()
The exclude and include patterns specified to rsync allow for flexible
selection of which files to transfer and which files to skip.
-rsync builds a ordered list of include/exclude options as specified on
+rsync builds an ordered list of include/exclude options as specified on
the command line. When a filename is encountered, rsync checks the
name against each exclude/include pattern in turn. The first matching
pattern is acted on. If it is an exclude pattern, then that file is
part of an include option. The "- " part is discarded before matching.
it() if the pattern is a single exclamation mark ! then the current
- exclude list is reset, removing all previous exclude patterns.
+ include/exclude list is reset, removing all previously defined patterns.
)
The +/- rules are most useful in exclude lists, allowing you to have a
manpagesection(BATCH MODE)
-The following call generates 4 files that encapsulate the information
-for synchronizing the contents of bf(target_dir) with the updates found in
-bf(src_dir)
+bf(Note:) Batch mode should be considered experimental in this version
+of rsync. The interface or behaviour may change before it stabilizes.
+
+Batch mode can be used to apply the same set of updates to many
+identical systems. Suppose one has a tree which is replicated on a
+number of hosts. Now suppose some changes have been made to this
+source tree and those changes need to be propagated to the other
+hosts. In order to do this using batch mode, rsync is run with the
+write-batch option to apply the changes made to the source tree to one
+of the destination trees. The write-batch option causes the rsync
+client to store the information needed to repeat this operation against
+other destination trees in a batch update fileset (see below). The
+filename of each file in the fileset starts with a prefix specified by
+the user as an argument to the write-batch option. This fileset is
+then copied to each remote host, where rsync is run with the read-batch
+option, again specifying the same prefix, and the destination tree.
+Rsync updates the destination tree using the information stored in the
+batch update fileset.
+
+The fileset consists of 4 files:
-quote(
-$ rsync -F [other rsync options here] \nl()
- /somewhere/src_dir /somewhere/target_dir
+itemize(
+it() bf(<prefix>.rsync_argvs) command-line arguments
+it() bf(<prefix>.rsync_flist) rsync internal file metadata
+it() bf(<prefix>.rsync_csums) rsync checksums
+it() bf(<prefix>.rsync_delta) data blocks for file update & change
)
-The generated files are labeled with a common timestamp:
+The .rsync_argvs file contains a command-line suitable for updating a
+destination tree using that batch update fileset. It can be executed
+using a Bourne(-like) shell, optionally passing in an alternate
+destination tree pathname which is then used instead of the original
+path. This is useful when the destination tree path differs from the
+original destination tree path.
-itemize(
-it() bf(rsync_argvs.<timestamp>) command-line arguments
-it() bf(rsync_flist.<timestamp>) rsync internal file metadata
-it() bf(rsync_csums.<timestamp>) rsync checksums
-it() bf(rsync_delta.<timestamp>) data blocks for file update & change
+Generating the batch update fileset once saves having to perform the
+file status, checksum and data block generation more than once when
+updating multiple destination trees. Multicast transport protocols can
+be used to transfer the batch update files in parallel to many hosts at
+once, instead of sending the same data to every host individually.
+
+Example:
+
+verb(
+$ rsync --write_batch=pfx -a /source/dir/ /adest/dir/
+$ rcp pfx.rsync_* remote:
+$ rsh remote rsync --read_batch=pfx -a /bdest/dir/
+# or alternatively
+$ rsh remote ./pfx.rsync_argvs /bdest/dir/
)
+In this example, rsync is used to update /adest/dir/ with /source/dir/
+and the information to repeat this operation is stored in the files
+pfx.rsync_*. These files are then copied to the machine named "remote".
+Rsync is then invoked on "remote" to update /bdest/dir/ the same way as
+/adest/dir/. The last line shows the rsync_argvs file being used to
+invoke rsync.
+
+Caveats:
+
+The read-batch option expects the destination tree it is meant to update
+to be identical to the destination tree that was used to create the
+batch update fileset. When a difference between the destination trees
+is encountered the update will fail at that point, leaving the
+destination tree in a partially updated state. In that case, rsync can
+be used in its regular (non-batch) mode of operation to fix up the
+destination tree.
+
+The rsync version used on all destinations should be identical to the
+one used on the original destination.
+
+The -z/--compress option does not work in batch mode and yields a usage
+error. A separate compression tool can be used instead to reduce the
+size of the batch update files for transport to the destination.
+
+The -n/--dryrun option does not work in batch mode and yields a runtime
+error.
+
See bf(http://www.ils.unc.edu/i2dsi/unc_rsync+.html) for papers and technical
reports.
+manpagesection(SYMBOLIC LINKS)
+
+Three basic behaviours are possible when rsync encounters a symbolic
+link in the source directory.
+
+By default, symbolic links are not transferred at all. A message
+"skipping non-regular" file is emitted for any symlinks that exist.
+
+If bf(--links) is specified, then symlinks are recreated with the same
+target on the destination. Note that bf(--archive) implies
+bf(--links).
+
+If bf(--copy-links) is specified, then symlinks are "collapsed" by
+copying their referent, rather than the symlink.
+
+rsync also distinguishes "safe" and "unsafe" symbolic links. An
+example where this might be used is a web site mirror that wishes
+ensure the rsync module they copy does not include symbolic links to
+bf(/etc/passwd) in the public section of the site. Using
+bf(--copy-unsafe-links) will cause any links to be copied as the file
+they point to on the destination. Using bf(--safe-links) will cause
+unsafe links to be ommitted altogether.
+
manpagesection(DIAGNOSTICS)
rsync occasionally produces error messages that may seem a little
manpagesection(THANKS)
Thanks to Richard Brent, Brendan Mackay, Bill Waite, Stephen Rothwell
-and David Bell for helpful suggestions and testing of rsync. I've
-probably missed some people, my apologies if I have.
+and David Bell for helpful suggestions, patches and testing of rsync.
+I've probably missed some people, my apologies if I have.
+
+Especial thanks also to: David Dykstra, Jos Backus, Sebastian Krahmer.
manpageauthor()
-rsync was written by Andrew Tridgell and Paul Mackerras. They may be
-contacted via email at tridge@samba.org and
-Paul.Mackerras@cs.anu.edu.au
+rsync was written by Andrew Tridgell <tridge@samba.org> and Paul
+Mackerras.
-rsync is now also maintained by Martin Pool <mbp@samba.org>
+rsync is now maintained by Martin Pool <mbp@samba.org>.
+Mailing lists for support and development are available at
+url(http://lists.samba.org)(lists.samba.org)
+If you suspect you have found a security vulnerability in rsync,
+please send it directly to Martin Pool and Andrew Tridgell. For other
+enquiries, please use the mailing list.
Matt McCutchen's Web Site / rsync / rsync.git / blobdiff