mailto(rsync-bugs@samba.org)
-manpage(rsync)(1)(7 Jul 2005)()()
+manpage(rsync)(1)(28 Jul 2005)()()
manpagename(rsync)(faster, flexible replacement for rcp)
manpagesynopsis()
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
+"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,
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::))
-This would list all the anonymous rsync modules available on the host
-somehost.mydomain.com. (See the following section for more details.)
+See the following section for more details.
manpagesection(ADVANCED USAGE)
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 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.
)
-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)
-
-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 the daemon is spawned via a remote
-shell--see below).
-
-manpagesection(RUNNING AN RSYNC DAEMON OVER A REMOTE SHELL PROGRAM)
+used to log-in to the "module".
-See the rsyncd.conf(5) man page for full information on the rsync
-daemon configuration file.
+manpagesection(STARTING AN RSYNC DAEMON TO ACCEPT CONNECTIONS)
-Several configuration options will not be available unless the remote
-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.
+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).
-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)
-q, --quiet suppress non-error messages
-c, --checksum skip based on checksum, not mod-time & size
-a, --archive archive mode; same as -rlptgoD (no -H)
+ --no-OPTION turn off an implied OPTION (e.g. --no-D)
-r, --recursive recurse into directories
-R, --relative use relative path names
- --no-relative turn off --relative
- --no-implied-dirs don't send implied dirs with -R
+ --no-implied-dirs don't send implied dirs with --relative
-b, --backup make backups (see --suffix & --backup-dir)
--backup-dir=DIR make backups into hierarchy based in DIR
--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
-S, --sparse handle sparse files efficiently
-n, --dry-run show what would have been transferred
-W, --whole-file copy files whole (without rsync algorithm)
- --no-whole-file always use incremental rsync algorithm
-x, --one-file-system don't cross filesystem boundaries
-B, --block-size=SIZE force a fixed checksum block-size
-e, --rsh=COMMAND specify the remote shell to use
--address=ADDRESS bind address for outgoing socket to daemon
--port=PORT specify double-colon alternate port number
--blocking-io use blocking I/O for the remote shell
- --no-blocking-io turn off blocking I/O when it is default
--stats give some file-transfer stats
--progress show progress during transfer
-P same as --partial --progress
dit(bf(-a, --archive)) This is equivalent to bf(-rlptgoD). It is a quick
way of saying you want recursion and want to preserve almost
-everything. The only exception to this is if bf(--files-from) was
+everything (with -H being a notable omission).
+The only exception to the above equivalence is when bf(--files-from) is
specified, in which case bf(-r) is not implied.
Note that bf(-a) bf(does not preserve hardlinks), because
finding multiply-linked files is expensive. You must separately
specify bf(-H).
+dit(--no-OPTION) You may turn off one or more implied options by prefixing
+the option name with "no-". Not all options may be prefixed with a "no-":
+only options that are implied by other options (e.g. bf(--no-D),
+bf(--no-perms)) or have different defaults in various circumstances
+(e.g. bf(--no-whole-file), bf(--no-blocking-io), bf(--no-dirs)). You may
+specify either the short or the long option name after the "no-" prefix
+(e.g. bf(--no-R) is the same as bf(--no-relative)).
+
+For example: if you want to use bf(-a) (bf(--archive)) but don't want
+bf(-o) (bf(--owner)), instead of converting bf(-a) into bf(-rlptgD), you
+could specify bf(-a --no-o) (or bf(-a --no-owner)).
+
+The order of the options is important: if you specify bf(--no-r -a), the
+bf(-r) option would end up being turned on, the opposite of bf(-a --no-r).
+Note also that the side-effects of the bf(--files-from) option are NOT
+positional, as it affects the default state of several options and sligntly
+changes the meaning of bf(-a) (see the bf(--files-from) option for more
+details).
+
dit(bf(-r, --recursive)) This tells rsync to copy directories
recursively. See also bf(--dirs) (bf(-d)).
names specified on the command line are sent to the server rather than
just the last parts of the filenames. This is particularly useful when
you want to send several different directories at the same time. For
-example, if you used the command
+example, if you used this command:
-quote(tt( rsync /foo/bar/foo.c remote:/tmp/))
+quote(tt( rsync -av /foo/bar/baz.c remote:/tmp/))
-then this would create a file called foo.c in /tmp/ on the remote
+... this would create a file called baz.c in /tmp/ on the remote
machine. If instead you used
-quote(tt( rsync -R /foo/bar/foo.c remote:/tmp/))
+quote(tt( rsync -avR /foo/bar/baz.c remote:/tmp/))
-then a file called /tmp/foo/bar/foo.c would be created on the remote
+then a file called /tmp/foo/bar/baz.c would be created on the remote
machine -- the full path name is preserved. To limit the amount of
-path information that is sent, do something like this:
+path information that is sent, you have a couple options: (1) With
+a modern rsync on the sending side (beginning with 2.6.7), you can
+insert a dot dir into the source path, like this:
-quote(
-tt( cd /foo)nl()
-tt( rsync -R bar/foo.c remote:/tmp/)nl()
-)
+quote(tt( rsync -avR /foo/./bar/baz.c remote:/tmp/))
-That would create /tmp/bar/foo.c on the remote machine.
+That would create /tmp/bar/baz.c on the remote machine. (Note that the
+dot dir must followed by a slash, so "/foo/." would not be abbreviated.)
+(2) For older rsync versions, you would need to use a chdir to limit the
+source path. For example, when pushing files:
-dit(bf(--no-relative)) Turn off the bf(--relative) option. This is only
-needed if you want to use bf(--files-from) without its implied bf(--relative)
-file processing.
+quote(tt( (cd /foo; rsync -avR bar/baz.c remote:/tmp/) ))
+
+(Note that the parens put the two commands into a sub-shell, so that the
+"cd" command doesn't remain in effect for future commands.)
+If you're pulling files, use this idiom (which doesn't work with an
+rsync daemon):
+
+quote(
+tt( rsync -avR --rsync-path="cd /foo; rsync" \ )nl()
+tt( remote:bar/baz.c /tmp/)
+)
dit(bf(--no-implied-dirs)) When combined with the bf(--relative) option, the
implied directories in each path are not explicitly duplicated as part
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 mismatched data.
+Only files on the receiving side that are shorter than the corresponding
+file on the sending side (as well as new files) are sent.
+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
name with a trailing slash (e.g. "foo/"). Without this option or the
bf(--recursive) option, rsync will skip all directories it encounters (and
-output a message to that effect for each one).
+output a message to that effect for each one). If you specify both
+bf(--dirs) and bf(--recursive), the latter takes precedence.
dit(bf(-l, --links)) When symlinks are encountered, recreate the
symlink on the destination.
"disk" is actually a networked filesystem). This is the default when both
the source and destination are specified as local paths.
-dit(bf(--no-whole-file)) Turn off bf(--whole-file), for use when it is the
-default.
-
dit(bf(-p, --perms)) This option causes rsync to set the destination
permissions to be the same as the source permissions.
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:
quote(itemize(
it() The bf(--relative) (bf(-R)) option is implied, which preserves the path
information that is specified for each item in the file (use
- bf(--no-relative) if you want to turn that off).
+ bf(--no-relative) or bf(--no-R) if you want to turn that off).
it() The bf(--dirs) (bf(-d)) option is implied, which will create directories
specified in the list on the destination rather than noisily skipping
- them.
+ them (use bf(--no-dirs) or bf(--no-d) if you want to turn that off).
it() The bf(--archive) (bf(-a)) option's behavior does not imply bf(--recursive)
(bf(-r)), so specify it explicitly, if you want it.
+ it() These side-effects change the default state of rsync, so the position
+ of the bf(--files-from) option on the command-line has no bearing on how
+ other options are parsed (e.g. bf(-a) works the same before or after
+ bf(--files-from), as does bf(--no-R) and all other options).
))
The file names that are read from the FILE are all relative to the
blocking I/O, otherwise it defaults to using non-blocking I/O. (Note that
ssh prefers non-blocking I/O.)
-dit(bf(--no-blocking-io)) Turn off bf(--blocking-io), for use when it is the
-default.
-
dit(bf(-i, --itemize-changes)) Requests a simple itemized list of the
changes that are being made to each file, including attribute changes.
This is exactly the same as specifying bf(--log-format='%i %n%L').
manpagesection(VERSION)
-This man page is current for version 2.6.6pre1 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