rsync.yo

Rsync 3.0.5 source code

mailto([e-mail])
manpage(rsync)(1)(28 Dec 2008)()()
manpagename(rsync)(a fast, versatile, remote (and local) file-copying tool)
manpagesynopsis()

verb(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)

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

manpagedescription()

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.

Rsync finds files that need to be transferred using a "quick check"
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.

Some of the additional features of rsync are:

itemization(
  it() support for copying links, devices, owners, groups, and permissions
  it() exclude and exclude-from options similar to GNU tar
  it() a CVS exclude mode for ignoring the same files that CVS would ignore
  it() can use any transparent remote shell, including ssh or rsh
  it() does not require super-user privileges
  it() pipelining of file transfers to minimize latency costs
  it() support for anonymous or authenticated rsync daemons (ideal for
       mirroring)
)

manpagesection(GENERAL)

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

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
"USING RSYNC-DAEMON FEATURES VIA A REMOTE-SHELL CONNECTION" section for
an exception to this latter rule).

As a special case, if a single source arg is specified without a
destination, the files are listed in an output format similar to "ls -l".

As expected, if neither the source or destination path specify a remote
host, the copy occurs locally (see also the bf(--list-only) option).

Rsync refers to the local side as the "client" and the remote side as the
"server".  Don't confuse "server" with an rsync daemon -- a daemon is always a
server, but a server can be either a daemon or a remote-shell spawned process.

manpagesection(SETUP)

See the file README for installation instructions.

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.

You can also specify any remote shell you like, either by using the bf(-e)
command line option, or by setting the RSYNC_RSH environment variable.

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

manpagesection(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 with some examples:

quote(tt(rsync -t *.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.

quote(tt(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.

quote(tt(rsync -avz foo:src/bar/ /data/tmp))

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 "copy the contents of this directory" as opposed
to "copy the directory by name", 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:

quote(
tt(rsync -av /src/foo /dest)nl()
tt(rsync -av /src/foo/ /dest/foo)nl()
)

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 "/dest":

quote(
tt(rsync -av host: /dest)nl()
tt(rsync -av host::module /dest)nl()
)

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.

Finally, you can list all the (listable) modules available from a
particular rsync daemon by leaving off the module name:

quote(tt(rsync somehost.mydomain.com::))

See the following section for more details.

manpagesection(ADVANCED USAGE)

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:

quote(tt(rsync -av host:file1 :file2 host:file{3,4} /dest/)nl()
tt(rsync -av host::modname/file{1,2} host::modname/file3 /dest/)nl()
tt(rsync -av host::modname/file1 ::modname/file{3,4}))

Older versions of rsync required using quoted spaces in the SRC, like these
examples:

quote(tt(rsync -av host:'dir1/file1 dir2/file2' /dest)nl()
tt(rsync host::'modname/dir1/file1 modname/dir2/file2' /dest))

This word-splitting still works (by default) in the latest rsync, but is
not as easy to use as the first method.

If you need to transfer a filename that contains whitespace, you can either
specify the bf(--protect-args) (bf(-s)) option, or you'll need to escape
the whitespace in a way that the remote shell will understand.  For
instance:

quote(tt(rsync -av host:'file\ name\ with\ spaces' /dest))

manpagesection(CONNECTING TO AN RSYNC DAEMON)

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

Using rsync in this way is the same as using it with a remote shell except
that:

itemization(
	it() you either use a double colon :: instead of a single colon to
	separate the hostname from the path, or you use an rsync:// URL.
	it() the first word of the "path" is actually a module name.
	it() the remote daemon may print a message of the day when you
	connect.
	it() if you specify no path name on the remote daemon then the
	list of accessible paths on the daemon will be shown.
	it() if you specify no local destination then a listing of the
	specified files on the remote daemon is provided.
	it() you must not specify the bf(--rsh) (bf(-e)) option.
)

An example that copies all the files in a remote module named "src":

verb(    rsync -av host::src /dest)

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 bf(--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 bf(--password-file) is recommended.

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.

You may also establish a daemon connection using a program as a proxy by
setting the environment variable RSYNC_CONNECT_PROG to the commands you
wish to run in place of making a direct socket connection.  The string may
contain the escape "%H" to represent the hostname specified in the rsync
command (so use "%%" if you need a single "%" in your string).  For
example:

verb(  export RSYNC_CONNECT_PROG='ssh proxyhost nc %H 873'
  rsync -av targethost1::module/src/ /dest/
  rsync -av rsync:://targethost2/module/src/ /dest/ )

The command specified above uses ssh to run nc (netcat) on a proxyhost,
which forwards all data to port 873 (the rsync daemon) on the targethost
(%H).

manpagesection(USING RSYNC-DAEMON FEATURES VIA A REMOTE-SHELL CONNECTION)

It is sometimes useful to use various features of an rsync daemon (such as
named modules) without actually allowing any new socket connections into a
system (other than what is already required to allow remote-shell access).
Rsync supports connecting to a host using a remote shell and then spawning
a single-use "daemon" server that expects to read its config file in the
home dir of the remote user.  This can be useful if you want to encrypt a
daemon-style transfer's data, but since the daemon is started up fresh by
the remote user, you may not be able to use features such as chroot or
change the uid used by the daemon.  (For another way to encrypt a daemon
transfer, consider using ssh to tunnel a local port to a remote machine and
configure a normal rsync daemon on that remote host to only allow
connections from "localhost".)

From the user's perspective, a daemon transfer via a remote-shell
connection uses nearly the same command-line syntax as a normal
rsync-daemon transfer, with the only exception being that you must