mailto(rsync-bugs@samba.org)
-manpage(rsync)(1)(30 Apr 2004)()()
+manpage(rsync)(1)(30 Sep 2004)()()
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 speed up file transfers when the destination file already
-exists.
+greatly speed up file transfers when the destination file is being
+updated.
The rsync remote-update protocol allows rsync to transfer just the
differences between two sets of files across the network connection, using
Perhaps the best way to explain the syntax is with some examples:
-quote(rsync *.c foo:src/)
+quote(rsync -t *.c foo:src/)
This would transfer all files matching the pattern *.c from the
current directory to the directory src on the machine foo. If any of
files in the same way, including their setting of the attributes of
/dest/foo:
-quote(rsync -avz /src/foo /dest)
-quote(rsync -avz /src/foo/ /dest/foo)
+quote(rsync -av /src/foo /dest)
+quote(rsync -av /src/foo/ /dest/foo)
You can also use rsync in local-only mode, where both the source and
destination don't have a ':' in the name. In this case it behaves like
somehost.mydomain.com. (See the following section for more details.)
+manpagesection(ADVANCED USAGE)
+
+The syntax for requesting multiple files from a remote host involves using
+quoted spaces in the SRC. Some examples:
+
+quote(rsync host::'modname/dir1/file1 modname/dir2/file2' /dest)
+
+This would copy file1 and file2 into /dest from an rsync daemon. Each
+additional arg must include the same "modname/" prefix as the first one,
+and must be preceded by a single space. All other spaces are assumed
+to be a part of the filenames.
+
+quote(rsync -av host:'dir1/file1 dir2/file2' /dest)
+
+This would copy file1 and file2 into /dest using a remote shell. This
+word-splitting is done by the remote shell, so if it doesn't work it means
+that the remote shell isn't configured to split its args based on
+whitespace (a very rare setting, but not unknown). If you need to transfer
+a filename that contains whitespace, you'll need to either escape the
+whitespace in a way that the remote shell will understand, or use wildcards
+in place of the spaces. Two examples of this are:
+
+quote(rsync -av host:'file\ name\ with\ spaces' /dest)
+quote(rsync -av host:file?name?with?spaces /dest)
+
+This latter example assumes that your shell passes through unmatched
+wildcards. If it complains about "no match", put the name in quotes.
+
+
manpagesection(CONNECTING TO AN RSYNC SERVER)
It is also possible to use rsync without a remote shell as the
--delete-after receiver deletes after transfer, not before
--ignore-errors delete even if there are I/O errors
--max-delete=NUM don't delete more than NUM files
+ --max-size=SIZE don't transfer any file larger than SIZE
--partial keep partially transferred files
--partial-dir=DIR put a partially transferred file into DIR
--force force deletion of dirs even if not empty
--modify-window=NUM compare mod times with reduced accuracy
-T --temp-dir=DIR create temporary files in directory DIR
--compare-dest=DIR also compare received files relative to DIR
- --link-dest=DIR create hardlinks to DIR for unchanged files
+ --copy-dest=DIR ... and include copies of unchanged files
+ --link-dest=DIR hardlink to files in DIR when unchanged
-P equivalent to --partial --progress
-z, --compress compress file data
-C, --cvs-exclude auto ignore files in the same way CVS does
--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 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
+ --port=PORT specify double-colon alternate port number
--blocking-io use blocking I/O for the remote shell
--no-blocking-io turn off --blocking-io
--stats give some file transfer stats
-4 --ipv4 prefer IPv4
-6 --ipv6 prefer IPv6
-h, --help show this help screen
+)
+Rsync can also be run as a daemon, in which case the following options are accepted:
+verb(
+ --daemon run as an rsync daemon
+ --address=ADDRESS bind to the specified address
+ --bwlimit=KBPS limit I/O bandwidth, KBytes per second
+ --config=FILE specify alternate rsyncd.conf file
+ --no-detach do not detach from the parent
+ --port=PORT listen on alternate port number
+ -4 --ipv4 prefer IPv4
+ -6 --ipv6 prefer IPv6
+ -h, --help show this help screen
)
manpageoptions()
startdit()
dit(bf(-h, --help)) Print a short help page describing the options
-available in rsync
+available in rsync.
-dit(bf(--version)) print the rsync version number and exit
+dit(bf(--version)) print the rsync version number and exit.
dit(bf(-v, --verbose)) This option increases the amount of information you
are given during the transfer. By default, rsync works silently. A
you want to send several different directories at the same time. For
example, if you used the command
-verb(rsync foo/bar/foo.c remote:/tmp/)
+verb(rsync /foo/bar/foo.c remote:/tmp/)
then this would create a file called foo.c in /tmp/ on the remote
machine. If instead you used
-verb(rsync -R foo/bar/foo.c remote:/tmp/)
+verb(rsync -R /foo/bar/foo.c remote:/tmp/)
then a file called /tmp/foo/bar/foo.c would be created on the remote
-machine -- the full path name is preserved.
+machine -- the full path name is preserved. To limit the amount of
+path information that is sent, do something like this:
+
+verb(cd /foo
+rsync -R bar/foo.c remote:/tmp/)
+
+That would create /tmp/bar/foo.c on the remote machine.
dit(bf(--no-relative)) Turn off the --relative option. This is only
needed if you want to use --files-from without its implied --relative
backup suffix used with the --backup (-b) option. The default suffix is a ~
if no --backup-dir was specified, otherwise it is an empty string.
-dit(bf(-u, --update)) This forces rsync to skip any files for which the
-destination file already exists and has a date later than the source
-file.
+dit(bf(-u, --update)) This forces rsync to skip any files which exist on
+the destination and have a modified time that is newer than the source
+file. (If an existing destination file has a modify time equal to the
+source file's, it will be updated if the sizes are different.)
-In the currently implementation, a difference of file format is always
+In the current implementation of --update, a difference of file format
+between the sender and receiver 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
dit(bf(--inplace)) This causes rsync not to create a new copy of the file
and then move it into place. Instead rsync will overwrite the existing
file, meaning that the rsync algorithm can't extract the full amount of
-network reduction it might otherwise.
+network reduction it might otherwise (since it does not yet try to sort
+data matches -- a future version may improve this).
+
+This option is useful for transfer of large files with block-based changes
+or appended data, and also on systems that are disk bound, not network
+bound.
-This option is useful for transfer of large files with block-based change
-or appended data, and also on systems that are disk bound not network bound.
+The option implies --partial (since an interrupted transfer does not delete
+the file), but conflicts with --partial-dir, --compare-dest, --copy-dest, and
+--link-dest (a future rsync version will hopefully update the protocol to
+remove some of these restrictions).
WARNING: The file's data will be in an inconsistent state during the
transfer (and possibly afterward if the transfer gets interrupted), so you
files or directories. This is useful when mirroring very large trees
to prevent disasters.
-dit(bf(--delete)) This tells rsync to delete any files on the receiving
-side that aren't on the sending side. Files that are excluded from
-transfer are excluded from being deleted unless you use --delete-excluded.
+dit(bf(--max-size=SIZE)) This tells rsync to avoid transferring any
+file that is larger than the specified SIZE. The SIZE value can be
+suffixed with a letter to indicate a size multiplier (K, M, or G) and
+may be a fractional value (e.g. "--max-size=1.5m").
+
+dit(bf(--delete)) This tells rsync to delete extraneous files from the
+receiving side (ones that aren't on the sending side), but only for the
+directories that are being synchronized. You must have asked rsync to
+send the whole directory (e.g. "dir" or "dir/") without using a wildcard
+for the directory's contents (e.g. "dir/*") since the wildcard is expanded
+by the shell and rsync thus gets a request to transfer those files, not
+the files' parent directory. Files that are excluded from transfer are
+excluded from being deleted unless you use --delete-excluded.
This option has no effect if directory recursion is not selected.
This option can be dangerous if used incorrectly! It is a very good idea
-to run first using the dry run option (-n) to see what files would be
+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 I/O 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
sufficient space on the receiving filesystem. If you want to delete
after transferring, use the --delete-after switch. Implies --delete.
+One reason to use --delete-after is to avoid a delay before the start of
+the transfer (while the receiving side is scanned for deletions) as this
+delay might cause the transfer to timeout.
+
dit(bf(--ignore-errors)) Tells --delete to go ahead and delete files
even when there are I/O errors.
transferred on the receiving side. The default behavior is to create
the temporary files in the receiving directory.
-dit(bf(--compare-dest=DIR)) This option instructs rsync to use DIR on
-the destination machine as an additional directory to compare destination
-files against when doing transfers if the files are missing in the
-destination directory. This is useful for doing transfers to a new
-destination while leaving existing files intact, and then doing a
-flash-cutover when all files have been successfully transferred (for
-example by moving directories around and removing the old directory,
-although this skips files that haven't changed; see also --link-dest).
-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 (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 (which changes in a recursive transfer).
+dit(bf(--compare-dest=DIR)) This option instructs rsync to use em(DIR) on
+the destination machine as an additional hierarchy to compare destination
+files against doing transfers (if the files are missing in the destination
+directory). If a file is found in em(DIR) that is identical to the
+sender's file, the file will NOT be transferred to the destination
+directory. This is useful for creating a sparse backup of just files that
+have changed from an earlier backup.
+
+Beginning in version 2.6.4, multiple --compare-dest directories may be
+provided and rsync will search the list in the order specified until it
+finds an existing file. That first discovery is used as the basis file,
+and also determines if the transfer needs to happen.
+
+If em(DIR) is a relative path, it is relative to the destination directory.
+See also --copy-dest and --link-dest.
+
+dit(bf(--copy-dest=DIR)) This option behaves like bf(--compare-dest), but
+rsync will also copy unchanged files found in em(DIR) to the destination
+directory (using the data in the em(DIR) for an efficient copy). This is
+useful for doing transfers to a new destination while leaving existing
+files intact, and then doing a flash-cutover when all files have been
+successfully transferred.
+
+If em(DIR) is a relative path, it is relative to the destination directory.
+See also --compare-dest and --link-dest.
+
+dit(bf(--link-dest=DIR)) This option behaves like bf(--copy-dest), but
+unchanged files are hard linked from em(DIR) to the destination directory.
+The files must be identical in all preserved attributes (e.g. permissions,
+possibly ownership) in order for the files to be linked together.
An example:
verb(
rsync -av --link-dest=$PWD/prior_dir host:src_dir/ new_dir/
)
+Beginning with version 2.6.4, if more than one --link-dest option is
+specified, rsync will try to find an exact match to link with (searching
+the list in the order specified), and if not found, a basis file from one
+of the em(DIR)s will be selected to try to speed up the transfer.
+
+If em(DIR) is a relative path, it is relative to the destination directory.
+See also --compare-dest and --copy-dest.
+
+Note that rsync versions prior to 2.6.1 had a bug that could prevent
+--link-dest from working properly for a non-root user when -o was specified
+(or implied by -a). If the receiving rsync is not new enough, you can work
+around this bug by avoiding the -o option.
+
dit(bf(-z, --compress)) With this option, rsync compresses any data from
the files that it sends to the destination machine. This
option is useful on slow connections. The compression method used is the
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 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
-(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
-rsync server. The --address option allows you to specify a specific IP
-address (or hostname) to bind to. This makes virtual hosting possible
-in conjunction with the --config option.
-
-dit(bf(--config=FILE)) This specifies an alternate config file than
-the default. This is only relevant when --daemon is specified.
-The default is /etc/rsyncd.conf unless the daemon is running over
-a remote shell program and the remote user is not root; in that case
-the default is rsyncd.conf in the current directory (typically $HOME).
-
dit(bf(--port=PORT)) This specifies an alternate TCP port number to use
-rather than the default port 873.
+rather than the default of 873. This is only needed if you are using the
+double-colon (::) syntax to connect with an rsync daemon (since the URL
+syntax has a way to specify the port as a part of the URL). See also this
+option in the --daemon mode section.
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,
make a subsequent transfer of the rest of the file much faster.
dit(bf(--partial-dir=DIR)) Turns on --partial mode, but tells rsync to
-put a partially transferred file into DIR instead of writing out the
+put a partially transferred file into em(DIR) instead of writing out the
file to the destination dir. Rsync will also use a file found in this
dir as data to speed up the transfer (i.e. when you redo the send after
rsync creates a partial file) and delete such a file after it has served
-its purpose.
+its purpose. Note that if --whole-file is specified (or implied) that an
+existing partial-dir file will not be used to speedup the transfer (since
+rsync is sending files without using the incremental rsync algorithm).
Rsync will create the dir if it is missing (just the last dir -- not the
whole path). This makes it easy to use a relative path (such as
"--partial-dir=.rsync-partial") to have rsync create the partial-directory
-in the destination file's directory (rsync will also try to remove the DIR
+in the destination file's directory (rsync will also try to remove the em(DIR)
if a partial file was found to exist at the start of the transfer and the
DIR was specified as a relative path).
-If you are deleting files on the destination and your partial-dir is
-inside the destination hierarchy, make sure you specify an exclude to
-prevent the partial file from being deleted (it could get deleted at the
-end of the transfer when using --delete-after, or at the beginning of the
-transfer when using --delete). E.g. "--exclude=.rsync-partial/".
-
-IMPORTANT: the --partial-dir should not be writable by other users to
-avoid a security risk. E.g. AVOID "/tmp".
+If the partial-dir value is not an absolute path, rsync will also add an
+--exclude of this value at the end of all your existing excludes. This
+will prevent partial-dir files from being transferred and also prevent the
+untimely deletion of partial-dir items on the receiving side. An example:
+the above --partial-dir option would add an "--exclude=.rsync-partial/"
+rule at the end of any other include/exclude rules. Note that if you are
+supplying your own include/exclude rules, you may need to manually insert a
+rule for this directory exclusion somewhere higher up in the list so that
+it has a high enough priority to be effective (e.g., if your rules specify
+a trailing --exclude=* rule, the auto-added rule will be ineffective).
+
+IMPORTANT: the --partial-dir should not be writable by other users or it
+is a security risk. E.g. AVOID "/tmp".
+
+You can also set the partial-dir value the RSYNC_PARTIAL_DIR environment
+variable. Setting this in the environment does not force --partial to be
+enabled, but rather it effects where partial files go when --partial (or
+-P) is used. For instance, instead of specifying --partial-dir=.rsync-tmp
+along with --progress, you could set RSYNC_PARTIAL_DIR=.rsync-tmp in your
+environment and then just use the -P option to turn on the use of the
+.rsync-tmp dir for partial transfers. The only time the --partial option
+does not look for this environment value is when --inplace was also
+specified (since --inplace conflicts with --partial-dir).
dit(bf(--progress)) This option tells rsync to print information
showing the progress of the transfer. This gives a bored user
data over the wire and data being matched locally), and the estimated time
remaining in this transfer.
-After the a file is complete, it the data looks like this:
+After a file is complete, the data looks like this:
verb(
1238099 100% 146.38kB/s 0:00:08 (5, 57.1% of 396)
These additional numbers tell you how many files have been updated, and
what percent of the total number of files has been scanned.
-dit(bf(-P)) The -P option is equivalent to --partial --progress. I
-found myself typing that combination quite often so I created an
-option to make it easier.
+dit(bf(-P)) The -P option is equivalent to --partial --progress. Its
+purpose is to make it much easier to specify these two options for a long
+transfer that may be interrupted.
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
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).
+rsync daemon. See also these options in the --daemon mode section.
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
enddit()
+The options allowed when starting an rsync daemon are as follows:
+
+startdit()
+
+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
+(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(--address)) By default rsync will bind to the wildcard address
+when run as a daemon with the --daemon option or when connecting to a
+rsync server. The --address option allows you to specify a specific IP
+address (or hostname) to bind to. This makes virtual hosting possible
+in conjunction with the --config option. See also the "address" global
+option in the rsyncd.conf manpage.
+
+dit(bf(--bwlimit=KBPS)) This option allows you to specify a maximum
+transfer rate in kilobytes per second for the data the daemon sends.
+The client can still specify a smaller --bwlimit value, but their
+requested value will be rounded down if they try to exceed it. See the
+client version of this option (above) for some extra details.
+
+dit(bf(--config=FILE)) This specifies an alternate config file than
+the default. This is only relevant when --daemon is specified.
+The default is /etc/rsyncd.conf unless the daemon is running over
+a remote shell program and the remote user is not root; in that case
+the default is rsyncd.conf in the current directory (typically $HOME).
+
+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(--port=PORT)) This specifies an alternate TCP port number for the
+daemon to listen on rather than the default of 873. See also the "port"
+global option in the rsyncd.conf manpage.
+
+dit(bf(-4, --ipv4) or bf(-6, --ipv6)) Tells rsync to prefer IPv4/IPv6
+when creating the incoming sockets that the rsync daemon will use 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(-h, --help)) When specified after --daemon, print a short help
+page describing the options available for starting an rsync daemon.
+
+enddit()
+
manpagesection(EXCLUDE PATTERNS)
The exclude and include patterns specified to rsync allow for flexible
appears to be up-to-date already) or the file-update may be attempted
and then, if the file fails to verify, the update discarded with an
error. This means that it should be safe to re-run a read-batch operation
-if the command got updated. If you wish to force the batched-update to
+if the command got interrupted. If you wish to force the batched-update to
always be attempted regardless of the file's size and date, use the -I
-option. If an error occurs, the destination tree will probably be in a
+option (when reading the batch).
+If an error occurs, the destination tree will probably be 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 must be at least as new as the
-one used to generate the batch file.
+one used to generate the batch file. Rsync will die with an error if the
+protocol version in the batch file is too new for the batch-reading rsync
+to handle.
The --dry-run (-n) option does not work in batch mode and yields a runtime
error.
user can ignore this detail and just use the shell script as an easy way
to run the appropriate --read-batch command for the batched data.
-See bf(http://www.ils.unc.edu/i2dsi/unc_rsync+.html) for papers and technical
-reports.
+The original batch mode in rsync was based on "rsync+", but the latest
+version uses a new implementation.
manpagesection(SYMBOLIC LINKS)
Matt McCutchen's Web Site / rsync / rsync.git / blobdiff