mailto(rsync-bugs@samba.org)
-manpage(rsync)(1)(19 May 2005)()()
+manpage(rsync)(1)(28 Jul 2005)()()
manpagename(rsync)(faster, flexible replacement for rcp)
manpagesynopsis()
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.
+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 remote source is specified without a destination,
the remote 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).
-Finally, it is possible to use a remote-shell transport to contact a remote
-host and then to spawn a single-use rsync daemon. This allows the use of
-some of the daemon features (such as named modules) without having to run a
-daemon as a service. To achieve this, invoke rsync with an explicit
-bf(--rsh=COMMAND) (aka "bf(-e COMMAND)") option combined with either the
-source or destination path specified as an rsync daemon (i.e. either a ::
-separator or an rsync:// URL). In this case, rsync contacts the remote
-host specified using the specified remote shell, and then starts a
-single-use rsync daemon to deal with that copy request. See the section
-"CONNECTING TO AN RSYNC DAEMON OVER A REMOTE SHELL PROGRAM" below.
-
manpagesection(SETUP)
See the file README for installation instructions.
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 daemon
-running on TCP port 873.
-
-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.
+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:
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 first word after the :: is 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
specified files on the remote daemon is provided.
)
-Some paths on the remote daemon may require authentication. If so then
+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
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 DAEMON OVER A REMOTE SHELL PROGRAM)
-
-It is sometimes useful to be able to set up file transfers using rsync
-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 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 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
-daemon user, you can use '-l user' on your remote-shell command:
+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.
-verb( rsync -av --rsh="ssh -l ssh-user" \
- rsync-user@host::module[/path] local-path)
+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
+explicitly set the remote shell program on the command-line with the
+bf(--rsh=COMMAND) option. (Setting the RSYNC_RSH in the environment
+will not turn on this functionality.) For example:
+
+verb( rsync -av --rsh=ssh host::module /dest)
+
+If you need to specify a different remote-shell user, keep in mind that the
+user@ prefix in front of the host is specifying the rsync-user value (for a
+module that requires user-based authentication). This means that you must
+give the '-l user' option to ssh when specifying the remote-shell:
+
+verb( rsync -av -e "ssh -l ssh-user" rsync-user@host::module /dest)
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 DAEMON)
+used to log-in to the "module".
-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).
+manpagesection(STARTING AN RSYNC DAEMON TO ACCEPT CONNECTIONS)
-manpagesection(RUNNING AN RSYNC DAEMON OVER A REMOTE SHELL PROGRAM)
+In order to connect to an rsync daemon, the remote system needs to have a
+daemon already running (or it needs to have configured something like inetd
+to spawn an rsync daemon for incoming connections on a particular port).
+For full information on how to start a daemon that will handling incoming
+socket connections, see the rsyncd.conf(5) man page -- that is the config
+file for the daemon, and it contains the full details for how to run the
+daemon (including stand-alone and inetd configurations).
-See the rsyncd.conf(5) man page for full information on the rsync
-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 daemon port
-if you run an rsync daemon only via a remote shell program.
-
-To run an rsync daemon out of a single-use ssh key, see this section
-in the rsyncd.conf(5) man page.
+If you're using one of the remote-shell transports for the transfer, there is
+no need to manually start an rsync daemon.
manpagesection(EXAMPLES)
--suffix=SUFFIX backup suffix (default ~ w/o --backup-dir)
-u, --update skip files that are newer on the receiver
--inplace update destination files in-place
+ --append append data onto shorter files
-d, --dirs transfer directories without recursing
-l, --links copy symlinks as symlinks
-L, --copy-links transform symlink into referent file/dir
rsync will be unable to update a file in-place that is not writable by the
receiving user.
+dit(bf(--append)) This causes rsync to update a file by appending data onto
+the end of the file, which presumes that the data that already exists on
+the receiving side is identical with the start of the file on the sending
+side. If that is not true, the file will fail the checksum test, and the
+resend will do a normal bf(--inplace) update to correct the mismatch. Any
+file on the receiving side that is longer than a file on the sending side
+is skipped. Implies bf(--inplace).
+
dit(bf(-d, --dirs)) Tell the sending side to include any directories that
are encountered. Unlike bf(--recursive), a directory's contents are not copied
unless the directory was specified on the command-line as either "." or a
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 daemon on the remote host. See the section "CONNECTING
-TO AN RSYNC DAEMON OVER A REMOTE SHELL PROGRAM" above.
+running rsync daemon on the remote host. See the section "USING
+RSYNC-DAEMON FEATURES VIA A REMOTE-SHELL CONNECTION" above.
Command-line arguments are permitted in COMMAND provided that COMMAND is
presented to rsync as a single argument. For example:
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
manpagesection(VERSION)
-This man page is current for version 2.6.5pre2 of rsync.
+This man page is current for version 2.6.6 of rsync.
manpagesection(CREDITS)
Matt McCutchen's Web Site / rsync / rsync.git / blobdiff