rsync
*****

rsync is a flexible program for efficiently copying files or directory trees.

This manual documents rsync 2.5.  It is not yet complete and should be consulted in conjunction with the rsync manual page.

Copyright © 2002 by Martin Pool mbp@samba.org.

Copyright © 1996--2001 by Andrew Tridgell tridge@samba.org.

Overview
********

rsync is a program for efficiently copying files or directory trees. rsync has many options to select which files will be copied and how they are to be transferred.  It may be used as an alternative to FTP, HTTP, scp or rcp.

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.

rsync's command line syntax is analogous to cp, rcp and scp:

     rsync [OPTIONS] SOURCE DESTINATION

Filenames may be prefixed by a hostname to indicate a remote file. (see Local and remote.)

Some of the additional features of rsync are:

  * support for copying links, devices, owners, groups and permissions

  * exclude and exclude-from options similar to GNU tar

  * a CVS exclude mode for ignoring the same files that CVS would ignore

  * can use any transparent remote shell, including rsh or ssh

  * does not require root privileges

  * pipelining of file transfers to minimize latency costs

  * support for anonymous or authenticated rsync servers (ideal for mirroring)

Introductory example
====================

Probably the most common case of rsync usage is to copy files to or from a remote machine using ssh as a network transport.  In this situation rsync is a good alternative to scp.

The most commonly used arguments for rsync are

-a
     Reproduce the structure and attributes of the origin files as exactly as possible: this includes copying subdirectories, symlinks, special files, ownership and permissions.  (see Attributes to copy.)

-v
     Be verbose.  Primarily, display the name of each file as it is copied.

-z
     Compress network traffic, using a modified version of the zlib library.

-P
     Display a progress indicator while files are transferred.  This should normally be ommitted if rsync is not run on a terminal.

To make a backup of your home directory to the /bkup/mbp/ remote machine foo.example.org, preserving the directory structure, use this command:

     rsync -avP ~ foo.example.org:/bkup/mbp/

Local and remote
================

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

 1. for copying local files. This is invoked when neither source nor destination path contains a : separator

 2. for copying from the local machine to a remote machine using a remote shell program as the transport (such as rsh or ssh). This is invoked when the destination path contains a single : separator.

 3. for copying from a remote machine to the local machine using a remote shell program. This is invoked when the source contains a : separator.

 4. for copying from a remote rsync server to the local machine. This is invoked when the source path contains a :: separator or a rsync:// URL.

 5. for copying from the local machine to a remote rsync server. This is invoked when the destination path contains a :: separator.

 6. for listing files on a remote machine. This is done the same way as rsync transfers except that you leave off the local destination.

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

Any one invocation of rsync makes a copy in a single direction.  rsync currently has no equivalent of ftp's interactive mode.

rsync's network protocol is generally faster at copying files than network filesystems such as NFS or CIFS.  It is better to run rsync on the file server either as a daemon or over ssh than running rsync giving the network directory.

Setting up rsync
================

See the file INSTALL that comes with the distribution 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, either by 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.

Invoking rsync
**************

Controlling rsync messages
==========================

--version
     Print the rsync version number and compilation information and exit

--help
     Print a short help page describing the options available and exit.

--stats
     Print statistics about rsync perfomance.

-v
--verbose
     This option increases the amount of information you are given during the transfer.  By default, rsync works silently.  A single -v will give you information about what files are being transferred and a brief summary at the end.  Two -v flags will give you information on network connections, files skipped, and slightly more information at the end.  More than two -v flags should only be used if you are debugging rsync.

Attributes to copy
==================

-a

     Preserve as much as possible of the structure and attributes of the origin directory.

     On many systems, only the superuser can set the ownership of files, and users can only put files into a group to which that user belongs. rsync works within the operating system security model.  So on such a system, if you copy a file which you can read but that does not belong to you, the destination file will be owned by you.  The only way to change this behaviour is to copy the file as the superuser, or to adjust your operating system's security model if that is possible.

          Please note: --archive does not detect files with multiple names.  If any exist, they will become multiple identical files on the destination.  To make the names all refer to the same file, use --hard-links.

Exit values
===========

rsync's exit code may be examined by shell scripts to determine whether the transfer completed successfully or not.

RERR_SYNTAX     1
     Syntax or usage error

RERR_PROTOCOL   2
     Protocol incompatibility

RERR_FILESELECT 3
     Errors selecting input/output files, dirs

RERR_UNSUPPORTED 4
     Requested action not supported: an attempt was made to manipulate 64-bit files on a platform that cannot support them; or an option was speciifed that is supported by the client and not by the server.

RERR_SOCKETIO   10
     Error in socket IO

RERR_FILEIO     11
     Error in file IO

RERR_STREAMIO   12
     Error in rsync protocol data stream

RERR_MESSAGEIO  13
     Errors with program diagnostics

RERR_IPC        14
     Error in IPC code

RERR_SIGNAL     20
     Received SIGUSR1 or SIGINT

RERR_WAITCHILD  21
     Some error returned by waitpid()

RERR_MALLOC     22
     Error allocating core memory buffers

RERR_TIMEOUT    30
     Timeout in data send/receive

Daemon mode
***********

Configuring rsync as a server is entirely optional.  If you just want to copy your own files between local directories or machines, then using rsync over ssh may well be sufficient.  Daemon mode may be useful if you wish to distribute files to a number of machines on a network, or to the public.

TCP port 873 is reserved for rsync by the Internet Assigned Numbers Authority (IANA) and has the service name rsync. However, rsync may be run on any other port using the --port option.

Daemon mode security
====================