rsync(1)   23 Sep 2011

NAME

rsync - a fast, versatile, remote (and local) file-copying tool

SYNOPSIS

.PP

.nf

Local: rsync [OPTION...] SRC... [DEST]

Access via remote shell: Pull: rsync [OPTION...] [[email protected]]HOST:SRC... [DEST] Push: rsync [OPTION...] SRC... [[email protected]]HOST:DEST

Access via rsync daemon: Pull: rsync [OPTION...] [[email protected]]HOST::SRC... [DEST] rsync [OPTION...] rsync://[[email protected]]HOST[:PORT]/SRC... [DEST] Push: rsync [OPTION...] SRC... [[email protected]]HOST::DEST rsync [OPTION...] SRC... rsync://[[email protected]]HOST[:PORT]/DEST

.fi

.PP

Usages with just one SRC arg and no DEST arg will list the source files instead of copying.

.PP

DESCRIPTION

.PP

Rsync is a fast and extraordinarily versatile file copying tool. It can copy locally, to/from another host over any remote shell, or to/from a remote rsync daemon. It offers a large number of options that control every aspect of its behavior and permit very flexible specification of the set of files to be copied. It is famous for its delta-transfer algorithm, which reduces the amount of data sent over the network by sending only the differences between the source files and the existing files in the destination. Rsync is widely used for backups and mirroring and as an improved copy command for everyday use.

.PP

Rsync finds files that need to be transferred using a dqquick checkdq algorithm (by default) that looks for files that have changed in size or in last-modified time. Any changes in the other preserved attributes (as requested by options) are made on the destination file directly when the quick check indicates that the filecqs data does not need to be updated.

.PP

Some of the additional features of rsync are:

.PP

GENERAL

.PP

Rsync copies files either to or from a remote host, or locally on the current host (it does not support copying files between two remote hosts).

.PP

There are two different ways for rsync to contact a remote system: using a remote-shell program as the transport (such as ssh or rsh) or contacting an rsync daemon directly via TCP. The remote-shell transport is used whenever the source or destination path contains a single colon (:) separator after a host specification. Contacting an rsync daemon directly happens when the source or destination path contains a double colon (::) separator after a host specification, OR when an rsync:// URL is specified (see also the dqUSING RSYNC-DAEMON FEATURES VIA A REMOTE-SHELL CONNECTIONdq section for an exception to this latter rule).

.PP

As a special case, if a single source arg is specified without a destination, the files are listed in an output format similar to dqls -ldq.

.PP

As expected, if neither the source or destination path specify a remote host, the copy occurs locally (see also the --list-only option).

.PP

Rsync refers to the local side as the dqclientdq and the remote side as the dqserverdq. Doncqt confuse dqserverdq with an rsync daemon -- a daemon is always a server, but a server can be either a daemon or a remote-shell spawned process.

.PP

SETUP

.PP

See the file README for installation instructions.

.PP

Once installed, you can use rsync to any machine that you can access via a remote shell (as well as some that you can access using the rsync daemon-mode protocol). For remote transfers, a modern rsync uses ssh for its communications, but it may have been configured to use a different remote shell by default, such as rsh or remsh.

.PP

You can also specify any remote shell you like, either by using the -e command line option, or by setting the RSYNC_RSH environment variable.

.PP

Note that rsync must be installed on both the source and destination machines.

.PP

USAGE

.PP

You use rsync in the same way you use rcp. You must specify a source and a destination, one of which may be remote.

.PP

Perhaps the best way to explain the syntax is with some examples:

.PP

CWrsync -t *.c foo:src/

.PP

This would transfer all files matching the pattern *.c from the current directory to the directory src on the machine foo. If any of the files already exist on the remote system then the rsync remote-update protocol is used to update the file by sending only the differences. See the tech report for details.

.PP

CWrsync -avz foo:src/bar /data/tmp

.PP

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 dqarchivedq mode, which ensures that symbolic 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.

.PP

CWrsync -avz foo:src/bar/ /data/tmp

.PP

