mailto(rsync-bugs@samba.org)
-manpage(rsync)(1)(24 Mar 2004)()()
+manpage(rsync)(1)(30 Apr 2004)()()
manpagename(rsync)(faster, flexible replacement for rcp)
manpagesynopsis()
Some of the additional features of rsync are:
itemize(
- it() support for copying links, devices, owners, groups and permissions
+ it() support for copying links, devices, owners, groups, and permissions
it() exclude and exclude-from options similar to GNU tar
it() a CVS exclude mode for ignoring the same files that CVS would ignore
it() can use any transparent remote shell, including ssh or rsh
--backup-dir make backups into this directory
--suffix=SUFFIX backup suffix (default ~ w/o --backup-dir)
-u, --update update only (don't overwrite newer files)
+ -K, --keep-dirlinks treat symlinked dir on receiver as dir
-l, --links copy symlinks as symlinks
-L, --copy-links copy the referent of all symlinks
--copy-unsafe-links copy the referent of "unsafe" symlinks
--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
- --write-batch=PREFIX write batch fileset starting with PREFIX
- --read-batch=PREFIX read batch fileset starting with PREFIX
+ --write-batch=FILE write a batch to FILE
+ --read-batch=FILE read a batch from FILE
+ --checksum-seed=NUM set block/file checksum seed
+ -4 --ipv4 prefer IPv4
+ -6 --ipv6 prefer IPv6
-h, --help show this help screen
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(-K, --keep-dirlinks)) On the receiving side, if a symlink is
+pointing to a directory, it will be treated as matching a directory
+from the sender.
+
dit(bf(-l, --links)) When symlinks are encountered, recreate the
symlink on the destination.
dit(bf(-W, --whole-file)) With this option the incremental rsync algorithm
is not used and the whole file is sent as-is instead. The transfer may be
faster if this option is used when the bandwidth between the source and
-target machines is higher than the bandwidth to disk (especially when the
+destination machines is higher than the bandwidth to disk (especially when the
"disk" is actually a networked filesystem). This is the default when both
-the source and target are on the local machine.
+the source and destination are specified as local paths.
dit(bf(--no-whole-file)) Turn off --whole-file, for use when it is the
default.
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
+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
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
dit(bf(--include-from=FILE)) This specifies a list of include patterns
from a file.
-If em(FILE) is bf(-) the list will be read from standard input.
+If em(FILE) is "-" the list will be read from standard input.
dit(bf(--files-from=FILE)) Using this option allows you to specify the
exact list of files to transfer (as read from the specified FILE or "-"
-for stdin). It also tweaks the default behavior of rsync to make
+for standard input). It also tweaks the default behavior of rsync to make
transferring just the specified files and directories easier. For
instance, the --relative option is enabled by default when this option
is used (use --no-relative if you want to turn that off), all
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
result is an average transfer rate equaling the specified limit. A value
of zero specifies no limit.
-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(--read-batch=PREFIX)) Apply a previously generated change batch,
-using the fileset whose filenames start with PREFIX. See the "BATCH
-MODE" section for details.
+dit(bf(--write-batch=FILE)) Record a file that can later be applied to
+anonther identical destination with --read-batch. See the "BATCH MODE"
+section for details.
+
+dit(bf(--read-batch=FILE)) Apply all of the changes stored in FILE, a
+file previously generated by --write-batch.
+If em(FILE) is "-" the list will be read from standard input.
+See the "BATCH MODE" section for details.
+
+dit(bf(-4, --ipv4) or bf(-6, --ipv6)) Tells rsync to prefer IPv4/IPv6
+when creating sockets. This only affects sockets that rsync has direct
+control over, such as the outgoing socket when directly contacting an
+rsync daemon, or the incoming sockets that an rsync daemon uses to
+listen for connections. One of these options may be required in older
+versions of Linux to work around an IPv6 bug in the kernel (if you see
+an "address already in use" error when nothing else is using the port,
+try specifying --ipv6 or --ipv4 when starting the daemon).
+
+dit(bf(--checksum-seed=NUM)) Set the MD4 checksum seed to the integer
+NUM. This 4 byte checksum seed is included in each block and file
+MD4 checksum calculation. By default the checksum seed is generated
+by the server and defaults to the current time(). This option
+is used to set a specific checksum seed, which is useful for
+applications that want repeatable block and file checksums, or
+in the case where the user wants a more random checksum seed.
+Note that setting NUM to 0 causes rsync to use the default of time()
+for checksum seed.
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 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
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 the source path or changing your use of the --relative
+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 a source filename that has an absolute
-path of "/home/me/foo/bar", here is how the various command choices can
-differ:
+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 /dest
- Source root: /home ("me" is part of transfer)
+ 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/ /dest
- Source root: /home/me (due to trailing /)
- +/- pattern: /foo/bar (note missing "me")
+ 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/ /dest
- Source root: /home/me
- +/- pattern: /home/me/foo/bar (note full path)
+ 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
+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
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.
+
+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:
-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 '*'.
+verb(
+ + /some/path/this-file-will-not-be-found
+ + /file-is-included
+ - *
+)
-Here are some exclude/include examples:
+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 --exclude='*' 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
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.
+of rsync. The interface or behavior 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
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.
+client to store in a "batch file" all the information needed to repeat
+this operation against other, identical destination trees.
+
+To apply the recorded changes to another destination tree, run rsync
+with the read-batch option, specifying the name of the same batch
+file, and the destination tree. Rsync updates the destination tree
+using the information stored in the batch file.
+
+For convenience, one additional file is creating when the write-batch
+option is used. This file's name is created by appending
+".rsync_argvs" to the batch filename. The .rsync_argvs file contains
+a command-line suitable for updating a destination tree using that
+batch file. 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.
+
+Generating the batch file 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.
-The fileset consists of 4 files:
+Examples:
-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
+verb(
+ $ rsync --write-batch=batch -a /source/dir/ /adest/dir/
+ $ ssh remote rsync --read-batch=- -a /bdest/dir/ <batch
)
-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.
-
-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=batch -a host:/source/dir/ /adest/dir/
+ $ scp batch remote:
+ $ ssh remote rsync --read-batch=batch -a /bdest/dir/
+)
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=batch -a /source/dir/ host:/adest/dir/
+ $ scp batch* remote:
+ $ ssh remote ./batch.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.
+In these examples, rsync is used to update /adest/dir/ with /source/dir/
+and the information to repeat this operation is stored in "batch" and
+"batch.rsync_argvs". The host "remote" is then updated with the batched
+update going into the directory /bdest/dir. The differences between the
+three examples is in how the batch gets to the remote machine (via remote
+stdin or by being copied first), whether the initial transfer was local or
+remote, and in how the batch-reading rsync command is invoked.
Caveats:
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 rsync version used on all destinations must be at least as new as the
+one used to generate the batch file.
The -n/--dryrun option does not work in batch mode and yields a runtime
error.
+You should use an equivalent set of options when reading a batch file that
+you used when generating it with a few exceptions. For instance
+--write-batch changes to --read-batch, --files-from is dropped, and the
+--include/--exclude options are not needed unless --delete is specified
+without --delete-excluded. Other options that affect how the update
+happens should generally remain the same as it is possible to confuse rsync
+into expecting a different data stream than the one that is contained in
+the batch file. For example, it would not work to change the setting of
+the -H or -c option, but it would work to add or remove the --delete
+option.
+
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
+Three basic behaviors are possible when rsync encounters a symbolic
link in the source directory.
By default, symbolic links are not transferred at all. A message
dit(bf(3)) Errors selecting input/output files, dirs
dit(bf(4)) Requested action not supported: an attempt
was made to manipulate 64-bit files on a platform that cannot support
-them; or an option was specifed that is supported by the client and
+them; or an option was specified 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 I/O
dit(bf(USER) or bf(LOGNAME)) The USER or LOGNAME environment variables
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.
times are transferred as unix time_t values
-When transferring to FAT filesystems rsync may resync
+When transferring to FAT filesystems rsync may re-sync
unmodified files.
See the comments on the --modify-window 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