rsync.1

Rsync 3.0.5 source code

.TH "rsync" "1" "28 Dec 2008" "" ""
.SH "NAME"
rsync \(em a fast, versatile, remote (and local) file-copying tool
.SH "SYNOPSIS"

.PP 
.nf 
Local:  rsync [OPTION...] SRC... [DEST]

Access via remote shell:
  Pull: rsync [OPTION...] [USER@]HOST:SRC... [DEST]
  Push: rsync [OPTION...] SRC... [USER@]HOST:DEST

Access via rsync daemon:
  Pull: rsync [OPTION...] [USER@]HOST::SRC... [DEST]
        rsync [OPTION...] rsync://[USER@]HOST[:PORT]/SRC... [DEST]
  Push: rsync [OPTION...] SRC... [USER@]HOST::DEST
        rsync [OPTION...] SRC... rsync://[USER@]HOST[:PORT]/DEST
.fi 

.PP 
Usages with just one SRC arg and no DEST arg will list the source files
instead of copying.
.PP 
.SH "DESCRIPTION"

.PP 
Rsync is a fast and extraordinarily versatile file copying tool.  It can
copy locally, to/from another host over any remote shell, or to/from a
remote rsync daemon.  It offers a large number of options that control
every aspect of its behavior and permit very flexible specification of the
set of files to be copied.  It is famous for its delta-transfer algorithm,
which reduces the amount of data sent over the network by sending only the
differences between the source files and the existing files in the
destination.  Rsync is widely used for backups and mirroring and as an
improved copy command for everyday use.
.PP 
Rsync finds files that need to be transferred using a \(lqquick check\(rq
algorithm (by default) that looks for files that have changed in size or
in last-modified time.  Any changes in the other preserved attributes (as
requested by options) are made on the destination file directly when the
quick check indicates that the file's data does not need to be updated.
.PP 
Some of the additional features of rsync are:
.PP 
.IP o 
support for copying links, devices, owners, groups, and permissions
.IP o 
exclude and exclude-from options similar to GNU tar
.IP o 
a CVS exclude mode for ignoring the same files that CVS would ignore
.IP o 
can use any transparent remote shell, including ssh or rsh
.IP o 
does not require super-user privileges
.IP o 
pipelining of file transfers to minimize latency costs
.IP o 
support for anonymous or authenticated rsync daemons (ideal for
mirroring)

.PP 
.SH "GENERAL"

.PP 
Rsync copies files either to or from a remote host, or locally on the
current host (it does not support copying files between two remote hosts).
.PP 
There are two different ways for rsync to contact a remote system: using a
remote-shell program as the transport (such as ssh or rsh) or contacting an
rsync daemon directly via TCP.  The remote-shell transport is used whenever
the source or destination path contains a single colon (:) separator after
a host specification.  Contacting an rsync daemon directly happens when the
source or destination path contains a double colon (::) separator after a
host specification, OR when an rsync:// URL is specified (see also the
\(lqUSING RSYNC-DAEMON FEATURES VIA A REMOTE-SHELL CONNECTION\(rq section for
an exception to this latter rule).
.PP 
As a special case, if a single source arg is specified without a
destination, the files are listed in an output format similar to \(lqls \-l\(rq.
.PP 
As expected, if neither the source or destination path specify a remote
host, the copy occurs locally (see also the \fB\-\-list\-only\fP option).
.PP 
Rsync refers to the local side as the \(lqclient\(rq and the remote side as the
\(lqserver\(rq.  Don't confuse \(lqserver\(rq with an rsync daemon \(em a daemon is always a
server, but a server can be either a daemon or a remote-shell spawned process.
.PP 
.SH "SETUP"

.PP 
See the file README for installation instructions.
.PP 
Once installed, you can use rsync to any machine that you can access via
a remote shell (as well as some that you can access using the rsync
daemon-mode protocol).  For remote transfers, a modern rsync uses ssh
for its communications, but it may have been configured to use a
different remote shell by default, such as rsh or remsh.
.PP 
You can also specify any remote shell you like, either by using the \fB\-e\fP
command line option, or by setting the RSYNC_RSH environment variable.
.PP 
Note that rsync must be installed on both the source and destination
machines.
.PP 
.SH "USAGE"

.PP 
You use rsync in the same way you use rcp. You must specify a source
and a destination, one of which may be remote.
.PP 
Perhaps the best way to explain the syntax is with some examples:
.PP 
.RS 
\f(CWrsync \-t *.c foo:src/\fP
.RE

.PP 
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.
.PP 
.RS 
\f(CWrsync \-avz foo:src/bar /data/tmp\fP
.RE

.PP 
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 \(lqarchive\(rq 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.
.PP 
.RS 
\f(CWrsync \-avz foo:src/bar/ /data/tmp\fP
.RE

.PP 
A trailing slash on the source changes this behavior to avoid creating an
additional directory level at the destination.  You can think of a trailing
/ on a source as meaning \(lqcopy the contents of this directory\(rq as opposed
to \(lqcopy the directory by name\(rq, but in both cases the attributes of the
containing directory are transferred to the containing directory on the
destination.  In other words, each of the following commands copies the
files in the same way, including their setting of the attributes of
/dest/foo:
.PP 
.RS 
\f(CWrsync \-av /src/foo /dest\fP
.br 
\f(CWrsync \-av /src/foo/ /dest/foo\fP
.br 
.RE

.PP 
Note also that host and module references don't require a trailing slash to
copy the contents of the default directory.  For example, both of these
copy the remote directory's contents into \(lq/dest\(rq:
.PP 
.RS 
\f(CWrsync \-av host: /dest\fP
.br 
\f(CWrsync \-av host::module /dest\fP
.br 
.RE

.PP 
You can also use rsync in local-only mode, where both the source and
destination don't have a \(oq:\(cq in the name. In this case it behaves like
an improved copy command.
.PP 
Finally, you can list all the (listable) modules available from a
particular rsync daemon by leaving off the module name:
.PP 
.RS 
\f(CWrsync somehost.mydomain.com::\fP
.RE

.PP 
See the following section for more details.
.PP 
.SH "ADVANCED USAGE"

.PP 
The syntax for requesting multiple files from a remote host is done by
specifying additional remote-host args in the same style as the first,
or with the hostname omitted.  For instance, all these work:
.PP 
.RS 
\f(CWrsync \-av host:file1 :file2 host:file{3,4} /dest/\fP
.br 
\f(CWrsync \-av host::modname/file{1,2} host::modname/file3 /dest/\fP
.br 
\f(CWrsync \-av host::modname/file1 ::modname/file{3,4}\fP
.RE

.PP 
Older versions of rsync required using quoted spaces in the SRC, like these
examples:
.PP 
.RS 
\f(CWrsync \-av host:'dir1/file1 dir2/file2' /dest\fP
.br 
\f(CWrsync host::'modname/dir1/file1 modname/dir2/file2' /dest\fP
.RE

.PP 
This word-splitting still works (by default) in the latest rsync, but is
not as easy to use as the first method.
.PP 
If you need to transfer a filename that contains whitespace, you can either
specify the \fB\-\-protect\-args\fP (\fB\-s\fP) option, or you'll need to escape
the whitespace in a way that the remote shell will understand.  For
instance:
.PP 
.RS 
\f(CWrsync \-av host:'file\e name\e with\e spaces' /dest\fP
.RE

.PP 
.SH "CONNECTING TO AN RSYNC DAEMON"

.PP 
It is also possible to use rsync without a remote shell as the transport.
In this case you will directly connect to a remote rsync daemon, typically
using TCP port 873.  (This obviously requires the daemon to be running on
the remote system, so refer to the STARTING AN RSYNC DAEMON TO ACCEPT
CONNECTIONS section below for information on that.)
.PP 
Using rsync in this way is the same as using it with a remote shell except
that:
.PP 
.IP o 
you either use a double colon :: instead of a single colon to
separate the hostname from the path, or you use an rsync:// URL.
.IP o 
the first word of the \(lqpath\(rq is actually a module name.
.IP o 
the remote daemon may print a message of the day when you
connect.
.IP o 
if you specify no path name on the remote daemon then the
list of accessible paths on the daemon will be shown.
.IP o 
if you specify no local destination then a listing of the
specified files on the remote daemon is provided.
.IP o 
you must not specify the \fB\-\-rsh\fP (\fB\-e\fP) option.

.PP 
An example that copies all the files in a remote module named \(lqsrc\(rq:
.PP 
.nf 
    rsync \-av host::src /dest
.fi 

.PP 
Some modules on the remote daemon may require authentication. If so,
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 \fB\-\-password\-file\fP option. This
may be useful when scripting rsync.
.PP 
WARNING: On some systems environment variables are visible to all
users. On those systems using \fB\-\-password\-file\fP is recommended.
.PP 
You may establish the connection 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's configuration must support
proxy connections to port 873.
.PP