A trailing slash on the source changes this behavior to avoid creating an additional directory level at the destination. You can think of a trailing / on a source as meaning dqcopy the contents of this directorydq as opposed to dqcopy the directory by namedq, but in both cases the attributes of the containing directory are transferred to the containing directory on the destination. In other words, each of the following commands copies the files in the same way, including their setting of the attributes of /dest/foo:

.PP

CWrsync -av /src/foo /dest
CWrsync -av /src/foo/ /dest/foo

.PP

Note also that host and module references doncqt require a trailing slash to copy the contents of the default directory. For example, both of these copy the remote directorycqs contents into dq/destdq:

.PP

CWrsync -av host: /dest
CWrsync -av host::module /dest

.PP

You can also use rsync in local-only mode, where both the source and destination doncqt have a cq:cq in the name. In this case it behaves like an improved copy command.

.PP

Finally, you can list all the (listable) modules available from a particular rsync daemon by leaving off the module name:

.PP

CWrsync somehost.mydomain.com::

.PP

See the following section for more details.

.PP

ADVANCED USAGE

.PP

The syntax for requesting multiple files from a remote host is done by specifying additional remote-host args in the same style as the first, or with the hostname omitted. For instance, all these work:

.PP

CWrsync -av host:file1 :file2 host:file{3,4} /dest/
CWrsync -av host::modname/file{1,2} host::modname/file3 /dest/
CWrsync -av host::modname/file1 ::modname/file{3,4}

.PP

Older versions of rsync required using quoted spaces in the SRC, like these examples:

.PP

CWrsync -av host:'dir1/file1 dir2/file2' /dest
CWrsync host::'modname/dir1/file1 modname/dir2/file2' /dest

.PP

This word-splitting still works (by default) in the latest rsync, but is not as easy to use as the first method.

.PP

If you need to transfer a filename that contains whitespace, you can either specify the --protect-args (-s) option, or youcqll need to escape the whitespace in a way that the remote shell will understand. For instance:

.PP

CWrsync -av host:'filee namee withe spaces' /dest

.PP

CONNECTING TO AN RSYNC DAEMON

.PP

It is also possible to use rsync without a remote shell as the transport. In this case you will directly connect to a remote rsync daemon, typically using TCP port 873. (This obviously requires the daemon to be running on the remote system, so refer to the STARTING AN RSYNC DAEMON TO ACCEPT CONNECTIONS section below for information on that.)

.PP

Using rsync in this way is the same as using it with a remote shell except that:

.PP

USING RSYNC\-DAEMON FEATURES VIA A REMOTE\-SHELL CONNECTION

.PP

It is sometimes useful to use various features of an rsync daemon (such as named modules) without actually allowing any new socket connections into a system (other than what is already required to allow remote-shell access). Rsync supports connecting to a host using a remote shell and then spawning a single-use dqdaemondq server that expects to read its config file in the home dir of the remote user. This can be useful if you want to encrypt a daemon-style transfercqs data, but since the daemon is started up fresh by the remote user, you may not be able to use features such as chroot or change the uid used by the daemon. (For another way to encrypt a daemon transfer, consider using ssh to tunnel a local port to a remote machine and configure a normal rsync daemon on that remote host to only allow connections from dqlocalhostdq.)

.PP

From the usercqs perspective, a daemon transfer via a remote-shell connection uses nearly the same command-line syntax as a normal rsync-daemon transfer, with the only exception being that you must explicitly set the remote shell program on the command-line with the --rsh=COMMAND option. (Setting the RSYNC_RSH in the environment will not turn on this functionality.) For example:

.PP

.nf

rsync -av --rsh=ssh host::module /dest

.fi

.PP

If you need to specify a different remote-shell user, keep in mind that the [email protected] prefix in front of the host is specifying the rsync-user value (for a module that requires user-based authentication). This means that you must give the cq-l usercq option to ssh when specifying the remote-shell, as in this example that uses the short version of the --rsh option:

.PP

.nf

rsync -av -e dqssh -l ssh-userdq [email protected]::module /dest

.fi

.PP

The dqssh-userdq will be used at the ssh level; the dqrsync-userdq will be used to log-in to the dqmoduledq.

.PP

