rsync - Unix, Linux Command

rsync [OPTION]... SRC [SRC]... DEST


rsync [OPTION]... SRC [SRC]... [USER@]HOST:DEST


rsync [OPTION]... SRC [SRC]... [USER@]HOST::DEST


rsync [OPTION]... SRC [SRC]... rsync://[USER@]HOST[:PORT]/DEST


rsync [OPTION]... SRC


rsync [OPTION]... [USER@]HOST:SRC [DEST]


rsync [OPTION]... [USER@]HOST::SRC [DEST]


rsync [OPTION]... rsync://[USER@]HOST[:PORT]/SRC [DEST]




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 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
an efficient checksum-search algorithm described in the technical
report that accompanies this package.


Some of the additional features of rsync are:




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).


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
"USING RSYNC-DAEMON FEATURES VIA A REMOTE-SHELL CONNECTION" section for
an exception to this latter rule).


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


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




See the file README for installation instructions.


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.


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.


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




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


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


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
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.


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


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
in the transfer.  Additionally, compression will be used to reduce the
size of data portions of the transfer.


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


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 "copy the contents of this directory" as opposed
to "copy the directory by name", 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:


rsync -av /src/foo /dest

rsync -av /src/foo/ /dest/foo


Note also that host and module references don’t require a trailing slash to
copy the contents of the default directory.  For example, both of these
copy the remote directory’s contents into "/dest":


rsync -av host: /dest

rsync -av host::module /dest


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
an improved copy command.


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


rsync somehost.mydomain.com::


See the following section for more details.




The syntax for requesting multiple files from a remote host involves using
quoted spaces in the SRC.  Some examples:


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.


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:


rsync -av host:’file\ name\ with\ spaces’ /dest

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.




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.)


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








    rsync -av host::src /dest


    rsync -av host::src /dest






Some modules on the remote daemon may require authentication. If so,
you will receive a password prompt when you connect. You can avoid the
password prompt by setting the environment variable RSYNC_PASSWORD to
the password you want to use or using the --password-file option. This
may be useful when scripting rsync.


WARNING: On some systems environment variables are visible to all
users. On those systems using --password-file is recommended.


You may establish the connection via a web proxy by setting the
environment variable RSYNC_PROXY to a hostname:port pair pointing to
your web proxy.  Note that your web proxy’s configuration must support
proxy connections to port 873.




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 "daemon" 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 transfer’s 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 "localhost".)


From the user’s 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:






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


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






If you need to specify a different remote-shell user, keep in mind that the
user@ 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 ’-l user’ option to ssh when specifying the remote-shell, as in
this example that uses the short version of the --rsh option:






    rsync -av -e "ssh -l ssh-user" rsync-user@host::module /dest


    rsync -av -e "ssh -l ssh-user" rsync-user@host::module /dest






The "ssh-user" will be used at the ssh level; the "rsync-user" will be
used to log-in to the "module".




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).


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




Here are some examples of how I use rsync.


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


rsync -Cavz . arvidsjaur:backup


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


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






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


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






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 isn’t very efficient.


I mirror a directory between my "old" and "new" ftp sites with the
command:


rsync -az -e ssh --delete ~ftp/pub/samba nimbus:"~ftp/pub/tridge"


