mailto(rsync-bugs@samba.org)
-manpage(rsync)(1)(29 May 2001)()()
+manpage(rsync)(1)(14 Dec 2001)()()
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
--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
which already exist and have the same checksum and size on the
receiver are skipped. This option can be quite slow.
-dit(bf(-a, --archive)) This is equivalent to -rlptgoD. It is a quick way
-of saying you want recursion and want to preserve everything.
+dit(bf(-a, --archive)) This is equivalent to -rlptgoD. It is a quick
+way of saying you want recursion and want to preserve almost
+everything.
+
+Note however that bf(-a) bf(does not preserve hardlinks), because
+finding multiply-linked files is expensive. You must separately
+specify bf(-H).
dit(bf(-r, --recursive)) This tells rsync to copy directories
recursively. If you don't specify this then rsync won't copy
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
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.
-dit(bf(-B , --block_size=BLOCKSIZE)) This controls the block size used in
+dit(bf(-B , --block-size=BLOCKSIZE)) This controls the block size used in
the rsync algorithm. See the technical report for details.
dit(bf(-e, --rsh=COMMAND)) This option allows you to choose an alternative
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
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
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
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 is now also maintained by Martin Pool <mbp@samba.org>
+rsync was written by Andrew Tridgell and Paul Mackerras.
+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)