STARTING AN RSYNC DAEMON TO ACCEPT CONNECTIONS

.PP

In order to connect to an rsync daemon, the remote system needs to have a daemon already running (or it needs to have configured something like inetd to spawn an rsync daemon for incoming connections on a particular port). For full information on how to start a daemon that will handling incoming socket connections, see the rsyncd.conf(5) man page -- that is the config file for the daemon, and it contains the full details for how to run the daemon (including stand-alone and inetd configurations).

.PP

If youcqre using one of the remote-shell transports for the transfer, there is no need to manually start an rsync daemon.

.PP

SORTED TRANSFER ORDER

.PP

Rsync always sorts the specified filenames into its internal transfer list. This handles the merging together of the contents of identically named directories, makes it easy to remove duplicate filenames, and may confuse someone when the files are transferred in a different order than what was given on the command-line.

.PP

If you need a particular file to be transferred prior to another, either separate the files into different rsync calls, or consider using --delay-updates (which doesncqt affect the sorted transfer order, but does make the final file-updating phase happen much more rapidly).

.PP

EXAMPLES

.PP

Here are some examples of how I use rsync.

.PP

To backup my wifecqs home directory, which consists of large MS Word files and mail folders, I use a cron job that runs

.PP

CWrsync -Cavz . arvidsjaur:backup

.PP

each night over a PPP connection to a duplicate directory on my machine dqarvidsjaurdq.

.PP

To synchronize my samba source trees I use the following Makefile targets:

.PP

.nf

get: rsync -avuzb --exclude '*~' samba:samba/ . put: rsync -Cavuzb . samba:samba/ sync: get put

.fi

.PP

this allows me to sync with a CVS directory at the other end of the connection. I then do CVS operations on the remote machine, which saves a lot of time as the remote CVS protocol isncqt very efficient.

.PP

I mirror a directory between my dqolddq and dqnewdq ftp sites with the command:

.PP

CWrsync -az -e ssh --delete ~ftp/pub/samba nimbus:dq~ftp/pub/tridgedq

.PP

This is launched from cron every few hours.

.PP

OPTIONS SUMMARY

.PP

Here is a short summary of the options available in rsync. Please refer to the detailed description below for a complete description.

.nf

