mailto(rsync-bugs@samba.anu.edu.au)
-manpage(rsync)(1)(13 May 1998)()()
+manpage(rsync)(1)(11 Nov 1998)()()
manpagename(rsync)(faster, flexible replacement for rcp)
manpagesynopsis()
rsync [options] path path
-rsync [options] [user@]host::path path
+rsync [options] [user@]host::module[/path] path
-rsync [options] path [user@]host::path
+rsync [options] path [user@]host::module[/path]
+
+rsync [options] rsync://[user@]host[:port]/module/path path
manpagedescription()
manpagesection(GENERAL)
-There are five different ways of using rsync. They are:
+There are six different ways of using rsync. They are:
itemize(
it() for copying local files. This is invoked when neither
it() for copying from a remote rsync server to the local
machine. This is invoked when the source path contains a ::
- separator.
+ separator or a rsync:// URL.
it() for copying from the local machine to a remote rsync
server. This is invoked when the destination path contains a ::
separator.
+
+ 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.
)
-Note that in all cases at least one of the source and destination
-paths must be local.
+Note that in all cases (other than listing) at least one of the source
+and destination paths must be local.
manpagesection(SETUP)
to. rsync uses rsh for its communications, unless both the source and
destination are local.
-You can also specify a alternative to rsh, by either using the -e
+You can also specify an alternative to rsh, by either 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
security.
+Note that rsync must be installed on both the source and destination
+machines.
+
manpagesection(USAGE)
You use rsync in the same way you use rcp. You must specify a source
quote(rsync -avz foo:src/bar /data/tmp)
-recursively transfer all files from the directory src/bar on the
+this would recursively transfer all files from the directory src/bar on the
machine foo into the /data/tmp/bar directory on the local machine. The
files are transferred in "archive" mode, which ensures that symbolic
links, devices, attributes, permissions, ownerships etc are preserved
-in the transfer. Additionally compression will be used to reduce the
+in the transfer. Additionally, compression will be used to reduce the
size of data portions of the transfer.
quote(rsync -avz foo:src/bar/ /data/tmp)
-With a trailing slash on the source this behavior changes to transfer
+a trailing slash on the source changes this behavior to transfer
all files from the directory src/bar on the machine foo into the
-/data/tmp/. With a trailing / on a source name it means "copy the
+/data/tmp/. A trailing / on a source name means "copy the
contents of this directory". Without a trailing slash it means "copy
the directory". This difference becomes particularly important when
using the --delete option.
destination don't have a ':' in the name. In this case it behaves like
an improved copy command.
+quote(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.)
+
manpagesection(CONNECTING TO AN RSYNC SERVER)
transport. In this case you will connect to a remote rsync server
running on TCP port 873.
-Using rsync in this was is the same as using it with rsh or ssh except
+Using rsync in this way is the same as using it with rsh or ssh except
that:
itemize(
separate the hostname from the path.
it() the remote server may print a message of the day when you
- connect
+ 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 local destination then a listing of the
+ specified files on the remote server is provided.
)
Some paths on the remote server may require authentication. If so then
Here are some examples of how I use rsync.
-To backup my wife's home directory, which consists of large MS word
-files and mail folders I use a cron job that runs
+To backup my wife's home directory, which consists of large MS Word
+files and mail folders, I use a cron job that runs
quote(rsync -Cavz . arvidsjaur:backup)
this is launched from cron every few hours.
+manpagesection(OPTIONS SUMMARY)
+
+Here is a short summary of the options available in rsync. Please refer
+to the detailed description below for a complete description.
+
+verb(
+Usage: rsync [OPTION]... SRC [USER@]HOST:DEST
+ or rsync [OPTION]... [USER@]HOST:SRC DEST
+ or rsync [OPTION]... SRC DEST
+ or rsync [OPTION]... [USER@]HOST::SRC [DEST]
+ or rsync [OPTION]... SRC [USER@]HOST::DEST
+ or rsync [OPTION]... rsync://[USER@]HOST[:PORT]/SRC [DEST]
+
+Options
+ -v, --verbose increase verbosity
+ -c, --checksum always checksum
+ -a, --archive archive mode
+ -r, --recursive recurse into directories
+ -R, --relative use relative path names
+ -b, --backup make backups (default ~ extension)
+ -u, --update update only (don't overwrite newer files)
+ -l, --links preserve soft links
+ -L, --copy-links treat soft links like regular files
+ --safe-links ignore links outside the destination tree
+ -H, --hard-links preserve hard links
+ -p, --perms preserve permissions
+ -o, --owner preserve owner (root only)
+ -g, --group preserve group
+ -D, --devices preserve devices (root only)
+ -t, --times preserve times
+ -S, --sparse handle sparse files efficiently
+ -n, --dry-run show what would have been transferred
+ -W, --whole-file copy whole files, no incremental checks
+ -x, --one-file-system don't cross filesystem boundaries
+ -B, --block-size=SIZE checksum blocking size
+ -e, --rsh=COMMAND specify rsh replacement
+ --rsync-path=PATH specify path to rsync on the remote machine
+ -C, --cvs-exclude auto ignore files in the same way CVS does
+ --delete delete files that don't exist on the sending side
+ --partial keep partially transferred files
+ --force force deletion of directories even if not empty
+ --numeric-ids don't map uid/gid values by user/group name
+ --timeout=TIME set IO timeout in seconds
+ -I, --ignore-times don't exclude files that match length and time
+ -T --temp-dir=DIR create temporary files in directory DIR
+ --compare-dest=DIR also compare destination files relative to DIR
+ -z, --compress compress file data
+ --exclude=PATTERN exclude files matching PATTERN
+ --exclude-from=FILE exclude files listed in FILE
+ --include=PATTERN don't exclude files matching PATTERN
+ --include-from=FILE don't exclude files listed in FILE
+ --suffix=SUFFIX override backup suffix
+ --version print version number
+ --daemon run as a rsync daemon
+ --config=FILE specify alternate rsyncd.conf file
+ --port=PORT specify alternate rsyncd port number
+ --stats give some file transfer stats
+ --progress show progress during transfer
+ --log-format=FORMAT log file transfers using specified format
+ -h, --help show this help screen
+)
+
manpageoptions()
rsync uses the GNU long options package. Many of the command line
options have two variants, one short and one long. These are shown
-below separated by commas. Some options only have a long variant.
+below, separated by commas. Some options only have a long variant.
startdit()
dit(bf(-h, --help)) Print a short help page describing the options
dit(bf(--version)) print the rsync version number and exit
dit(bf(-v, --verbose)) This option increases the amount of information you
-are given during the transfer. By default rsync works silently. A
+are given during the transfer. By default, rsync works silently. A
single -v will give you information about what files are being
transferred and a brief summary at the end. Two -v flags will give you
information on what files are being skipped and slightly more
information at the end. More than two -v flags should only be used if
-you are debugging rsync
+you are debugging rsync.
dit(bf(-I, --ignore-times)) Normally rsync will skip any files that are
already the same length and have the same time-stamp. This option turns
which already exist and have the same checksum and size on the
receiver are skipped. This option can be quite slow.
-dit(bf(-a, --archive)) This is equivalent to -rlptDog. It is a quick way
-of saying I want recursion and want to preserve everything.
+dit(bf(-a, --archive)) This is equivalent to -rlptDg. It is a quick way
+of saying you want recursion and want to preserve everything.
+
+Note: if the user launching rsync is root then the -o option (preserve
+uid) is also implied.
-dit(bf(-r, --recursive)) This tells rsync to copy directories recursively
+dit(bf(-r, --recursive)) This tells rsync to copy directories recursively.
dit(bf(-R, --relative)) Use relative paths. This means that the full path
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 sent several different directories at the same time. For
-example if you used the command
+you want to send several different directories at the same time. For
+example, if you used the command
verb(rsync foo/bar/foo.c remote:/tmp/)
dit(bf(-l, --links)) This tells rsync to recreate symbolic links on the
remote system to be the same as the local system. Without this
-option all symbolic links are skipped.
+option, all symbolic links are skipped.
dit(bf(-L, --copy-links)) This tells rsync to treat symbolic links just
like ordinary files.
+dit(bf(--safe-links)) This tells rsync to ignore any symbolic links
+which point outside the destination tree. All absolute symlinks are
+also ignored. Using this option in conjunction with --relative may
+give unexpected results.
+
dit(bf(-H, --hard-links)) This tells rsync to recreate hard links on
the remote system to be the same as the local system. Without this
option hard links are treated like regular files.
is not used and the whole file is sent as-is instead. This may be
useful when using rsync with a local machine.
+dit(bf(--partial)) By default, rsync will delete any partially
+transferred file if the transfer is interrupted. In some circumstances
+it is more desirable to keep partially transferred files. Using the
+--partial option tells rsync to keep the partial file which should
+make a subsequent transfer of the rest of the file much faster.
+
dit(bf(-p, --perms)) This option causes rsync to update the remote
permissions to be the same as the local permissions.
dit(bf(-o, --owner)) This option causes rsync to update the remote owner
of the file to be the same as the local owner. This is only available
-to the super-user.
+to the super-user. Note that if the source system is a daemon using chroot,
+the --numeric-ids option is implied because the source system cannot get
+access to the usernames.
dit(bf(-g, --group)) This option causes rsync to update the remote group
-of the file to be the same as the local group.
+of the file to be the same as the local group. Note that if the source
+system is a daemon using chroot, the --numeric-ids option is implied because
+the source system cannot get access to the group names.
dit(bf(-D, --devices)) This option causes rsync to transfer character and
block device information to the remote system to recreate these
devices. This option is only available to the super-user.
dit(bf(-t, --times)) This tells rsync to transfer modification times along
-with the files and update them on the remote system
+with the files and update them on the remote system. Note that if this
+option is not used, the optimization that excludes files that have not been
+modified cannot be effective; in other words, a missing -t or -a will
+cause the next transfer to behave as if it used -I, and all files will have
+their checksums compared and show up in log messages even if they haven't
+changed.
dit(bf(-n, --dry-run)) This tells rsync to not do any file transfers,
instead it will just report the actions it would have taken.
dit(bf(-S, --sparse)) Try to handle sparse files efficiently so they take
up less space on the destination.
+NOTE: Don't use this option when the destination is a Solaris "tmpfs"
+filesystem. It doesn't seem to handle seeks over null regions
+correctly and ends up corrupting the files.
+
dit(bf(-x, --one-file-system)) This tells rsync not to cross filesystem
boundaries when recursing. This is useful for transferring the
contents of only one filesystem.
of the story is to use the -n option until you get used to the
behavior of --delete.
-NOTE: It also may delete files on the destination if the sending side
-can't open them or stat them. This is a bug that hopefully will be
-fixed in a future release.
+If the sending side detects any IO errors then the deletion of any
+files at the destination will be automatically disabled. This is to
+prevent temporary filesystem failures (such as NFS errors) on the
+sending side causing a massive deletion of files on the
+destination.
dit(bf(--force)) This options tells rsync to delete directories even if
they are not empty. This applies to both the --delete option and to
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
+remote copies of rsync. By default, rsync will use rsh, but you may
like to instead use ssh because of its high security.
You can also choose the remote shell program using the RSYNC_RSH
environment variable.
dit(bf(--rsync-path PATH)) Use this to specify the path to the copy of
-rsync on the remote machine. Useful when its not in your path.
+rsync on the remote machine. Useful when it's not in your path.
-dit(bf(--exclude FILE)) This option allows you to selectively exclude
+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.
-The option FILE can either be a file name or a shell wildcard
-expression. If it is a directory name then rsync will not recurse into
-directories of that name.
-
You may use as many --exclude options on the command line as you like
to build up the list of files to exclude.
-If the filename is a single ! then the exclude list is reset.
+See the section on exclude patterns for information on the syntax of
+this option.
dit(bf(--exclude-from FILE)) This option is similar to the --exclude
option, but instead it adds all filenames listed in the file FILE to
the exclude list.
+dit(bf(--include pattern)) This option tells rsync to not exclude the
+specified pattern of filenames. This is useful as it allows you to
+build up quite complex exclude/include rules.
+
+See the section of exclude patterns for information on the syntax of
+this option.
+
+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
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.
+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.
microscopic and can be safely ignored (the universe will probably end
before it fails) but with smaller values the risk is higher.
-dit(bf(-T, --temp-dir DIR)) This options instructs rsync to use DIR as a
-scratch directory when creating a temporary copies of the files
+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.
+
+dit(bf(-T, --temp-dir DIR)) This option instructs rsync to use DIR as a
+scratch directory when creating temporary copies of the files
transferred on the receiving side. The default behavior is to create
the temporary files in the receiving directory.
+dit(bf(--compare-dest DIR)) This option instructs rsync to use DIR 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 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.
+
dit(bf(-z, --compress)) With this option, rsync compresses any data from
the source file(s) which it sends to the destination machine. This
option is useful on slow links. The compression method used is the
By default rsync will use the user name and group name to determine
what ownership to give files. The special uid 0 and the special group
-0 and never mapped via user/group names even if the --numeric-ids
+0 are never mapped via user/group names even if the --numeric-ids
option is not specified.
-If a user or group name does not exist on the destination system then
-the numeric id from the source system is used instead.
+If the source system is a daemon using chroot, or if a user or group name
+does not exist on the destination system, then the numeric id from the
+source system is used instead.
-dit(bf(--timeout)) This option allows you to set a maximum IO timeout in
-seconds. If no data is transferred for the specified time then rsync
-will exit. The default is 0, which means no timeout.
+dit(bf(--timeout=TIMEOUT)) This option allows you to set a maximum IO
+timeout in seconds. If no data is transferred for the specified time
+then rsync will exit. The default is 0, which means no timeout.
dit(bf(--daemon)) This tells rsync that it is to run as a rsync
daemon. If standard input is a socket then rsync will assume that it
specified.
dit(bf(--port PORT)) This specifies an alternate TCP port number to use
-rather than the default port 873.
+rather than the default port 873.
+
+dit(bf(--log-format=FORMAT)) This allows you to specify exactly what the
+rsync client logs to stdout on a per-file basis. The log format is
+specified using the same format conventions as the log format option in
+rsyncd.conf.
+
+dit(bf(--stats)) This tells rsync to print a verbose set of statistics
+on the file transfer, allowing you to tell how effective the rsync
+algorithm is for your data. This option only works in conjunction with
+the -v (verbose) option.
+
+dit(bf(--progress)) This option tells rsync to print information
+showing the progress of the transfer. This gives a bored user
+something to watch.
+
+enddit()
+
+manpagesection(EXCLUDE PATTERNS)
+
+The exclude and include patterns specified to rsync allow for flexible
+selection of which files to transfer and which files to skip.
+
+rsync builds a ordered list of include/exclude options as specified on
+the command line. When a filename is encountered, rsync checks the
+name against each exclude/include pattern in turn. The first matching
+pattern is acted on. If it is an exclude pattern than that file is
+skipped. If it is an include pattern then that filename is not
+skipped. If no matching include/exclude pattern is found then the
+filename is not skipped.
+
+The patterns can take several forms. The rules are:
+
+itemize(
+ it() if the pattern starts with a / then it is matched against the
+ start of the filename, otherwise it is matched against the end of
+ the filename. Thus /foo would match a file called foo
+ at the base of the tree whereas foo would match any file
+ called foo anywhere in the tree.
+
+ it() if the pattern ends with a / then it will only match a
+ directory, not a file, link or device.
+
+ it() if the pattern contains a wildcard character from the set
+ *?[ then regular expression matching is applied using the
+ normal shell filename matching rules. Otherwise a simple string
+ match is used.
+
+ it() if the pattern contains a / (not counting a trailing /) then it
+ is matched against the full filename, including any leading
+ directory. If the pattern doesn't contain a / then it is matched
+ only against the final component of the filename.
+
+ it() if the pattern starts with "+ " (a plus followed by a space)
+ then it is always considered a include pattern, even if specified as
+ part of an exclude option. The "+ " part is discarded before matching.
+
+ it() if the pattern starts with "- " (a minus followed by a space)
+ then it is always considered a exclude pattern, even if specified as
+ part of an include option. The "- " part is discarded before matching.
+
+ it() if the pattern is a single exclamation mark ! then the current
+ exclude list is reset, removing all previous exclude patterns.
+)
+
+The +/- rules are most useful in exclude lists, allowing you to have a
+single exclude list that contains both include and exclude options.
+
+Here are some examples:
+
+itemize(
+ it() --exclude "*.o" would exclude all filenames matching *.o
+ it() --exclude "/foo" would exclude a file in the base directory called foo
+ it() --exclude "foo/" would exclude any directory called foo
+ it() --include "*/" --include "*.c" --exclude "*" would include all
+ directories and C source files.
+)
+
+manpagesection(DIAGNOSTICS)
+
+rsync occasionally produces error messages that may seem a little
+cryptic. The one that seems to cause the most confusion is "protocol
+version mismatch - is your shell clean?".
+
+This message is usually caused by your startup scripts or remote shell
+facility producing unwanted garbage on the stream that rsync is using
+for its transport. The way to diagnose this problem is to run your
+remote shell like this:
+
+verb(
+ rsh remotehost /bin/true > out.dat
+)
+
+then look at out.dat. If everything is working correctly then out.dat
+should be a zero length file. You you are getting the above error from
+rsync then you will probably find that out.dat contains some text or
+data. Look at the contents and try to work out what is producing
+it. The most common cause is incorrectly configured shell startup
+scripts (such as .cshrc or .profile) that contain output statements
+for non-interactive logins.
+
+manpagesection(ENVIRONMENT VARIABLES)
+
+startdit()
+
+dit(bf(CVSIGNORE)) The CVSIGNORE environment variable supplements any
+ignore patterns in .cvsignore files. See the --cvs-exclude option for
+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.
+
+dit(bf(RSYNC_PASSWORD)) Setting RSYNC_PASSWORD to the required
+password allows you to run authenticated rsync connections to a rsync
+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 a rsync server.
+
+dit(bf(HOME)) The HOME environment variable is used to find the user's
+default .cvsignore file.
enddit()
file permissions, devices etc are transferred as native numerical
values
-see also the comments on the -delete option
+see also the comments on the --delete option
Please report bugs! The rsync bug tracking system is online at
url(http://samba.anu.edu.au/rsync/)(http://samba.anu.edu.au/rsync/)