mailto(rsync-bugs@samba.org)
-manpage(rsync)(1)(30 Mar 2005)()()
+manpage(rsync)(1)(7 Jul 2005)()()
manpagename(rsync)(faster, flexible replacement for rcp)
manpagesynopsis()
it() can use any transparent remote shell, including ssh or rsh
it() does not require root privileges
it() pipelining of file transfers to minimize latency costs
- it() support for anonymous or authenticated rsync servers (ideal for
+ it() support for anonymous or authenticated rsync daemons (ideal for
mirroring)
)
manpagesection(GENERAL)
-There are eight different ways of using rsync. They are:
+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).
-itemize(
- it() for copying local files. This is invoked when neither
- source nor destination path contains a : separator
- it() for copying from the local machine to a remote machine using
- a remote shell program as the transport (such as ssh or
- rsh). This is invoked when the destination path contains a
- single : separator.
- it() for copying from a remote machine to the local machine
- using a remote shell program. This is invoked when the source
- contains a : separator.
- it() for copying from a remote rsync server to the local
- machine. This is invoked when the source path contains a ::
- separator or an rsync:// URL.
- it() for copying from the local machine to a remote rsync
- server. This is invoked when the destination path contains a ::
- separator or an rsync:// URL.
- it() for copying from a remote machine using a remote shell
- program as the transport, using rsync server on the remote
- machine. This is invoked when the source path contains a ::
- separator and the bf(--rsh=COMMAND) (aka "bf(-e COMMAND)") option is
- also provided.
- it() for copying from the local machine to a remote machine
- using a remote shell program as the transport, using rsync
- server on the remote machine. This is invoked when the
- destination path contains a :: separator and the
- bf(--rsh=COMMAND) option is also provided.
- it() for listing files on a remote machine. This is done the
- same way as rsync transfers except that you leave off the
- local destination.
-)
+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
+"CONNECTING TO AN RSYNC DAEMON OVER A REMOTE SHELL PROGRAM" section for
+an exception to this latter rule).
+
+As a special case, if a remote source is specified without a destination,
+the remote files are listed in an output format similar to "ls -l".
-Note that in all cases (other than listing) at least one of the source
-and destination paths must be local.
+As expected, if neither the source or destination path specify a remote
+host, the copy occurs locally (see also the bf(--list-only) option).
manpagesection(SETUP)
This latter example assumes that your shell passes through unmatched
wildcards. If it complains about "no match", put the name in quotes.
-manpagesection(CONNECTING TO AN RSYNC SERVER)
+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 connect to a remote rsync server
+transport. In this case you will connect to a remote rsync daemon
running on TCP port 873.
You may establish the connection via a web proxy by setting the
itemize(
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 remote server may print a message of the day when you
+ it() the remote daemon may print a message of the day when you
connect.
- it() if you specify no path name on the remote server then the
- list of accessible paths on the server will be shown.
+ 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 server is provided.
+ specified files on the remote daemon is provided.
)
-Some paths on the remote server may require authentication. If so then
+Some paths on the remote daemon may require authentication. If so then
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
WARNING: On some systems environment variables are visible to all
users. On those systems using bf(--password-file) is recommended.
-manpagesection(CONNECTING TO AN RSYNC SERVER OVER A REMOTE SHELL PROGRAM)
+manpagesection(CONNECTING TO AN RSYNC DAEMON OVER A REMOTE SHELL PROGRAM)
It is sometimes useful to be able to set up file transfers using rsync
-server capabilities on the remote machine, while still using ssh or
+daemon capabilities on the remote machine, while still using ssh or
rsh for transport. This is especially useful when you want to connect
to a remote machine via ssh (for encryption or to get through a
-firewall), but you still want to have access to the rsync server
-features (see RUNNING AN RSYNC SERVER OVER A REMOTE SHELL PROGRAM,
+firewall), but you still want to have access to the rsync daemon
+features (see RUNNING AN RSYNC DAEMON OVER A REMOTE SHELL PROGRAM,
below).
From the user's perspective, using rsync in this way is the same as
-using it to connect to an rsync server, except that you must
+using it to connect to an rsync daemon, except that you must
explicitly set the remote shell program on the command line with
bf(--rsh=COMMAND). (Setting RSYNC_RSH in the environment will not turn on
this functionality.)
In order to distinguish between the remote-shell user and the rsync
-server user, you can use '-l user' on your remote-shell command:
+daemon user, you can use '-l user' on your remote-shell command:
verb( rsync -av --rsh="ssh -l ssh-user" \
rsync-user@host::module[/path] local-path)
The "ssh-user" will be used at the ssh level; the "rsync-user" will be
used to check against the rsyncd.conf on the remote host.
-manpagesection(RUNNING AN RSYNC SERVER)
+manpagesection(RUNNING AN RSYNC DAEMON)
-An rsync server is configured using a configuration file. Please see the
+An rsync daemon is configured using a configuration file. Please see the
rsyncd.conf(5) man page for more information. By default the configuration
-file is called /etc/rsyncd.conf, unless rsync is running over a remote
-shell program and is not running as root; in that case, the default name
-is rsyncd.conf in the current directory on the remote computer
-(typically $HOME).
+file is called /etc/rsyncd.conf (unless the daemon is spawned via a remote
+shell--see below).
-manpagesection(RUNNING AN RSYNC SERVER OVER A REMOTE SHELL PROGRAM)
+manpagesection(RUNNING AN RSYNC DAEMON OVER A REMOTE SHELL PROGRAM)
See the rsyncd.conf(5) man page for full information on the rsync
-server configuration file.
+daemon configuration file.
Several configuration options will not be available unless the remote
-user is root (e.g. chroot, setuid/setgid, etc.). There is no need to
-configure inetd or the services map to include the rsync server port
-if you run an rsync server only via a remote shell program.
+user is root (e.g. chroot, uid, gid, etc.). There is no need to
+configure inetd or the services map to include the rsync daemon port
+if you run an rsync daemon only via a remote shell program.
-To run an rsync server out of a single-use ssh key, see this section
+To run an rsync daemon out of a single-use ssh key, see this section
in the rsyncd.conf(5) man page.
manpagesection(EXAMPLES)
default, but you may prefer to use rsh on a local network.
If this option is used with bf([user@]host::module/path), then the
-remote shell em(COMMAND) will be used to run an rsync server on the
+remote shell em(COMMAND) will be used to run an rsync daemon on the
remote host, and all data will be transmitted through that remote
shell connection, rather than through a direct socket connection to a
-running rsync server on the remote host. See the section "CONNECTING
-TO AN RSYNC SERVER OVER A REMOTE SHELL PROGRAM" above.
+running rsync daemon on the remote host. See the section "CONNECTING
+TO AN RSYNC DAEMON OVER A REMOTE SHELL PROGRAM" above.
Command-line arguments are permitted in COMMAND provided that COMMAND is
presented to rsync as a single argument. For example:
quote(tt( rsync -a --files-from=/tmp/foo /usr remote:/backup))
If /tmp/foo contains the string "bin" (or even "/bin"), the /usr/bin
-directory will be created as /backup/bin on the remote host (but the
-contents of the /usr/bin dir would not be sent unless you specified bf(-r)
-or the names were explicitly listed in /tmp/foo). Also keep in mind
+directory will be created as /backup/bin on the remote host. If it
+contains "bin/" (note the trailing slash), the immediate contents of
+the directory would also be sent (without needing to be explicitly
+mentioned in the file -- this began in version 2.6.4). In both cases,
+if the bf(-r) option was enabled, that dir's entire hierarchy would
+also be transferred (keep in mind that bf(-r) needs to be specified
+explicitly with bf(--files-from), since it is not implied by bf(-a)).
+Also note
that the effect of the (enabled by default) bf(--relative) option is to
duplicate only the path info that is read from the file -- it does not
force the duplication of the source-spec path (/usr in this case).
it() A bf(s) means the size of the file is different and will be updated
by the file transfer.
it() A bf(t) means the modification time is different and is being updated
- to the server's value (requires bf(--times)). An alternate value of bf(T)
+ to the sender's value (requires bf(--times)). An alternate value of bf(T)
means that the time will be set to the transfer time, which happens
anytime a symlink is transferred, or when a file or device is transferred
without bf(--times).
it() A bf(p) means the permissions are different and are being updated to
- the server's value (requires bf(--perms)).
+ the sender's value (requires bf(--perms)).
it() An bf(o) means the owner is different and is being updated to the
- server's value (requires bf(--owner) and root privileges).
+ sender's value (requires bf(--owner) and root privileges).
it() A bf(g) means the group is different and is being updated to the
- server's value (requires bf(--group) and the authority to set the group).
+ sender's value (requires bf(--group) and the authority to set the group).
it() The bf(a) is reserved for a future enhanced version that supports
extended file attributes, such as ACLs.
))
specified (since bf(--inplace) conflicts with bf(--partial-dir)), or (2) when
bf(--delay-updates) was specified (see below).
-For the purposes of the server-config's "refuse options" setting,
+For the purposes of the daemon-config's "refuse options" setting,
bf(--partial-dir) does em(not) imply bf(--partial). This is so that a
refusal of the bf(--partial) option can be used to disallow the overwriting
of destination files with a partial transfer, while still allowing the
each file's destination directory, but you can override this by specifying
the bf(--partial-dir) option. (Note that RSYNC_PARTIAL_DIR has no effect
on this value, nor is bf(--partial-dir) considered to be implied for the
-purposes of the server-config's "refuse options" setting.)
+purposes of the daemon-config's "refuse options" setting.)
Conflicts with bf(--inplace).
This option uses more memory on the receiving side (one bit per file
transfer that may be interrupted.
dit(bf(--password-file)) This option allows you to provide a password
-in a file for accessing a remote rsync server. Note that this option
-is only useful when accessing an rsync server using the built in
+in a file for accessing a remote rsync daemon. Note that this option
+is only useful when accessing an rsync daemon using the built in
transport, not when using a remote shell as the transport. The file
must not be world readable. It should contain just the password as a
single line.
dit(bf(--list-only)) This option will cause the source files to be listed
instead of transferred. This option is inferred if there is no destination
specified, so you don't usually need to use it explicitly. However, it can
-come in handy for a power user that wants to avoid the "bf(-r --exclude='/*/*')"
+come in handy for a user that wants to avoid the "bf(-r --exclude='/*/*')"
options that rsync might use as a compatibility kluge when generating a
-non-recursive listing.
+non-recursive listing, or to list the files that are involved in a local
+copy (since the destination path is not optional for a local copy, you
+must specify this option explicitly and still include a destination).
dit(bf(--bwlimit=KBPS)) This option allows you to specify a maximum
transfer rate in kilobytes per second. This option is most effective when
default to having that modifier set. For instance, "merge,-/ .excl" would
treat the contents of .excl as absolute-path excludes,
while "dir-merge,s .filt" and ":sC" would each make all their
- per-directory rules apply only on the server side.
+ per-directory rules apply only on the sending side.
)
The following modifiers are accepted after a "+" or "-":
being transferred. The default is for a rule to affect both sides
unless bf(--delete-excluded) was specified, in which case default rules
become sender-side only. See also the hide (H) and show (S) rules,
- which are an alternate way to specify server-side includes/excludes.
+ which are an alternate way to specify sending-side includes/excludes.
it() An bf(r) is used to indicate that the rule applies to the receiving
side. When a rule affects the receiving side, it prevents files from
being deleted. See the bf(s) modifier for more info. See also the
bf(/etc/passwd) in the public section of the site. Using
bf(--copy-unsafe-links) will cause any links to be copied as the file
they point to on the destination. Using bf(--safe-links) will cause
-unsafe links to be omitted altogether.
+unsafe links to be omitted altogether. (Note that you must specify
+bf(--links) for bf(--safe-links) to have any effect.)
Symbolic links are considered unsafe if they are absolute symlinks
(start with bf(/)), empty, or if they contain enough bf("..")
components to ascend from the directory being copied.
+Here's a summary of how the symlink options are interpreted. The list is
+in order of precedence, so if your combination of options isn't mentioned,
+use the first line that is a complete subset of your options:
+
+dit(bf(--copy-links)) Turn all symlinks into normal files (leaving no
+symlinks for any other options to affect).
+
+dit(bf(--links --copy-unsafe-links)) Turn all unsafe symlinks into files
+and duplicate all safe symlinks.
+
+dit(bf(--copy-unsafe-links)) Turn all unsafe symlinks into files, noisily
+skip all safe symlinks.
+
+dit(bf(--links --safe-links)) Duplicate safe symlinks and skip unsafe
+ones.
+
+dit(bf(--links)) Duplicate all symlinks.
+
manpagediagnostics()
rsync occasionally produces error messages that may seem a little
daemon without user intervention. Note that this does not supply a
password to a shell transport such as ssh.
dit(bf(USER) or bf(LOGNAME)) The USER or LOGNAME environment variables
-are used to determine the default username sent to an rsync server.
+are used to determine the default username sent to an rsync daemon.
If neither is set, the username defaults to "nobody".
dit(bf(HOME)) The HOME environment variable is used to find the user's
default .cvsignore file.
Please report bugs! See the website at
url(http://rsync.samba.org/)(http://rsync.samba.org/)
+manpagesection(VERSION)
+
+This man page is current for version 2.6.6pre1 of rsync.
+
manpagesection(CREDITS)
rsync is distributed under the GNU public license. See the file
git.samba.org / rsync.git / blobdiff