-v, --verbose increase verbosity -q, --quiet suppress non-error messages --no-motd suppress daemon-mode MOTD (see caveat) -c, --checksum skip based on checksum, not mod-time & size -a, --archive archive mode; equals -rlptgoD (no -H,-A,-X) --no-OPTION turn off an implied OPTION (e.g. --no-D) -r, --recursive recurse into directories -R, --relative use relative path names --no-implied-dirs don't send implied dirs with --relative -b, --backup make backups (see --suffix & --backup-dir) --backup-dir=DIR make backups into hierarchy based in DIR --suffix=SUFFIX backup suffix (default ~ w/o --backup-dir) -u, --update skip files that are newer on the receiver --inplace update destination files in-place --append append data onto shorter files --append-verify --append w/old data in file checksum -d, --dirs transfer directories without recursing -l, --links copy symlinks as symlinks -L, --copy-links transform symlink into referent file/dir --copy-unsafe-links only dqunsafedq symlinks are transformed --safe-links ignore symlinks that point outside the tree -k, --copy-dirlinks transform symlink to dir into referent dir -K, --keep-dirlinks treat symlinked dir on receiver as dir -H, --hard-links preserve hard links -p, --perms preserve permissions -E, --executability preserve executability --chmod=CHMOD affect file and/or directory permissions -A, --acls preserve ACLs (implies -p) -X, --xattrs preserve extended attributes -o, --owner preserve owner (super-user only) -g, --group preserve group --devices preserve device files (super-user only) --specials preserve special files -D same as --devices --specials -t, --times preserve modification times -O, --omit-dir-times omit directories from --times --super receiver attempts super-user activities --fake-super store/recover privileged attrs using xattrs -S, --sparse handle sparse files efficiently -n, --dry-run perform a trial run with no changes made -W, --whole-file copy files whole (w/o delta-xfer algorithm) -x, --one-file-system don't cross filesystem boundaries -B, --block-size=SIZE force a fixed checksum block-size -e, --rsh=COMMAND specify the remote shell to use --rsync-path=PROGRAM specify the rsync to run on remote machine --existing skip creating new files on receiver --ignore-existing skip updating files that exist on receiver --remove-source-files sender removes synchronized files (non-dir) --del an alias for --delete-during --delete delete extraneous files from dest dirs --delete-before receiver deletes before xfer, not during --delete-during receiver deletes during the transfer --delete-delay find deletions during, delete after --delete-after receiver deletes after transfer, not during --delete-excluded also delete excluded files from dest dirs --ignore-errors delete even if there are I/O errors --force force deletion of dirs even if not empty --max-delete=NUM don't delete more than NUM files --max-size=SIZE don't transfer any file larger than SIZE --min-size=SIZE don't transfer any file smaller than SIZE --partial keep partially transferred files --partial-dir=DIR put a partially transferred file into DIR --delay-updates put all updated files into place at end -m, --prune-empty-dirs prune empty directory chains from file-list --numeric-ids don't map uid/gid values by user/group name --timeout=SECONDS set I/O timeout in seconds --contimeout=SECONDS set daemon connection timeout in seconds -I, --ignore-times don't skip files that match size and time --size-only skip files that match in size --modify-window=NUM compare mod-times with reduced accuracy -T, --temp-dir=DIR create temporary files in directory DIR -y, --fuzzy find similar file for basis if no dest file --compare-dest=DIR also compare received files relative to DIR --copy-dest=DIR ... and include copies of unchanged files --link-dest=DIR hardlink to files in DIR when unchanged -z, --compress compress file data during the transfer --compress-level=NUM explicitly set compression level --skip-compress=LIST skip compressing files with suffix in LIST -C, --cvs-exclude auto-ignore files in the same way CVS does -f, --filter=RULE add a file-filtering RULE -F same as --filter='dir-merge /.rsync-filter' repeated: --filter='- .rsync-filter' --exclude=PATTERN exclude files matching PATTERN --exclude-from=FILE read exclude patterns from FILE --include=PATTERN don't exclude files matching PATTERN --include-from=FILE read include patterns from FILE --files-from=FILE read list of source-file names from FILE -0, --from0 all *from/filter files are delimited by 0s -s, --protect-args no space-splitting; wildcard chars only --address=ADDRESS bind address for outgoing socket to daemon --port=PORT specify double-colon alternate port number --sockopts=OPTIONS specify custom TCP options --blocking-io use blocking I/O for the remote shell --stats give some file-transfer stats -8, --8-bit-output leave high-bit chars unescaped in output -h, --human-readable output numbers in a human-readable format --progress show progress during transfer -P same as --partial --progress -i, --itemize-changes output a change-summary for all updates --out-format=FORMAT output updates using the specified FORMAT --log-file=FILE log what we're doing to the specified FILE --log-file-format=FMT log updates using the specified FMT --password-file=FILE read daemon-access password from FILE --list-only list the files instead of copying them --bwlimit=KBPS limit I/O bandwidth; KBytes per second --write-batch=FILE write a batched update to FILE --only-write-batch=FILE like --write-batch but w/o updating dest --read-batch=FILE read a batched update from FILE --protocol=NUM force an older protocol version to be used --iconv=CONVERT_SPEC request charset conversion of filenames --checksum-seed=NUM set block/file checksum seed (advanced) -4, --ipv4 prefer IPv4 -6, --ipv6 prefer IPv6 --version print version number (-h) --help show this help (see below for -h comment)

.fi

.PP

Rsync can also be run as a daemon, in which case the following options are accepted:

.nf

--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 --log-file=FILE override the dqlog filedq setting --log-file-format=FMT override the dqlog formatdq setting --sockopts=OPTIONS specify custom TCP options -v, --verbose increase verbosity -4, --ipv4 prefer IPv4 -6, --ipv6 prefer IPv6 -h, --help show this help (if used after --daemon)

.fi

.PP

OPTIONS

.PP

