rsync

1 Mar 1999

NAME

rsync - faster, flexible replacement for rcp

SYNOPSIS


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


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


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


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


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


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


DESCRIPTION


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 speedup file transfers when the destination file already exists.


The rsync remote-update protocol allows rsync to transfer just the differences between two sets of files across the network link, using an efficient checksum-search algorithm described in the technical report that accompanies this package.


Some of the additional features of rsync are:



GENERAL


There are six different ways of using rsync. They are:



Note that in all cases (other than listing) at least one of the source and destination paths must be local.


SETUP


See the file README for installation instructions.


Once installed you can use rsync to any machine that you can use rsh to. rsync uses rsh for its communications, unless both the source and destination are local.


You can also specify an alternative to rsh, by either using the -e command line option, or by setting the RSYNC_RSH environment variable.


One common substitute is to use ssh, which offers a high degree of security.


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


USAGE


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 some examples:


rsync *.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 transfer all files from the directory src/bar on the machine foo into the /data/tmp/. A trailing / on a source name means "copy the contents of this directory". Without a trailing slash it means "copy the directory". This difference becomes particularly important when using the --delete option.


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.


rsync somehost.mydomain.com::


this would list all the anonymous rsync modules available on the host somehost.mydomain.com. (See the following section for more details.)


CONNECTING TO AN RSYNC SERVER


It is also possible to use rsync without using rsh or ssh as the transport. In this case you will connect to a remote rsync server running on TCP port 873.


You may establish the connetcion 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 must allow proxying to port 873, this must be configured in your proxy servers ruleset.


Using rsync in this way is the same as using it with rsh or ssh except that:



Some paths on the remote server may require authentication. If so then 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.


RUNNING AN RSYNC SERVER


An rsync server is configured using a config file which by default is called /etc/rsyncd.conf. Please see the rsyncd.conf(5) man page for more information.


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


rsync -Cavz . arvidsjaur:backup


each night over a PPP link 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


this allows me to sync with a CVS directory at the other end of the link. 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/samba"


this is launched from cron every few hours.


OPTIONS SUMMARY


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                 decrease verbosity
 -c, --checksum              always checksum
 -a, --archive               archive mode
 -r, --recursive             recurse into directories
 -R, --relative              use relative path names
 -b, --backup                make backups (default ~ suffix)
     --backup-dir=DIR        put backups in the specified directory
     --suffix=SUFFIX         override backup suffix
 -u, --update                update only (don't overwrite newer files)
 -l, --links                 preserve soft links
 -L, --copy-links            treat soft links like regular files
     --copy-unsafe-links     copy links outside the source tree
     --safe-links            ignore links outside the destination tree
 -H, --hard-links            preserve hard links
 -p, --perms                 preserve permissions
 -o, --owner                 preserve owner (root only)
 -g, --group                 preserve group
 -D, --devices               preserve devices (root only)
 -t, --times                 preserve times
 -S, --sparse                handle sparse files efficiently
 -n, --dry-run               show what would have been transferred
 -W, --whole-file            copy whole files, no incremental checks
 -x, --one-file-system       don't cross filesystem boundaries
 -B, --block-size=SIZE       checksum blocking size (default 700)
 -e, --rsh=COMMAND           specify rsh replacement
     --rsync-path=PATH       specify path to rsync on the remote machine
 -C, --cvs-exclude           auto ignore files in the same way CVS does
     --existing              only update files that already exist
     --delete                delete files that don't exist on the sending side
     --delete-excluded       also delete excluded files on the receiving side
     --delete-after          delete after transferring, not before
     --max-delete=NUM        don't delete more than NUM files
     --partial               keep partially transferred files
     --force                 force deletion of directories even if not empty
     --numeric-ids           don't map uid/gid values by user/group name
     --timeout=TIME          set IO timeout in seconds
 -I, --ignore-times          don't exclude files that match length and time
     --size-only             only use file size when determining if a file should be transferred
 -T  --temp-dir=DIR          create temporary files in directory DIR
     --compare-dest=DIR      also compare destination files relative to DIR
 -P                          equivalent to --partial --progress
 -z, --compress              compress file data
     --exclude=PATTERN       exclude files matching PATTERN
     --exclude-from=FILE     exclude patterns listed in FILE
     --include=PATTERN       don't exclude files matching PATTERN
     --include-from=FILE     don't exclude patterns listed in FILE
     --version               print version number
     --daemon                run as a rsync daemon
     --address               bind to the specified address
     --config=FILE           specify alternate rsyncd.conf file
     --port=PORT             specify alternate rsyncd port number
     --stats                 give some file transfer stats
     --progress              show progress during transfer
     --log-format=FORMAT     log file transfers using specified format
     --password-file=FILE    get password from FILE
 -h, --help                  show this help screen


OPTIONS


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.



EXCLUDE PATTERNS


The exclude and include patterns specified to rsync allow for flexible selection of which files to transfer and which files to skip.


rsync builds a ordered list of include/exclude options as specified on the command line. When a filename is encountered, rsync checks the name against each exclude/include pattern in turn. The first matching pattern is acted on. If it is an exclude pattern than that file is skipped. If it is an include pattern then that filename is not skipped. If no matching include/exclude pattern is found then the filename is not skipped.


Note that the --include and --exclude options take one pattern each. To add multiple patterns use the --include-from and --exclude-from options or multiple --include and --exclude options.


The patterns can take several forms. The rules are:



The +/- rules are most useful in exclude lists, allowing you to have a single exclude list that contains both include and exclude options.


Here are some examples:



DIAGNOSTICS


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:


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


ENVIRONMENT VARIABLES



FILES


/etc/rsyncd.conf


SEE ALSO


rsyncd.conf(5)


DIAGNOSTICS


BUGS


times are transferred as unix time_t values


file permissions, devices etc are transferred as native numerical values


see also the comments on the --delete option


Please report bugs! The rsync bug tracking system is online at http://rsync.samba.org/rsync/


VERSION

This man page is current for version 2.0 of rsync


CREDITS


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


Thanks to Richard Brent, Brendan Mackay, Bill Waite, Stephen Rothwell and David Bell for helpful suggestions and testing of rsync. I've probably missed some people, my apologies if I have.


AUTHOR


rsync was written by Andrew Tridgell and Paul Mackerras. They may be contacted via email at tridge@samba.org and Paul.Mackerras@cs.anu.edu.au