mailto(rsync-bugs@samba.org)
-manpage(rsync)(1)(30 Mar 2005)()()
+manpage(rsync)(1)(28 Jul 2005)()()
manpagename(rsync)(faster, flexible replacement for rcp)
manpagesynopsis()
rsync [OPTION]... SRC [SRC]... [USER@]HOST:DEST
-rsync [OPTION]... [USER@]HOST:SRC DEST
+rsync [OPTION]... [USER@]HOST:SRC [DEST]
rsync [OPTION]... SRC [SRC]... DEST
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
+"USING RSYNC-DAEMON FEATURES VIA A REMOTE-SHELL CONNECTION" section for
+an exception to this latter rule).
-Note that in all cases (other than listing) at least one of the source
-and destination paths must be local.
+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).
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)
-
-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
-running on TCP port 873.
+manpagesection(CONNECTING TO AN RSYNC DAEMON)
-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 remote server may print a message of the day when you
+ 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 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
+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 SERVER 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
-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,
-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
-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:
+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 SERVER)
-
-An rsync server 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).
+used to log-in to the "module".
-manpagesection(RUNNING AN RSYNC SERVER OVER A REMOTE SHELL PROGRAM)
+manpagesection(STARTING AN RSYNC DAEMON TO ACCEPT CONNECTIONS)
-See the rsyncd.conf(5) man page for full information on the rsync
-server configuration file.
+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).
-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.
-
-To run an rsync server 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
--include-from=FILE read include patterns from FILE
--files-from=FILE read list of source-file names from FILE
-0, --from0 all *from/filter files are delimited by 0s
- --version print version number
--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
--progress show progress during transfer
-P same as --partial --progress
-i, --itemize-changes output a change-summary for all updates
- --log-format=FORMAT log file-transfers using specified format
+ --log-format=FORMAT output filenames using the specified format
--password-file=FILE read password from FILE
--list-only list the files instead of copying them
--bwlimit=KBPS limit I/O bandwidth; KBytes per second
--checksum-seed=NUM set block/file checksum seed (advanced)
-4, --ipv4 prefer IPv4
-6, --ipv6 prefer IPv6
+ --version print version number
-h, --help show this help screen)
Rsync can also be run as a daemon, in which case the following options are
Note that the names of the transferred files that are output are done using
a default bf(--log-format) of "%n%L", which tells you just the name of the
-file and, if the item is a symlink, where it points. At the single bf(-v)
+file and, if the item is a link, where it points. At the single bf(-v)
level of verbosity, this does not mention when a file gets its attributes
changed. If you ask for an itemized list of changed attributes (either
bf(--itemize-changes) or adding "%i" to the bf(--log-format) setting), the
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
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 "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(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).
a "." for no change. Three exceptions to this are: (1) a newly created
item replaces each letter with a "+", (2) an identical item replaces the
dots with spaces, and (3) an unknown attribute replaces each letter with
-a "?" (this happens when talking to an older rsync).
+a "?" (this can happen when talking to an older rsync).
The attribute that is associated with each letter is as follows:
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.
))
in a significant way (a transferred file, a recreated symlink/device, or a
touched directory) unless the itemized-changes escape (%i) is included in
the string, in which case the logging of names increases to mention any
-item that is updated in any way (as long as the receiving side is version
+item that is changed in any way (as long as the receiving side is at least
2.6.4). See the bf(--itemized-changes) option for a description of the
output of "%i".
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
is useful for creating a batch file that is compatible with an older
version of rsync. For instance, if rsync 2.6.4 is being used with the
bf(--write-batch) option, but rsync 2.6.3 is what will be used to run the
-bf(--read-batch) option, you should use "--protocol=28" (when creating the
-batch file) to force the older protocol version to be used in the batch
-file (assuming you can't upgrade the rsync on the reading system to 2.6.4).
+bf(--read-batch) option, you should use "--protocol=28" when creating the
+batch file to force the older protocol version to be used in the batch
+file (assuming you can't upgrade the rsync on the reading system).
dit(bf(-4, --ipv4) or bf(-6, --ipv6)) Tells rsync to prefer IPv4/IPv6
when creating sockets. This only affects sockets that rsync has direct
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.6 of rsync.
+
manpagesection(CREDITS)
rsync is distributed under the GNU public license. See the file
Matt McCutchen's Web Site / rsync / rsync.git / blobdiff