This is launched from cron every few hours.




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



 -v, --verbose               increase verbosity
 -q, --quiet                 suppress non-error messages
 -c, --checksum              skip based on checksum, not mod-time & size
 -a, --archive               archive mode; same as -rlptgoD (no -H)
     --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
 -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 "unsafe" 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
 -A, --acls                  preserve ACLs (implies -p) [non-standard]
 -X, --xattrs                preserve extended attrs (implies -p) [n.s.]
     --chmod=CHMOD           change destination permissions
 -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 times
 -O, --omit-dir-times        omit directories when preserving times
     --super                 receiver attempts super-user activities
 -S, --sparse                handle sparse files efficiently
 -n, --dry-run               show what would have been transferred
 -W, --whole-file            copy files whole (without rsync 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              ignore non-existing files on receiving side
     --ignore-existing       ignore files that already exist on receiver
     --remove-sent-files     sent files/symlinks are removed from sender
     --del                   an alias for --delete-during
     --delete                delete files that don’t exist on sender
     --delete-before         receiver deletes before transfer (default)
     --delete-during         receiver deletes during xfer, not before
     --delete-after          receiver deletes after transfer, not before
     --delete-excluded       also delete excluded files on receiver
     --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=TIME          set I/O 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
 -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
     --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
     --log-format=FORMAT     output filenames using the specified format
     --password-file=FILE    read 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
     --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)





 -v, --verbose               increase verbosity
 -q, --quiet                 suppress non-error messages
 -c, --checksum              skip based on checksum, not mod-time & size
 -a, --archive               archive mode; same as -rlptgoD (no -H)
     --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
 -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 "unsafe" 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
 -A, --acls                  preserve ACLs (implies -p) [non-standard]
 -X, --xattrs                preserve extended attrs (implies -p) [n.s.]
     --chmod=CHMOD           change destination permissions
 -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 times
 -O, --omit-dir-times        omit directories when preserving times
     --super                 receiver attempts super-user activities
 -S, --sparse                handle sparse files efficiently
 -n, --dry-run               show what would have been transferred
 -W, --whole-file            copy files whole (without rsync 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              ignore non-existing files on receiving side
     --ignore-existing       ignore files that already exist on receiver
     --remove-sent-files     sent files/symlinks are removed from sender
     --del                   an alias for --delete-during
     --delete                delete files that don’t exist on sender
     --delete-before         receiver deletes before transfer (default)
     --delete-during         receiver deletes during xfer, not before
     --delete-after          receiver deletes after transfer, not before
     --delete-excluded       also delete excluded files on receiver
     --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=TIME          set I/O 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
 -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
     --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
     --log-format=FORMAT     output filenames using the specified format
     --password-file=FILE    read 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
     --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)








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



     --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
     --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)





     --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
     --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)










rsync uses the GNU long options package. Many of the command line
options have two variants, one short and one long.  These are shown
below, separated by commas. Some options only have a long variant.
The ’=’ for options that take a parameter is optional; whitespace
can be used instead.






      782448  63%  110.64kB/s    0:00:04


      782448  63%  110.64kB/s    0:00:04








     1238099 100%  146.38kB/s    0:00:08  (5, 57.1% of 396)


     1238099 100%  146.38kB/s    0:00:08  (5, 57.1% of 396)








    rsync -av --list-only foo* dest/


    rsync -av --list-only foo* dest/






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




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).


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.


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


RULE [PATTERN_OR_FILENAME]

RULE,MODIFIERS [PATTERN_OR_FILENAME]


You have your choice of using either short or long RULE names, as described
below.  If you use a short-named rule, the ’,’ 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:


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)


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


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 "!" token to clear the
list (and the normal comment parsing when rules are read from a file).
If a pattern
does not begin with "- " (dash, space) or "+ " (plus, space), then the
rule will be interpreted as if "+ " (for an include option) or "- " (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.


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.




You can include and exclude files by specifying patterns using the "+",
"-", 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:








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).


There are two kinds of merged files -- single-instance (’.’) and
per-directory (’:’).  A single-instance merge file is read one time, and
its rules are incorporated into the filter list in the place of the "."
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 don’t get deleted (see PER-DIRECTORY RULES AND DELETE
below).


Some examples:


merge /etc/rsync/default.rules

. /etc/rsync/default.rules

dir-merge .per-dir-filter

dir-merge,n- .non-inherited-per-dir-excludes

:n- .non-inherited-per-dir-excludes


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














You can clear the current include/exclude list by using the "!" filter
rule (as introduced in the FILTER RULES section above).  The "current"
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 parent’s rules).




As mentioned earlier, global include/exclude patterns are anchored at the
"root of the transfer" (as opposed to per-directory patterns, which are
anchored at the merge-file’s 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.


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.


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:


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 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 you’re not yet ready to copy any files).




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 ’e’ modifier adds
this exclude for you, as seen in these two equivalent commands:


rsync -av --filter=’: .excl’ --exclude=.excl host:src/dir /dest

rsync -av --filter=’:e .excl’ host:src/dir /dest


However, if you want to do a delete on the receiving side AND you want some
files to be excluded from being deleted, you’ll 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:


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


However, if the merge files are not a part of the transfer, you’ll need to
either specify some global exclude rules (i.e. specified on the command
line), or you’ll 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):






