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
--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
--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=FILE read batch file
+ --write-batch write batch file
-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
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
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)
+bf(Note:) Batch mode should be considered experimental in this version
+of rsync. The interface or behaviour may change before it stabilizes.
+
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)
quote(
-$ rsync -F [other rsync options here] \nl()
+$ rsync --write-batch [other rsync options here] \nl()
/somewhere/src_dir /somewhere/target_dir
)
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