mailto(rsync-bugs@samba.org)
-manpage(rsync)(1)(1 Jan 2004)()()
+manpage(rsync)(1)(29 Apr 2004)()()
manpagename(rsync)(faster, flexible replacement for rcp)
manpagesynopsis()
it() for copying from a remote rsync server to the local
machine. This is invoked when the source path contains a ::
- separator or a rsync:// URL.
+ separator or an rsync:// URL.
it() for copying from the local machine to a remote rsync
server. This is invoked when the destination path contains a ::
- separator or a rsync:// URL.
+ separator or an rsync:// URL.
it() for copying from a remote machine using a remote shell
program as the transport, using rsync server on the remote
This would recursively transfer all files from the directory src/bar on the
machine foo into the /data/tmp/bar directory on the local machine. The
files are transferred in "archive" mode, which ensures that symbolic
-links, devices, attributes, permissions, ownerships etc are preserved
+links, devices, attributes, permissions, ownerships, etc. are preserved
in the transfer. Additionally, compression will be used to reduce the
size of data portions of the transfer.
itemize(
it() you use a double colon :: instead of a single colon to
- separate the hostname from the path or a rsync:// URL.
+ separate the hostname from the path or an rsync:// URL.
it() the remote server may print a message of the day when you
connect.
--suffix=SUFFIX backup suffix (default ~ w/o --backup-dir)
-u, --update update only (don't overwrite newer 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
+ -L, --copy-links copy the referent of all symlinks
+ --copy-unsafe-links copy the referent of "unsafe" symlinks
+ --safe-links ignore "unsafe" symlinks
-H, --hard-links preserve hard links
-p, --perms preserve permissions
-o, --owner preserve owner (root only)
--delete delete files that don't exist on sender
--delete-excluded also delete excluded files on receiver
--delete-after receiver deletes after transfer, not before
- --ignore-errors delete even if there are IO errors
+ --ignore-errors delete even if there are I/O errors
--max-delete=NUM don't delete more than NUM files
--partial keep partially transferred files
--force force deletion of dirs even if not empty
--numeric-ids don't map uid/gid values by user/group name
- --timeout=TIME set IO timeout in seconds
+ --timeout=TIME set I/O timeout in seconds
-I, --ignore-times turn off mod time & file size quick check
--size-only ignore mod time for quick check (use size)
--modify-window=NUM compare mod times with reduced accuracy
--files-from=FILE read FILE for list of source-file names
-0 --from0 all file lists are delimited by nulls
--version print version number
- --daemon run as a rsync daemon
+ --daemon run as an rsync daemon
--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
+ --blocking-io use blocking I/O for the remote shell
--no-blocking-io turn off --blocking-io
--stats give some file transfer stats
--progress show progress during transfer
already the same size and have the same modification time-stamp.
This option turns off this "quick check" behavior.
-dit(bf(--size-only)) Normally rsync will skip any files that are
+dit(bf(--size-only)) Normally rsync will not transfer any files that are
already the same size and have the same modification time-stamp. With the
---size-only option files will be skipped if they have the same size,
+--size-only option, files will not be transferred if they have the same size,
regardless of timestamp. This is useful when starting to use rsync
after using another mirroring system which may not preserve timestamps
exactly.
a 128-bit MD4 checksum before transfer. The checksum is then
explicitly checked on the receiver and any files of the same name
which already exist and have the same checksum and size on the
-receiver are skipped. This option can be quite slow.
+receiver are not transferred. 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 almost
specify a backup suffix using the --suffix option
(otherwise the files backed up in the specified directory
will keep their original filenames).
+If DIR is a relative path, it is relative to the destination directory
+(which changes in a recursive transfer).
dit(bf(--suffix=SUFFIX)) This option allows you to override the default
backup suffix used with the --backup (-b) option. The default suffix is a ~
destination file already exists and has a date later than the source
file.
+In the currently implementation, a difference of file format is always
+considered to be important enough for an update, no matter what date
+is on the objects. In other words, if the source has a directory or a
+symlink where the destination has a file, the transfer would occur
+regardless of the timestamps. This might change in the future (feel
+free to comment on this on the mailing list if you have an opinion).
+
dit(bf(-l, --links)) When symlinks are encountered, recreate the
symlink on the destination.
dit(bf(-L, --copy-links)) When symlinks are encountered, the file that
-they point to is copied, rather than the symlink.
+they point to (the referent) is copied, rather than the symlink.
dit(bf(--copy-unsafe-links)) This tells rsync to copy the referent of
-symbolic links that point outside the source tree. Absolute symlinks
+symbolic links that point outside the copied 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
+which point outside the copied tree. All absolute symlinks are
also ignored. Using this option in conjunction with --relative may
give unexpected results.
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. Note that if the remote system
-is a daemon using chroot, the --numeric-ids option is implied because the
-remote system cannot get access to the usernames from /etc/passwd.
+only the super-user can set file ownership. By default, the preservation
+is done by name, but may fall back to using the ID number in some
+circumstances. See the --numeric-ids option for a full discussion.
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).
+receiver is a member of will be preserved. By default, the preservation
+is done by name, but may fall back to using the ID number in some
+circumstances. See the --numeric-ids option for a full discussion.
dit(bf(-D, --devices)) This option causes rsync to transfer character and
block device information to the remote system to recreate these
to run first using the dry run option (-n) to see what files would be
deleted to make sure important files aren't listed.
-If the sending side detects any IO errors then the deletion of any
+If the sending side detects any I/O errors then the deletion of any
files at the destination will be automatically disabled. This is to
prevent temporary filesystem failures (such as NFS errors) on the
sending side causing a massive deletion of files on the
after transferring, use the --delete-after switch. Implies --delete.
dit(bf(--ignore-errors)) Tells --delete to go ahead and delete files
-even when there are IO errors.
+even when there are I/O errors.
dit(bf(--force)) This options tells rsync to delete directories even if
they are not empty when they are to be replaced by non-directories. This
The exclude list is initialized to:
-quote(RCS/ SCCS/ CVS/ .svn/ CVS.adm RCSLOG cvslog.* tags TAGS .make.state
-.nse_depinfo *~ #* .#* ,* *.old *.bak *.BAK *.orig *.rej .del-*
-*.a *.o *.obj *.so *.Z *.elc *.ln core)
+quote(RCS SCCS CVS CVS.adm RCSLOG cvslog.* tags TAGS .make.state
+.nse_depinfo *~ #* .#* ,* _$* *$ *.old *.bak *.BAK *.orig *.rej
+.del-* *.a *.olb *.o *.obj *.so *.exe *.Z *.elc *.ln core .svn/)
then files listed in a $HOME/.cvsignore are added to the list and any
-files listed in the CVSIGNORE environment variable (space delimited).
+files listed in the CVSIGNORE environment variable (all cvsignore names
+are delimited by whitespace).
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.
+.cvsignore file and matches one of the patterns listed therein.
+See the bf(cvs(1)) manual for more information.
dit(bf(--exclude=PATTERN)) This option allows you to selectively exclude
certain files from the list of files to be transferred. This is most
You may use as many --exclude options on the command line as you like
to build up the list of files to exclude.
-See the EXCLUDE PATTERNS section for information on the syntax of
-this option.
+See the EXCLUDE PATTERNS section for detailed information on this option.
dit(bf(--exclude-from=FILE)) This option is similar to the --exclude
option, but instead it adds all exclude patterns listed in the file
specified pattern of filenames. This is useful as it allows you to
build up quite complex exclude/include rules.
-See the EXCLUDE PATTERNS section for information on the syntax of
-this option.
+See the EXCLUDE PATTERNS section for detailed information on this option.
dit(bf(--include-from=FILE)) This specifies a list of include patterns
from a file.
dit(bf(-0, --from0)) This tells rsync that the filenames it reads from a
file are terminated by a null ('\0') character, not a NL, CR, or CR+LF.
This affects --exclude-from, --include-from, and --files-from.
+It does not affect --cvs-exclude (since all names read from a .cvsignore
+file are split on whitespace).
dit(bf(-T, --temp-dir=DIR)) This option instructs rsync to use DIR as a
scratch directory when creating temporary copies of the files
This option increases the usefulness of --partial because partially
transferred files will remain in the new temporary destination until they
have a chance to be completed. If DIR is a relative path, it is relative
-to the destination directory.
+to the destination directory (which changes in a recursive transfer).
dit(bf(--link-dest=DIR)) This option behaves like bf(--compare-dest) but
also will create hard links from em(DIR) to the destination directory for
unchanged files. Files with changed ownership or permissions will not be
linked.
Like bf(--compare-dest) if DIR is a relative path, it is relative
-to the destination directory.
+to the destination directory (which changes in a recursive transfer).
+An example:
+
+verb(
+ rsync -av --link-dest=$PWD/prior_dir host:src_dir/ new_dir/
+)
dit(bf(-z, --compress)) With this option, rsync compresses any data from
the files that it sends to the destination machine. This
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 a user or group has no name on the source system or it has no match
+on the destination system, then the numeric ID
+from the source system is used instead. See also the comments on the
+"use chroot" setting in the rsyncd.conf manpage for information on how
+the chroot setting affects rsync's ability to look up the names of the
+users and groups and what you can do about it.
-dit(bf(--timeout=TIMEOUT)) This option allows you to set a maximum IO
+dit(bf(--timeout=TIMEOUT)) This option allows you to set a maximum I/O
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(--port=PORT)) This specifies an alternate TCP port number to use
rather than the default port 873.
-dit(bf(--blocking-io)) This tells rsync to use blocking IO when launching
+dit(bf(--blocking-io)) This tells rsync to use blocking I/O when launching
a remote shell transport. If the remote shell is either rsh or remsh,
rsync defaults to using
-blocking IO, otherwise it defaults to using non-blocking IO. (Note that
-ssh prefers non-blocking IO.)
+blocking I/O, otherwise it defaults to using non-blocking I/O. (Note that
+ssh prefers non-blocking I/O.)
dit(bf(--no-blocking-io)) Turn off --blocking-io, for use when it is the
default.
dit(bf(--password-file)) This option allows you to provide a password
in a file for accessing a remote rsync server. Note that this option
-is only useful when accessing a rsync server using the built in
+is only useful when accessing an rsync server using the built in
transport, not when using a remote shell as the transport. The file
must not be world readable. It should contain just the password as a
single line.
The exclude and include patterns specified to rsync allow for flexible
selection of which files to transfer and which files to skip.
-rsync builds an ordered list of include/exclude options as specified on
+Rsync builds an ordered list of include/exclude options as specified on
the command line. Rsync checks each file and directory
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
skipped. If no matching include/exclude pattern is found then the
filename is not skipped.
-The filenames matched against the exclude/include patterns
-are relative to the destination directory, or "top
-directory", so patterns should not include the path elements
-of the source or destination directories. The only way in
-which a pattern will match the absolute path of a file or
-directory is if the source path is the root directory.
+The filenames matched against the exclude/include patterns are relative
+to the "root of the transfer". If you think of the transfer as a
+subtree of names that are being sent from sender to receiver, the root
+is where the tree starts to be duplicated in the destination directory.
+This root governs where patterns that start with a / match (see below).
+
+Because the matching is relative to the transfer-root, changing the
+trailing slash on a source path or changing your use of the --relative
+option affects the path you need to use in your matching (in addition to
+changing how much of the file tree is duplicated on the destination
+system). The following examples demonstrate this.
+
+Let's say that we want to match two source files, one with an absolute
+path of "/home/me/foo/bar", and one with a path of "/home/you/bar/baz".
+Here is how the various command choices differ for a 2-source transfer:
+
+verb(
+ Example cmd: rsync -a /home/me /home/you /dest
+ +/- pattern: /me/foo/bar
+ +/- pattern: /you/bar/baz
+ Target file: /dest/me/foo/bar
+ Target file: /dest/you/bar/baz
+
+ Example cmd: rsync -a /home/me/ /home/you/ /dest
+ +/- pattern: /foo/bar (note missing "me")
+ +/- pattern: /bar/baz (note missing "you")
+ Target file: /dest/foo/bar
+ Target file: /dest/bar/baz
+
+ Example cmd: rsync -a --relative /home/me/ /home/you /dest
+ +/- pattern: /home/me/foo/bar (note full path)
+ +/- pattern: /home/you/bar/baz (ditto)
+ Target file: /dest/home/me/foo/bar
+ Target file: /dest/home/you/bar/baz
+
+ Example cmd: cd /home; rsync -a --relative me/foo you/ /dest
+ +/- pattern: /me/foo/bar (starts at specified path)
+ +/- pattern: /you/bar/baz (ditto)
+ Target file: /dest/me/foo/bar
+ Target file: /dest/you/bar/baz
+)
+
+The easiest way to see what name you should include/exclude is to just
+look at the output when using --verbose and put a / in front of the name
+(use the --dry-run option if you're not yet ready to copy any files).
-Note that when used with -r (which is implied by -a), every subcomponent of
-every path is visited from top down, so include/exclude patterns get
+Note that, when using the --recursive (-r) option (which is implied by -a),
+every subcomponent of
+every path is visited from the top down, so include/exclude patterns get
applied recursively to each subcomponent.
+The exclude patterns actually short-circuit the directory traversal stage
+when rsync finds the files to send. If a pattern excludes a particular
+parent directory, it can render a deeper include pattern ineffectual
+because rsync did not descend through that excluded section of the
+hierarchy.
Note also that the --include and --exclude options take one pattern
each. To add multiple patterns use the --include-from and
start of the filename, otherwise it is matched against the end of
the filename.
This is the equivalent of a leading ^ in regular expressions.
- Thus "/foo" would match a file called "foo" at the top of the
- transferred tree.
+ Thus "/foo" would match a file called "foo" at the transfer-root
+ (see above for how this is different from the filesystem-root).
On the other hand, "foo" would match any file called "foo"
anywhere in the tree because the algorithm is applied recursively from
top down; it behaves as if each path component gets a turn at being the
end of the file name.
- The leading / does not make the pattern an absolute pathname.
it() if the pattern ends with a / then it will only match a
- directory, not a file, link or device.
+ directory, not a file, link, or device.
it() if the pattern contains a wildcard character from the set
*?[ then expression matching is applied using the shell filename
it() if the pattern starts with "+ " (a plus followed by a space)
then it is always considered an include pattern, even if specified as
- part of an exclude option. The "+ " part is discarded before matching.
+ part of an exclude option. The prefix is discarded before matching.
it() if the pattern starts with "- " (a minus followed by a space)
then it is always considered an exclude pattern, even if specified as
- part of an include option. The "- " part is discarded before matching.
+ part of an include option. The prefix is discarded before matching.
it() if the pattern is a single exclamation mark ! then the current
include/exclude list is reset, removing all previously defined patterns.
The +/- rules are most useful in a list that was read from a file, allowing
you to have a single exclude list that contains both include and exclude
-options.
+options in the proper order.
-If you end an exclude list with --exclude '*', note that since the
-algorithm is applied recursively that unless you explicitly include
-parent directories of files you want to include then the algorithm
-will stop at the parent directories and never see the files below
-them. To include all directories, use --include '*/' before the
---exclude '*'.
+Remember that the matching occurs at every step in the traversal of the
+directory hierarchy, so you must be sure that all the parent directories of
+the files you want to include are not excluded. This is particularly
+important when using a trailing '*' rule. For instance, this won't work:
-Here are some exclude/include examples:
+verb(
+ + /some/path/this-file-will-not-be-found
+ + /file-is-included
+ - *
+)
+
+This fails because the parent directory "some" is excluded by the '*' rule,
+so rsync never visits any of the files in the "some" or "some/path"
+directories. One solution is to ask for all directories in the hierarchy
+to be included by using a single rule: --include='*/' (put it somewhere
+before the --excludde='*' rule). Another solution is to add specific
+include rules for all the parent dirs that need to be visited. For
+instance, this set of rules works fine:
+
+verb(
+ + /some/
+ + /some/path/
+ + /some/path/this-file-is-found
+ + /file-also-included
+ - *
+)
+
+Here are some examples of exclude/include matching:
itemize(
it() --exclude "*.o" would exclude all filenames matching *.o
- it() --exclude "/foo" would exclude a file called foo in the top directory
+ it() --exclude "/foo" would exclude a file called foo in the transfer-root directory
it() --exclude "foo/" would exclude any directory called foo
it() --exclude "/foo/*/bar" would exclude any file called bar two
- levels below a directory called foo in the top directory
+ levels below a directory called foo in the transfer-root directory
it() --exclude "/foo/**/bar" would exclude any file called bar two
- or more levels below a directory called foo in the top directory
+ or more levels below a directory called foo in the transfer-root directory
it() --include "*/" --include "*.c" --exclude "*" would include all
directories and C source files
it() --include "foo/" --include "foo/bar.c" --exclude "*" would include
Example:
verb(
-$ rsync --write-batch=pfx -a /source/dir/ /adest/dir/
-$ rcp pfx.rsync_* remote:
-$ ssh remote rsync --read-batch=pfx -a /bdest/dir/
-# or alternatively
-$ ssh remote ./pfx.rsync_argvs /bdest/dir/
+ $ rsync --write-batch=pfx -a /source/dir/ /adest/dir/
+ $ rcp pfx.rsync_* remote:
+ $ ssh remote rsync --read-batch=pfx -a /bdest/dir/
+ # or alternatively
+ $ ssh remote ./pfx.rsync_argvs /bdest/dir/
)
In this example, rsync is used to update /adest/dir/ with /source/dir/
them; or an option was specifed that is supported by the client and
not by the server.
dit(bf(5)) Error starting client-server protocol
-dit(bf(10)) Error in socket IO
-dit(bf(11)) Error in file IO
+dit(bf(10)) Error in socket I/O
+dit(bf(11)) Error in file I/O
dit(bf(12)) Error in rsync protocol data stream
dit(bf(13)) Errors with program diagnostics
dit(bf(14)) Error in IPC code
rsync daemon. You should set RSYNC_PROXY to a hostname:port pair.
dit(bf(RSYNC_PASSWORD)) Setting RSYNC_PASSWORD to the required
-password allows you to run authenticated rsync connections to a rsync
+password allows you to run authenticated rsync connections to an rsync
daemon without user intervention. Note that this does not supply a
password to a shell transport such as ssh.
dit(bf(USER) or bf(LOGNAME)) The USER or LOGNAME environment variables
-are used to determine the default username sent to a rsync server.
+are used to determine the default username sent to an rsync server.
+If neither is set, the username defaults to "nobody".
dit(bf(HOME)) The HOME environment variable is used to find the user's
default .cvsignore file.
unmodified files.
See the comments on the --modify-window option.
-file permissions, devices etc are transferred as native numerical
+file permissions, devices, etc. are transferred as native numerical
values
see also the comments on the --delete option
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.
-
+Especial thanks also to: David Dykstra, Jos Backus, Sebastian Krahmer,
+Martin Pool, Wayne Davison.
manpageauthor()
-rsync was written by Andrew Tridgell <tridge@samba.org> and Paul
-Mackerras.
-
-rsync is now maintained by Martin Pool <mbp@samba.org>.
+rsync was originally written by Andrew Tridgell and Paul Mackerras.
+Many people have later contributed to it.
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