rsync -av --filter=’: .rules’ --filter=’. /my/extra.rules’
   --delete host:src/dir /dest


rsync -av --filter=’: .rules’ --filter=’. /my/extra.rules’
   --delete host:src/dir /dest






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.


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 don’t get
deleted) and then put rules into the local files to control what else
should not get deleted.  Like one of these commands:






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


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








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 "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
".sh" to the batch filename.  The .sh file contains
a command-line suitable for updating a destination tree using that
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 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.


Examples:


$ rsync --write-batch=foo -a host:/source/dir/ /adest/dir/

$ scp foo* remote:

$ ssh remote ./foo.sh /bdest/dir/


$ rsync --write-batch=foo -a /source/dir/ /adest/dir/

$ ssh remote rsync --read-batch=- -a /bdest/dir/ <foo


In these examples, rsync is used to update /adest/dir/ from /source/dir/
and the information to repeat this operation is stored in "foo" and
"foo.sh".  The host "remote" 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:




The read-batch option expects the destination tree that it is updating
to be identical to the destination tree that was used to create the
batch update fileset.  When a difference between the destination trees
is encountered the update might be discarded with a warning (if the file
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 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 (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.  Rsync will die with an error if the
protocol version in the batch file is too new for the batch-reading rsync
to handle.  See also the --protocol option for a way to have the
creating rsync generate a batch file that an older rsync can understand.
(Note that batch files changed format in version 2.6.3, so mixing versions
older than that with newer versions will not work.)


When reading a batch file, rsync will force the value of certain options
to match the data in the batch file if you didn’t set them to the same
as the batch-writing command.  Other options can (and should) be changed.
For instance --write-batch changes to --read-batch,
--files-from is dropped, and the
--filter/--include/--exclude options are not needed unless
one of the --delete options is specified.


The code that creates the BATCH.sh file transforms any filter/include/exclude
options into a single list that is appended as a "here" document to the
shell script file.  An advanced user can use this to modify the exclude
list if a change in what gets deleted by --delete is desired.  A normal
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.


The original batch mode in rsync was based on "rsync+", but the latest
version uses a new implementation.




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
"skipping non-regular" file is emitted for any symlinks that exist.


If --links is specified, then symlinks are recreated with the same
target on the destination.  Note that --archive implies
--links.


If --copy-links is specified, then symlinks are "collapsed" by
copying their referent, rather than the symlink.


rsync also distinguishes "safe" and "unsafe" symbolic links.  An
example where this might be used is a web site mirror that wishes
ensure the rsync module they copy does not include symbolic links to
/etc/passwd in the public section of the site.  Using
--copy-unsafe-links will cause any links to be copied as the file
they point to on the destination.  Using --safe-links will cause
unsafe links to be omitted altogether.  (Note that you must specify
--links for --safe-links to have any effect.)


Symbolic links are considered unsafe if they are absolute symlinks
(start with /), empty, or if they contain enough ".."
components to ascend from the directory being copied.


Here’s a summary of how the symlink options are interpreted.  The list is
in order of precedence, so if your combination of options isn’t mentioned,
use the first line that is a complete subset of your options:




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


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:


ssh remotehost /bin/true > out.dat


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.


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.








/etc/rsyncd.conf or rsyncd.conf






times are transferred as *nix time_t values


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


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


see also the comments on the --delete option


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




This man page is current for version 2.6.8 of rsync.




rsync is distributed under the GNU public license.  See the file
COPYING for details.


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.


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


We would be delighted to hear from you if you like this program.


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




Thanks to Richard Brent, Brendan Mackay, Bill Waite, Stephen Rothwell
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,
Martin Pool, Wayne Davison, J.W. Schultz.




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
http://lists.samba.org











Advertisements


    129 Lectures 
     23 hours 

 Eduonix Learning Solutions

    5 Lectures 
     4.5 hours 

 Frahaan Hussain

    35 Lectures 
     2 hours 

 Pradeep D

    41 Lectures 
     2.5 hours 

 Musab Zayadneh

    46 Lectures 
     4 hours 

 GUHARAJANM

    6 Lectures 
     4 hours 

 Uplatz
 Print
 Add Notes
 Bookmark this page