Rsync accepts both long (double-dash + word) and short (single-dash + letter) options. The full list of the available options are described below. If an option can be specified in more than one way, the choices are comma-separated. Some options only have a long variant, not a short. If the option takes a parameter, the parameter is only listed after the long variant, even though it must also be specified for the short. When specifying a parameter, you can either use the form --option=param or replace the cq=cq with whitespace. The parameter may need to be quoted in some manner for it to survive the shellcqs command-line parsing. Keep in mind that a leading tilde (~) in a filename is substituted by your shell, so --option=~/foo will not change the tilde into your home directory (remove the cq=cq for that).

.PP

DAEMON OPTIONS

.PP

The options allowed when starting an rsync daemon are as follows:

.PP

FILTER RULES

.PP

The filter rules allow for flexible selection of which files to transfer (include) and which files to skip (exclude). The rules either directly specify include/exclude patterns or they specify a way to acquire more include/exclude patterns (e.g. to read them from a file).

.PP

As the list of files/directories to transfer is built, rsync checks each name to be transferred against the list of include/exclude patterns in turn, and the first matching pattern is acted on: if it is an exclude pattern, then that file is skipped; if it is an include pattern then that filename is not skipped; if no matching pattern is found, then the filename is not skipped.

.PP

Rsync builds an ordered list of filter rules as specified on the command-line. Filter rules have the following syntax:

.PP

CWRULE [PATTERN_OR_FILENAME]
CWRULE,MODIFIERS [PATTERN_OR_FILENAME]

.PP

You have your choice of using either short or long RULE names, as described below. If you use a short-named rule, the cq,cq separating the RULE from the MODIFIERS is optional. The PATTERN or FILENAME that follows (when present) must come after either a single space or an underscore (_). Here are the available rule prefixes:

.PP

exclude, - specifies an exclude pattern.
include, + specifies an include pattern.
merge, . specifies a merge-file to read for more rules.
dir-merge, : specifies a per-directory merge-file.
hide, H specifies a pattern for hiding files from the transfer.
show, S files that match the pattern are not hidden.
protect, P specifies a pattern for protecting files from deletion.
risk, R files that match the pattern are not protected.
clear, ! clears the current include/exclude list (takes no arg)

.PP

When rules are being read from a file, empty lines are ignored, as are comment lines that start with a dq#dq.

.PP

Note that the --include/--exclude command-line options do not allow the full range of rule parsing as described above -- they only allow the specification of include/exclude patterns plus a dq!dq token to clear the list (and the normal comment parsing when rules are read from a file). If a pattern does not begin with dq- dq (dash, space) or dq+ dq (plus, space), then the rule will be interpreted as if dq+ dq (for an include option) or dq- dq (for an exclude option) were prefixed to the string. A --filter option, on the other hand, must always contain either a short or long rule name at the start of the rule.

.PP

Note also that the --filter, --include, and --exclude options take one rule/pattern each. To add multiple ones, you can repeat the options on the command-line, use the merge-file syntax of the --filter option, or the --include-from/--exclude-from options.

.PP

INCLUDE/EXCLUDE PATTERN RULES

.PP

You can include and exclude files by specifying patterns using the dq+dq, dq-dq, etc. filter rules (as introduced in the FILTER RULES section above). The include/exclude rules each specify a pattern that is matched against the names of the files that are going to be transferred. These patterns can take several forms:

.PP

MERGE\-FILE FILTER RULES

.PP

You can merge whole files into your filter rules by specifying either a merge (.) or a dir-merge (:) filter rule (as introduced in the FILTER RULES section above).

.PP

There are two kinds of merged files -- single-instance (cq.cq) and per-directory (cq:cq). A single-instance merge file is read one time, and its rules are incorporated into the filter list in the place of the dq.dq rule. For per-directory merge files, rsync will scan every directory that it traverses for the named file, merging its contents when the file exists into the current list of inherited rules. These per-directory rule files must be created on the sending side because it is the sending side that is being scanned for the available files to transfer. These rule files may also need to be transferred to the receiving side if you want them to affect what files doncqt get deleted (see PER-DIRECTORY RULES AND DELETE below).

.PP

Some examples:

.PP

