Introduction

rsync is a replacement for mirror and rcp. It copies files and directories between two hosts, utilising a minimum amount of bandwidth by sending only the data that it needs to send to synchronise the source and destination.

It calculates a block-by-block checksum of the source tree, sending these checksums over a network link, where a second rsync compares them against a list of checksums calculated at the destination. Only portions of the source tree that have different checksums are sent across the link, saving bandwidth at the cost of some CPU time.

rsync uses rsh or ssh to start a peer on the remote host, and to act as a transport for the data. This means the traditional methods of authentication and encryption provided by those programs (such as .rhosts, hosts.equiv, or .ssh/authorized_hosts and ssh-agent) can be used.

rsync also supports an "anonymous rsync" mode, which allows rsync clients to connect to it and retrieve "modules". This is ideal for mirroring FTP and HTTP sites, home directories or CVS repositories.

Command-line Options

      rsync [options] [user@]host:path               path
      rsync [options] path                           [user@]host:path
      rsync [options] path                           path
      rsync [options] [user@]host::module[/path]     path
      rsync [options] path[user@]host::module[/path]

In all cases, the first non-option argument indicates the source, and the second indicates the destination. Either the source or destination must be on the local machine, although clever use of NFS mounts could get around this.

If rsync is invoked to retrieve no modules from a remote rsync server, the default behaviour is to print a list of modules available from that host.

Example Usage

Copy files on the local host

rsync /home/henry/Kernel/linux-2.2.0.tar.gz /usr/src/linux.tgz

linux-2.2.0.tar.gz will be copied from the user's directory to /usr/src, and renamed to linux.tgz. In effect, this behaves exactly like cp, except the destination file would not be mindlessly overwritten; only portions of the source file that needed to be copied would be "transmitted".

Copy files from a remote host to the local host

rsync -a linus@transmeta.com:/home/linus/linux-3.0.0/ /pub/ftp/linux-kernel/v3.0.0/

In this example, a remote shell would be started on transmeta.com, under the username "linus". Once the connection had been established (depending on the transport agent used, there may be a prompt for a password or passphrase), the [CHECK THIS] contents of linus's linux-3.0.0 directory would be synchronised with the contents of the public FTP server directory on the local host.

The -a option means the same thing as it does to cp---rsync will run in "archive" mode, which preserves permissions, file ownership, and recurses directories.

Mirror a module from a remote host

rsync mirror.aarnet.edu.au::
rsync mirror.aarnet.edu.au::redhat /home/ftp/pub/redhat
rsync mirror.aarnet.edu.au::debian/dists/potato /home/ftp/debian/potato

The first of these three commands lists the modules available for mirroring on mirror.aarnet.edu.au. After viewing the list, and deciding which modules to retrieve, the next two commands perform some transfers. The first will retrieve all of the Red Hat archive, whereas the second will only retrieve the "potato" part of the Debian archive.

rsync command-line switches and options

For a serious discussion of rsync's options, you should turn to the README file that came with the distribution (found under /usr/doc/rsync on Debian and Red Hat) or (preferably) to the manual page.

rsync supports both long and short options for most flags. Short argument forms are given first, if they exist, with long GNU-style arguments following.

• By far the most useful option is -a (--archive). This acts like the corresponding option to cp; rsync will:
  • recurse subdirectories (-r);
  • recreate soft links (-l);
  • preserve permissions (-p);
  • preserve timestamps (-t);
  • attempt to copy devices (if invoked as root) (-D);
  • preserve group information (-g) (and userid, if invoked as root) (-o).
• The -H (--hard-links) option is not implied by -a.
• -b (--backup) will force backups to be made; the default extension is a tilde, "~". Overridden with --suffix=SUFFIX.
• -S (--sparse) asks rsync to copy sparse files efficiently.
• -x (--one-file-system): Don't cross filesystems. Useful if you've got -a turned on!
• -e (-rsh=COMMAND) use COMMAND instead of rsh. Using rsync without this option to specify ssh can result in very confusing error messages.
• --daemon run in "daemon" mode, where clients may connect to receive (parts of) pre-defined "modules".
• --config=FILE FILE is used as the config file for a daemon mode instead of /etc/rsyncd.conf.

rsyncd.conf

uid     = root
gid     = root
exclude = tmp/
exclude = temp/

[home]
        path            = /export/home
        comment         = All home directories
        read only       = true
        hosts allow     = trustedhost.plugged.org.au

This configuration file specifies an rsync daemon that runs as root, and offers /export/home to any client from trustedhost.plugged.org.au.

The other options ensure that directories named "tmp" or "temp" are never transferred, and that clients have read-only access to the server.

Typical Usage

Resources

rsync's maintainer is Andrew Tridgell, the author of Samba; he can be reached at tridge@samba.anu.edu.au. There is also an rsync mailing list that provides technical support for rsync's users.

Getting rsync source code

CVS

For you bleeding-edge types, rsync can be retrieved by CVS:

cvs -d :pserver:cvs@cvs.samba.org:/cvsroot login
Password: cvs

cvs -d :pserver:cvs@cvs.samba.org:/cvsroot co rsync

This will create a directory called "rsync", where you can build rsync, hack the source, or even write more documentation. Running

cvs update

in the "rsync" directory will update your new source tree to the latest version released.

See the CVS manual page for more information.

Source tarballs

Precompiled versions