mailto(rsync-bugs@samba.org)
-manpage(rsync)(1)(25 Jan 2002)()()
+manpage(rsync)(1)(26 Jan 2003)()()
manpagename(rsync)(faster, flexible replacement for rcp)
manpagesynopsis()
rsync [OPTION]... rsync://[USER@]HOST[:PORT]/SRC [DEST]
+rsync [OPTION]... SRC [SRC]... rsync://[USER@]HOST[:PORT]/DEST
+
manpagedescription()
rsync is a program that behaves in much the same way that rcp does,
exists.
The rsync remote-update protocol allows rsync to transfer just the
-differences between two sets of files across the network link, using
+differences between two sets of files across the network connection, using
an efficient checksum-search algorithm described in the technical
report that accompanies this package.
manpagesection(GENERAL)
-There are six different ways of using rsync. They are:
+There are eight different ways of using rsync. They are:
itemize(
it() for copying local files. This is invoked when neither
it() for copying from the local machine to a remote rsync
server. This is invoked when the destination path contains a ::
- separator.
+ separator or a 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 --rsh=COMMAND (aka "-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
+ --rsh=COMMMAND 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
See the file README for installation instructions.
-Once installed you can use rsync to any machine that you can use rsh
-to. rsync uses rsh for its communications, unless both the source and
-destination are local.
+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, rsync typically uses rsh
+for its communications, but it may have been configured to use a
+different remote shell by default, such as ssh.
-You can also specify an alternative to rsh, either by using the -e
+You can also specify any remote shell you like, either by using the -e
command line option, or by setting the RSYNC_RSH environment variable.
One common substitute is to use ssh, which offers a high degree of
manpagesection(CONNECTING TO AN RSYNC SERVER)
-It is also possible to use rsync without using rsh or ssh as the
+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.
your web proxy. Note that your web proxy's configuration must allow
proxying to port 873.
-Using rsync in this way is the same as using it with rsh or ssh except
+Using rsync in this way is the same as using it with a remote shell except
that:
itemize(
it() you use a double colon :: instead of a single colon to
- separate the hostname from the path.
+ separate the hostname from the path or a rsync:// URL.
it() the remote server may print a message of the day when you
connect.
WARNING: On some systems environment variables are visible to all
users. On those systems using --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 rsh or
+ssh 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
+--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:
+
+quote(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)
-An rsync server is configured using a config file which by default is
-called /etc/rsyncd.conf. Please see the rsyncd.conf(5) man page for more
-information.
+An rsync server is configured using a config 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(RUNNING AN RSYNC SERVER OVER A REMOTE SHELL PROGRAM)
+
+See the rsyncd.conf(5) man page for full information on the rsync
+server 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.
+
+To run an rsync server out of a single-use ssh key, use the
+"command=em(COMMAND)" syntax in the remote user's
+authorized_keys entry, where command would be
+
+quote(rsync --server --daemon .)
+
+NOTE: rsync's argument parsing expects the trailing ".", so make sure
+that it's there. If you want to use a rsyncd.conf(5)-style
+configuration file other than the default, you can added a
+--config option to the em(command):
+
+quote(rsync --server --daemon --config=em(file) .)
manpagesection(EXAMPLES)
quote(rsync -Cavz . arvidsjaur:backup)
-each night over a PPP link to a duplicate directory on my machine
+each night over a PPP connection to a duplicate directory on my machine
"arvidsjaur".
To synchronize my samba source trees I use the following Makefile
sync: get put)
this allows me to sync with a CVS directory at the other end of the
-link. I then do cvs operations on the remote machine, which saves a
+connection. I then do cvs operations on the remote machine, which saves a
lot of time as the remote cvs protocol isn't very efficient.
I mirror a directory between my "old" and "new" ftp sites with the
-v, --verbose increase verbosity
-q, --quiet decrease verbosity
-c, --checksum always checksum
- -a, --archive archive mode
+ -a, --archive archive mode, equivalent to -rlptgoD
-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
-b, --backup make backups (default ~ suffix)
--backup-dir make backups into this directory
- --suffix=SUFFIX override backup suffix
+ --suffix=SUFFIX define backup suffix
-u, --update update only (don't overwrite newer files)
-l, --links copy symlinks as symlinks
-L, --copy-links copy the referent of symlinks
--no-whole-file turn off --whole-file
-x, --one-file-system don't cross filesystem boundaries
-B, --block-size=SIZE checksum blocking size (default 700)
- -e, --rsh=COMMAND specify rsh replacement
+ -e, --rsh=COMMAND specify the remote shell to use
--rsync-path=PATH specify path to rsync on the remote machine
- -C, --cvs-exclude auto ignore files in the same way CVS does
--existing only update files that already exist
--ignore-existing ignore files that already exist on the receiving side
--delete delete files that don't exist on the sending side
--modify-window=NUM Timestamp window (seconds) for file match (default=0)
-T --temp-dir=DIR create temporary files in directory DIR
--compare-dest=DIR also compare destination files relative to DIR
+ --link-dest=DIR create hardlinks to DIR for unchanged files
-P equivalent to --partial --progress
-z, --compress compress file data
+ -C, --cvs-exclude auto ignore files in the same way CVS does
--exclude=PATTERN exclude files matching PATTERN
--exclude-from=FILE exclude patterns listed in FILE
--include=PATTERN don't exclude files matching PATTERN
--include-from=FILE don't exclude patterns listed in FILE
+ --files-from=FILE read FILE for list of source-file names
+ -0 --from0 file names we read are separated by nulls, not newlines
--version print version number
--daemon run as a rsync daemon
--no-detach do not detach from the parent
the timestamps as being equal if they are within the value of
modify_window. This is normally zero, but you may find it useful to
set this to a larger value in some situations. In particular, when
-transferring to/from FAT filesystems which cannot represent times with
-a 1 second resolution this option is useful.
+transferring to Windows FAT filesystems which cannot represent times
+with a 1 second resolution --modify-window=1 is useful.
dit(bf(-c, --checksum)) This forces the sender to checksum all files using
a 128-bit MD4 checksum before transfer. The checksum is then
verb(rsync -R foo/bar/foo.c remote:/tmp/)
then a file called /tmp/foo/bar/foo.c would be created on the remote
-machine. The full path name is preserved.
+machine -- the full path name is preserved.
+
+dit(bf(--no-relative)) Turn off the --relative option. This is only
+needed if you want to use --files-from without its implied --relative
+file processing.
+
+dit(bf(--no-implied-dirs)) When combined with the --relative option, the
+implied directories in each path are not explicitly duplicated as part
+of the transfer. This makes the transfer more optimal and also allows
+the two sides to have non-matching symlinks in the implied part of the
+path. For instance, if you transfer the file "/path/foo/file" with -R,
+the default is for rsync to ensure that "/path" and "/path/foo" on the
+destination exactly match the directories/symlinks of the source. Using
+the --no-implied-dirs option would omit both of these implied dirs,
+which means that if "/path" was a real directory on one machine and a
+symlink of the other machine, rsync would not try to change this.
dit(bf(-b, --backup)) With this option preexisting destination files are
renamed with a ~ extension as each file is transferred. You can
dit(bf(--backup-dir=DIR)) In combination with the --backup option, this
tells rsync to store all backups in the specified directory. This is
-very useful for incremental backups.
+very useful for incremental backups. You can additionally
+specify a backup suffix using the --suffix option
+(otherwise the files backed up in the specified directory
+will keep their original filenames).
dit(bf(--suffix=SUFFIX)) This option allows you to override the default
backup suffix used with the -b option. The default is a ~.
+If --backup-dir and --suffix are both specified,
+the SUFFIX is appended to the filename even in the backup directory.
dit(bf(-u, --update)) This forces rsync to skip any files for which the
destination file already exists and has a date later than the source
dit(bf(-o, --owner)) This option causes rsync to set the owner of the
destination file to be the same as the source file. On most systems,
-only the super-user can set file ownership.
+only the super-user can set file ownership. Note that if the remote system
+is a daemon using chroot, the --numeric-ids option is implied because the
+remote system cannot get access to the usernames from /etc/passwd.
dit(bf(-g, --group)) This option causes rsync to set the group of the
destination file to be the same as the source file. If the receiving
dit(bf(-e, --rsh=COMMAND)) This option allows you to choose an alternative
remote shell program to use for communication between the local and
-remote copies of rsync. By default, rsync will use rsh, but you may
-like to instead use ssh because of its high security.
+remote copies of rsync. Typically, rsync is configured to use rsh by
+default, but you may prefer to use ssh because of its high security.
+
+If this option is used with bf([user@]host::module/path), then the
+remote shell em(COMMMAND) will be used to run an rsync server 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.
+
+Command-line arguments are permitted in COMMAND provided that COMMAND is
+presented to rsync as a single argument. For example:
+
+quote(-e "ssh -p 2234")
+
+(Note that ssh users can alternately customize site-specific connect
+options in their .ssh/config file.)
You can also choose the remote shell program using the RSYNC_RSH
-environment variable.
+environment variable, which accepts the same range of values as -e.
See also the --blocking-io option which is affected by this option.
that this is the full path to the binary, not just the directory that
the binary is in.
+dit(bf(-C, --cvs-exclude)) This is a useful shorthand for excluding a
+broad range of files that you often don't want to transfer between
+systems. It uses the same algorithm that CVS uses to determine if
+a file should be ignored.
+
+The exclude list is initialized to:
+
+quote(RCS/ SCCS/ CVS/ .svn/ CVS.adm RCSLOG cvslog.* tags TAGS .make.state
+.nse_depinfo *~ #* .#* ,* *.old *.bak *.BAK *.orig *.rej .del-*
+*.a *.o *.obj *.so *.Z *.elc *.ln core)
+
+then files listed in a $HOME/.cvsignore are added to the list and any
+files listed in the CVSIGNORE environment variable (space delimited).
+
+Finally, any file is ignored if it is in the same directory as a
+.cvsignore file and matches one of the patterns listed therein. See
+the bf(cvs(1)) manual for more information.
+
dit(bf(--exclude=PATTERN)) This option allows you to selectively exclude
certain files from the list of files to be transferred. This is most
useful in combination with a recursive transfer.
option, but instead it adds all exclude patterns listed in the file
FILE to the exclude list. Blank lines in FILE and lines starting with
';' or '#' are ignored.
+If em(FILE) is bf(-) the list will be read from standard input.
dit(bf(--include=PATTERN)) This option tells rsync to not exclude the
specified pattern of filenames. This is useful as it allows you to
dit(bf(--include-from=FILE)) This specifies a list of include patterns
from a file.
-
-dit(bf(-C, --cvs-exclude)) This is a useful shorthand for excluding a
-broad range of files that you often don't want to transfer between
-systems. It uses the same algorithm that CVS uses to determine if
-a file should be ignored.
-
-The exclude list is initialized to:
-
-quote(RCS SCCS CVS CVS.adm RCSLOG cvslog.* tags TAGS .make.state
-.nse_depinfo *~ #* .#* ,* *.old *.bak *.BAK *.orig *.rej .del-*
-*.a *.o *.obj *.so *.Z *.elc *.ln core)
-
-then files listed in a $HOME/.cvsignore are added to the list and any
-files listed in the CVSIGNORE environment variable (space delimited).
-
-Finally, any file is ignored if it is in the same directory as a
-.cvsignore file and matches one of the patterns listed therein. See
-the bf(cvs(1)) manual for more information.
-
-dit(bf(--csum-length=LENGTH)) By default the primary checksum used in
-rsync is a very strong 16 byte MD4 checksum. In most cases you will
-find that a truncated version of this checksum is quite efficient, and
-this will decrease the size of the checksum data sent over the link,
-making things faster.
-
-You can choose the number of bytes in the truncated checksum using the
---csum-length option. Any value less than or equal to 16 is valid.
-
-Note that if you use this option then you run the risk of ending up
-with an incorrect target file. The risk with a value of 16 is
-microscopic and can be safely ignored (the universe will probably end
-before it fails) but with smaller values the risk is higher.
-
-Current versions of rsync actually use an adaptive algorithm for the
-checksum length by default, using a 16 byte file checksum to determine
-if a 2nd pass is required with a longer block checksum. Only use this
-option if you have read the source code and know what you are doing.
+If em(FILE) is bf(-) the list will be read from standard input.
+
+dit(bf(--files-from=FILE)) Using this option allows you to specify the
+exact list of files to transfer (as read from the specified FILE or "-"
+for stdin). It also tweaks the default behavior of rsync to make
+transferring just the specified files and directories easier. For
+instance, the --relative option is enabled by default when this option
+is used (use --no-relative if you want to turn that off), all
+directories specified in the list are created on the destination (rather
+than being noisily skipped without -r), and the -a (--archive) option's
+behavior does not imply -r (--recursive) -- specify it explicitly, if
+you want it.
+
+The file names that are read from the FILE are all relative to the
+source dir -- any leading slashes are removed and no ".." references are
+allowed to go higher than the source dir. For example, take this
+command:
+
+quote(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 -r
+or the names were explicitly listed in /tmp/foo). Also keep in mind
+that the effect of the (enabled by default) --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).
+
+In addition, the --files-from file can be read from the remote host
+instead of the local host if you specify a "host:" in front of the file
+(the host must match one end of the transfer). As a short-cut, you can
+specify just a prefix of ":" to mean "use the remote end of the
+transfer". For example:
+
+quote(rsync -a --files-from=:/path/file-list src:/ /tmp/copy)
+
+This would copy all the files specified in the /path/file-list file that
+was located on the remote "src" host.
+
+dit(bf(-0, --from0)) This tells rsync that the filenames it reads from a
+file are terminated by a null ('\0') character, not a NL, CR, or CR+LF.
+This affects --exclude-from, --include-from, and --files-from.
dit(bf(-T, --temp-dir=DIR)) This option instructs rsync to use DIR as a
scratch directory when creating temporary copies of the files
dit(bf(--compare-dest=DIR)) This option instructs rsync to use DIR on
the destination machine as an additional directory to compare destination
-files against when doing transfers. This is useful for doing transfers to
-a new destination while leaving existing files intact, and then doing a
+files against when doing transfers if the files are missing in the
+destination directory. This is useful for doing transfers to a new
+destination while leaving existing files intact, and then doing a
flash-cutover when all files have been successfully transferred (for
example by moving directories around and removing the old directory,
-although this requires also doing the transfer with -I to avoid skipping
-files that haven't changed). This option increases the usefulness of
---partial because partially transferred files will remain in the new
-temporary destination until they have a chance to be completed. If DIR is
-a relative path, it is relative to the destination directory.
+although this skips files that haven't changed; see also --link-dest).
+This option increases the usefulness of --partial because partially
+transferred files will remain in the new temporary destination until they
+have a chance to be completed. If DIR is a relative path, it is relative
+to the destination directory.
+
+dit(bf(--link-dest=DIR)) This option behaves like bf(--compare-dest) but
+also will create hard links from em(DIR) to the destination directory for
+unchanged files. Files with changed ownership or permissions will not be
+linked.
dit(bf(-z, --compress)) With this option, rsync compresses any data from
the files that it sends to the destination machine. This
-option is useful on slow links. The compression method used is the
+option is useful on slow connections. The compression method used is the
same method that gzip uses.
Note this this option typically achieves better compression ratios
If standard input is a socket then rsync will assume that it is being
run via inetd, otherwise it will detach from the current terminal and
become a background daemon. The daemon will read the config file
-(/etc/rsyncd.conf) on each connect made by a client and respond to
+(rsyncd.conf) on each connect made by a client and respond to
requests accordingly. See the rsyncd.conf(5) man page for more
details.
in conjunction with the --config option.
dit(bf(--config=FILE)) This specifies an alternate config file than
-the default /etc/rsyncd.conf. This is only relevant when --daemon is
-specified.
+the default. This is only relevant when --daemon is specified.
+The default is /etc/rsyncd.conf unless the daemon is running over
+a remote shell program and the remote user is not root; in that case
+the default is rsyncd.conf in the current directory (typically $HOME).
dit(bf(--port=PORT)) This specifies an alternate TCP port number to use
rather than the default port 873.
a remote shell transport. If -e or --rsh are not specified or are set to
the default "rsh", this defaults to blocking IO, otherwise it defaults to
non-blocking IO. You may find the --blocking-io option is needed for some
-remote shells that can't handle non-blocking IO. Ssh prefers blocking IO.
+remote shells that can't handle non-blocking IO. (Note that ssh prefers
+non-blocking IO.)
dit(bf(--no-blocking-io)) Turn off --blocking-io, for use when it is the
default.
more details.
dit(bf(RSYNC_RSH)) The RSYNC_RSH environment variable allows you to
-override the default shell used as the transport for rsync. This can
-be used instead of the -e option.
+override the default shell used as the transport for rsync. Command line
+options are permitted after the command name, just as in the -e option.
dit(bf(RSYNC_PROXY)) The RSYNC_PROXY environment variable allows you to
redirect your rsync client to use a web proxy when connecting to a
manpagefiles()
-/etc/rsyncd.conf
+/etc/rsyncd.conf or rsyncd.conf
manpageseealso()
times are transferred as unix time_t values
+When transferring to FAT filesystmes rsync may resync
+unmodified files.
+See the comments on the --modify-window option.
+
file permissions, devices etc are transferred as native numerical
values
see also the comments on the --delete option
-Please report bugs! The rsync bug tracking system is online at
-url(http://rsync.samba.org/rsync/)(http://rsync.samba.org/rsync/)
-
-manpagesection(VERSION)
-This man page is current for version 2.0 of rsync
+Please report bugs! See the website at
+url(http://rsync.samba.org/)(http://rsync.samba.org/)
manpagesection(CREDITS)