CWmerge /etc/rsync/default.rules
CW. /etc/rsync/default.rules
CWdir-merge .per-dir-filter
CWdir-merge,n- .non-inherited-per-dir-excludes
CW:n- .non-inherited-per-dir-excludes

.PP

The following modifiers are accepted after a merge or dir-merge rule:

.PP

LIST\-CLEARING FILTER RULE

.PP

You can clear the current include/exclude list by using the dq!dq filter rule (as introduced in the FILTER RULES section above). The dqcurrentdq list is either the global list of rules (if the rule is encountered while parsing the filter options) or a set of per-directory rules (which are inherited in their own sub-list, so a subdirectory can use this to clear out the parentcqs rules).

.PP

ANCHORING INCLUDE/EXCLUDE PATTERNS

.PP

As mentioned earlier, global include/exclude patterns are anchored at the dqroot of the transferdq (as opposed to per-directory patterns, which are anchored at the merge-filecqs directory). If you think of the transfer as a subtree of names that are being sent from sender to receiver, the transfer-root is where the tree starts to be duplicated in the destination directory. This root governs where patterns that start with a / match.

.PP

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 host). The following examples demonstrate this.

.PP

Letcqs say that we want to match two source files, one with an absolute path of dq/home/me/foo/bardq, and one with a path of dq/home/you/bar/bazdq. Here is how the various command choices differ for a 2-source transfer:

.PP

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

.PP

Example cmd: rsync -a /home/me/ /home/you/ /dest
+/- pattern: /foo/bar (note missing dqmedq)
+/- pattern: /bar/baz (note missing dqyoudq)
Target file: /dest/foo/bar
Target file: /dest/bar/baz

.PP

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

.PP

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

.PP

The easiest way to see what name you should filter is to just look at the output when using --verbose and put a / in front of the name (use the --dry-run option if youcqre not yet ready to copy any files).

.PP

PER\-DIRECTORY RULES AND DELETE

.PP

Without a delete option, per-directory rules are only relevant on the sending side, so you can feel free to exclude the merge files themselves without affecting the transfer. To make this easy, the cqecq modifier adds this exclude for you, as seen in these two equivalent commands:

.PP

CWrsync -av --filter=': .excl' --exclude=.excl host:src/dir /dest
CWrsync -av --filter=':e .excl' host:src/dir /dest

.PP

However, if you want to do a delete on the receiving side AND you want some files to be excluded from being deleted, youcqll need to be sure that the receiving side knows what files to exclude. The easiest way is to include the per-directory merge files in the transfer and use --delete-after, because this ensures that the receiving side gets all the same exclude rules as the sending side before it tries to delete anything:

.PP

CWrsync -avF --delete-after host:src/dir /dest

.PP

However, if the merge files are not a part of the transfer, youcqll need to either specify some global exclude rules (i.e. specified on the command line), or youcqll need to maintain your own per-directory merge files on the receiving side. An example of the first is this (assume that the remote .rules files exclude themselves):

.PP

.nf

rsync -av --filter=cq: .rulescq --filter=cq. /my/extra.rulescq --delete host:src/dir /dest

.fi

.PP

In the above example the extra.rules file can affect both sides of the transfer, but (on the sending side) the rules are subservient to the rules merged from the .rules files because they were specified after the per-directory merge rule.

.PP

In one final example, the remote side is excluding the .rsync-filter files from the transfer, but we want to use our own .rsync-filter files to control what gets deleted on the receiving side. To do this we must specifically exclude the per-directory merge files (so that they doncqt get deleted) and then put rules into the local files to control what else should not get deleted. Like one of these commands:

.PP

.nf

rsync -av --filter=':e /.rsync-filter' --delete e host:src/dir /dest rsync -avFF --delete host:src/dir /dest

.fi

.PP

BATCH MODE

.PP

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 number of hosts. Now suppose some changes have been made to this source tree and those changes need to be propagated to the other 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 in a dqbatch filedq all the information needed to repeat this operation against other, identical destination trees.

.PP

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.

.PP

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.

.PP

