# rsync

1996 -- 2002
Martin Pool
Andrew Tridgell
Martin
Pool

## Introduction

rsync is a flexible 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.

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)

## Using rsync

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

`-v`

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

`-a`

  Reproduce the structure and attributes of the origin files as exactly as possible: this includes copying subdirectories, symlinks, special files, ownership and permissions. (@xref{Attributes to copy}.)

`-v`

`-z` Compress network traffic, using a modified version of the @command{zlib} library.

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

### 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 @code{:} 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 @code{:} 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 @code{:} separator.

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

5. for copying from the local machine to a remote rsync server. This is invoked when the destination path contains a @code{::} 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 @command{ftp}'s interactive mode.

@cindex @sc{nfs} @cindex network filesystems @cindex remote filesystems

rsync's network protocol is generally faster at copying files than network filesystems such as @sc{nfs} or @sc{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.

## Frequently asked questions

Are there mailing lists for rsync?

Yes, and you can subscribe and unsubscribe through a web interface at http://lists.samba.org/

If you are having trouble with the mailing list, please send mail to the administrator

rsync-admin@lists.samba.org

not to the list itself.

The mailing list archives are searchable. Use Google and prepend the search with `site:lists.samba.org rsync`, plus relevant keywords.

Why is rsync so much bigger when I build it with `gcc`?

On gcc, rsync builds by default with debug symbols included. If you strip both executables, they should end up about the same size. (Use `make install-strip`.)

Is rsync useful for a single large file like an ISO image?

Yes, but note the following:

Background: A common use of rsync is to update a file (or set of files) in one location from a more correct or up-to-date copy in another location, taking advantage of portions of the files that are identical to speed up the process. (Note that rsync will transfer a file in its entirety if no copy exists at the destination.)

(This discussion is written in terms of updating a local copy of a file from a correct file in a remote location, although rsync can work in either direction.)

The file to be updated (the local file) must be in a destination directory that has enough space for two copies of the file. (In addition, keep an extra copy of the file to be updated in a different location for safety -- see the discussion (below) about rsync's behavior when the rsync process is interrupted before completion.)

The local file must have the same name as the remote file being sync'd to (I think?). If you are trying to upgrade an iso from, for example, beta1 to beta2, rename the local file to the same name as the beta2 file. *(This is a useful thing to do -- only the changed portions will be transmitted.)*

The extra copy of the local file kept in a different location is because of rsync's behavior if interrupted before completion:

* If you specify the --partial option and rsync is interrupted, rsync will save the partially rsync'd file and throw away the original local copy. (The partially rsync'd file is correct but truncated.) If rsync is restarted, it will not have a local copy of the file to check for duplicate blocks beyond the section of the file that has already been rsync'd, thus the remainder of the rsync process will be a "pure transfer" of the file rather than taking advantage of the rsync algorithm.

* If you don't specify the --partial option and rsync is interrupted, rsync will throw away the partially rsync'd file, and, when rsync is restarted starts the rsync process over from the beginning.

Which of these is most desirable depends on the degree of commonality between the local and remote copies of the file *and how much progress was made before the interruption*.

The ideal approach after an interruption would be to create a new file by taking the original file and deleting a portion equal in size to the portion already rsync'd and then appending *the remaining* portion to the portion of the file that has already been rsync'd. (There has been some discussion about creating an option to do this automatically.)

The --compare-dest option is useful when transferring multiple files, but is of no benefit in transferring a single file. (AFAIK)

*Other potentially useful information can be found at: -[3]http://twiki.org/cgi-bin/view/Wikilearn/RsyncingALargeFile

This answer, formatted with "real" bullets, can be found at: -[4]http://twiki.org/cgi-bin/view/Wikilearn/RsyncingALargeFileFAQ*

## Other Resources