rsync.yo

Rsync 3.0.5 source code

explicitly set the remote shell program on the command-line with the
bf(--rsh=COMMAND) option.  (Setting the RSYNC_RSH in the environment
will not turn on this functionality.)  For example:

verb(    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 bf(--rsh) option:

verb(    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".

manpagesection(STARTING AN RSYNC DAEMON TO ACCEPT CONNECTIONS)

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

manpagesection(EXAMPLES)

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

quote(tt(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:

verb(    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:

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

This is launched from cron every few hours.

manpagesection(OPTIONS SUMMARY)

Here is a short summary of the options available in rsync. Please refer
to the detailed description below for a complete description.  verb(
 -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 "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
     --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 transfer (default)
     --delete-during         receiver deletes during xfer, not before
     --delete-delay          find deletions during, delete after
     --delete-after          receiver deletes after transfer, not before
     --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))

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
     --log-file=FILE         override the "log file" setting
     --log-file-format=FMT   override the "log format" 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))

manpageoptions()

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.

startdit()
dit(bf(--help)) Print a short help page describing the options
available in rsync and exit.  For backward-compatibility with older
versions of rsync, the help will also be output if you use the bf(-h)
option without any other args.

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
single bf(-v) will give you information about what files are being
transferred and a brief summary at the end. Two bf(-v) options will give you
information on what files are being skipped and slightly more
information at the end. More than two bf(-v) options should only be used if
you are debugging rsync.

Note that the names of the transferred files that are output are done using
a default bf(--out-format) of "%n%L", which tells you just the name of the
file and, if the item is a link, where it points.  At the single bf(-v)
level of verbosity, this does not mention when a file gets its attributes
changed.  If you ask for an itemized list of changed attributes (either
bf(--itemize-changes) or adding "%i" to the bf(--out-format) setting), the
output (on the client) increases to mention all items that are changed in
any way.  See the bf(--out-format) option for more details.

dit(bf(-q, --quiet)) This option decreases the amount of information you
are given during the transfer, notably suppressing information messages
from the remote server. This option is useful when invoking rsync from
cron.

dit(bf(--no-motd)) This option affects the information that is output
by the client at the start of a daemon transfer.  This suppresses the
message-of-the-day (MOTD) text, but it also affects the list of modules
that the daemon sends in response to the "rsync host::" request (due to
a limitation in the rsync protocol), so omit this option if you want to
request the list of modules from the daemon.

dit(bf(-I, --ignore-times)) Normally rsync will skip any files that are
already the same size and have the same modification timestamp.
This option turns off this "quick check" behavior, causing all files to
be updated.

dit(bf(--size-only)) This modifies rsync's "quick check" algorithm for
finding files that need to be transferred, changing it from the default of
transferring files with either a changed size or a changed last-modified
time to just looking for files that have changed in size.  This is useful
when starting to use rsync after using another mirroring system which may