For your convenience, a script file is also created when the write-batch option is used: it will be named the same as the batch file with dq.shdq appended. This script file contains a command-line suitable for updating a destination tree using the associated batch file. It can be executed using a Bourne (or Bourne-like) shell, optionally passing in an alternate destination tree pathname which is then used instead of the original destination path. This is useful when the destination tree path on the current host differs from the one used to create the batch file.

.PP

Examples:

.PP

CW$ rsync --write-batch=foo -a host:/source/dir/ /adest/dir/
CW$ scp foo* remote:
CW$ ssh remote ./foo.sh /bdest/dir/

.PP

CW$ rsync --write-batch=foo -a /source/dir/ /adest/dir/
CW$ ssh remote rsync --read-batch=- -a /bdest/dir/

.PP

In these examples, rsync is used to update /adest/dir/ from /source/dir/ and the information to repeat this operation is stored in dqfoodq and dqfoo.shdq. The host dqremotedq is then updated with the batched data going into the directory /bdest/dir. The differences between the two examples reveals some of the flexibility you have in how you deal with batches:

.PP

DIAGNOSTICS

.PP

rsync occasionally produces error messages that may seem a little cryptic. The one that seems to cause the most confusion is dqprotocol version mismatch -- is your shell clean?dq.

.PP

This message is usually caused by your startup scripts or remote shell facility producing unwanted garbage on the stream that rsync is using for its transport. The way to diagnose this problem is to run your remote shell like this:

.PP

CWssh remotehost /bin/true > out.dat

.PP

then look at out.dat. If everything is working correctly then out.dat should be a zero length file. If you are getting the above error from rsync then you will probably find that out.dat contains some text or data. Look at the contents and try to work out what is producing it. The most common cause is incorrectly configured shell startup scripts (such as .cshrc or .profile) that contain output statements for non-interactive logins.

.PP

If you are having trouble debugging filter patterns, then try specifying the -vv option. At this level of verbosity rsync will show why each individual file is included or excluded.

.PP

EXIT VALUES

.PP

ENVIRONMENT VARIABLES

.PP

FILES

.PP

/etc/rsyncd.conf or rsyncd.conf

.PP

SEE ALSO

.PP

rsyncd.conf(5)

.PP

BUGS

.PP

times are transferred as *nix time_t values

.PP

When transferring to FAT filesystems rsync may re-sync unmodified files. See the comments on the --modify-window option.

.PP

file permissions, devices, etc. are transferred as native numerical values

.PP

see also the comments on the --delete option

.PP

Please report bugs! See the web site at http://rsync.samba.org/

.PP

VERSION

.PP

This man page is current for version 3.0.9 of rsync.

.PP

INTERNAL OPTIONS

.PP

The options --server and --sender are used internally by rsync, and should never be typed by a user under normal circumstances. Some awareness of these options may be needed in certain scenarios, such as when setting up a login that can only run an rsync command. For instance, the support directory of the rsync distribution has an example script named rrsync (for restricted rsync) that can be used with a restricted ssh login.

.PP

CREDITS

.PP

rsync is distributed under the GNU General Public License. See the file COPYING for details.

.PP

A WEB site is available at http://rsync.samba.org/. The site includes an FAQ-O-Matic which may cover questions unanswered by this manual page.

.PP

The primary ftp site for rsync is ftp://rsync.samba.org/pub/rsync.

.PP

We would be delighted to hear from you if you like this program. Please contact the mailing-list at [email protected]

.PP

This program uses the excellent zlib compression library written by Jean-loup Gailly and Mark Adler.

.PP

THANKS

.PP

Special thanks go out to: John Van Essen, Matt McCutchen, Wesley W. Terpstra, David Dykstra, Jos Backus, Sebastian Krahmer, Martin Pool, and our gone-but-not-forgotten compadre, J.W. Schultz.

.PP

Thanks also to Richard Brent, Brendan Mackay, Bill Waite, Stephen Rothwell and David Bell. Icqve probably missed some people, my apologies if I have.

.PP

AUTHOR

.PP

rsync was originally written by Andrew Tridgell and Paul Mackerras. Many people have later contributed to it. It is currently maintained by Wayne Davison.

.PP

Mailing lists for support and development are available at http://lists.samba.org