1 mailto(rsync-bugs@samba.org)
2 manpage(rsync)(1)(25 Jan 2002)()()
3 manpagename(rsync)(faster, flexible replacement for rcp)
6 rsync [OPTION]... SRC [SRC]... [USER@]HOST:DEST
8 rsync [OPTION]... [USER@]HOST:SRC DEST
10 rsync [OPTION]... SRC [SRC]... DEST
12 rsync [OPTION]... [USER@]HOST::SRC [DEST]
14 rsync [OPTION]... SRC [SRC]... [USER@]HOST::DEST
16 rsync [OPTION]... rsync://[USER@]HOST[:PORT]/SRC [DEST]
20 rsync is a program that behaves in much the same way that rcp does,
21 but has many more options and uses the rsync remote-update protocol to
22 greatly speed up file transfers when the destination file already
25 The rsync remote-update protocol allows rsync to transfer just the
26 differences between two sets of files across the network link, using
27 an efficient checksum-search algorithm described in the technical
28 report that accompanies this package.
30 Some of the additional features of rsync are:
33 it() support for copying links, devices, owners, groups and permissions
34 it() exclude and exclude-from options similar to GNU tar
35 it() a CVS exclude mode for ignoring the same files that CVS would ignore
36 it() can use any transparent remote shell, including rsh or ssh
37 it() does not require root privileges
38 it() pipelining of file transfers to minimize latency costs
39 it() support for anonymous or authenticated rsync servers (ideal for
43 manpagesection(GENERAL)
45 There are six different ways of using rsync. They are:
48 it() for copying local files. This is invoked when neither
49 source nor destination path contains a : separator
51 it() for copying from the local machine to a remote machine using
52 a remote shell program as the transport (such as rsh or
53 ssh). This is invoked when the destination path contains a
56 it() for copying from a remote machine to the local machine
57 using a remote shell program. This is invoked when the source
58 contains a : separator.
60 it() for copying from a remote rsync server to the local
61 machine. This is invoked when the source path contains a ::
62 separator or a rsync:// URL.
64 it() for copying from the local machine to a remote rsync
65 server. This is invoked when the destination path contains a ::
68 it() for listing files on a remote machine. This is done the
69 same way as rsync transfers except that you leave off the
73 Note that in all cases (other than listing) at least one of the source
74 and destination paths must be local.
78 See the file README for installation instructions.
80 Once installed, you can use rsync to any machine that you can access via
81 a remote shell (as well as some that you can access using the rsync
82 daemon-mode protocol). For remote transfers, rsync typically uses rsh
83 for its communications, but it may have been configured to use a
84 different remote shell by default, such as ssh.
86 You can also specify any remote shell you like, either by using the -e
87 command line option, or by setting the RSYNC_RSH environment variable.
89 One common substitute is to use ssh, which offers a high degree of
92 Note that rsync must be installed on both the source and destination
97 You use rsync in the same way you use rcp. You must specify a source
98 and a destination, one of which may be remote.
100 Perhaps the best way to explain the syntax is some examples:
102 quote(rsync *.c foo:src/)
104 this would transfer all files matching the pattern *.c from the
105 current directory to the directory src on the machine foo. If any of
106 the files already exist on the remote system then the rsync
107 remote-update protocol is used to update the file by sending only the
108 differences. See the tech report for details.
110 quote(rsync -avz foo:src/bar /data/tmp)
112 this would recursively transfer all files from the directory src/bar on the
113 machine foo into the /data/tmp/bar directory on the local machine. The
114 files are transferred in "archive" mode, which ensures that symbolic
115 links, devices, attributes, permissions, ownerships etc are preserved
116 in the transfer. Additionally, compression will be used to reduce the
117 size of data portions of the transfer.
119 quote(rsync -avz foo:src/bar/ /data/tmp)
121 a trailing slash on the source changes this behavior to transfer
122 all files from the directory src/bar on the machine foo into the
123 /data/tmp/. A trailing / on a source name means "copy the
124 contents of this directory". Without a trailing slash it means "copy
125 the directory". This difference becomes particularly important when
126 using the --delete option.
128 You can also use rsync in local-only mode, where both the source and
129 destination don't have a ':' in the name. In this case it behaves like
130 an improved copy command.
132 quote(rsync somehost.mydomain.com::)
134 this would list all the anonymous rsync modules available on the host
135 somehost.mydomain.com. (See the following section for more details.)
138 manpagesection(CONNECTING TO AN RSYNC SERVER)
140 It is also possible to use rsync without a remote shell as the
141 transport. In this case you will connect to a remote rsync server
142 running on TCP port 873.
144 You may establish the connection via a web proxy by setting the
145 environment variable RSYNC_PROXY to a hostname:port pair pointing to
146 your web proxy. Note that your web proxy's configuration must allow
147 proxying to port 873.
149 Using rsync in this way is the same as using it with a remote shell except
153 it() you use a double colon :: instead of a single colon to
154 separate the hostname from the path.
156 it() the remote server may print a message of the day when you
159 it() if you specify no path name on the remote server then the
160 list of accessible paths on the server will be shown.
162 it() if you specify no local destination then a listing of the
163 specified files on the remote server is provided.
166 Some paths on the remote server may require authentication. If so then
167 you will receive a password prompt when you connect. You can avoid the
168 password prompt by setting the environment variable RSYNC_PASSWORD to
169 the password you want to use or using the --password-file option. This
170 may be useful when scripting rsync.
172 WARNING: On some systems environment variables are visible to all
173 users. On those systems using --password-file is recommended.
175 manpagesection(RUNNING AN RSYNC SERVER)
177 An rsync server is configured using a config file which by default is
178 called /etc/rsyncd.conf. Please see the rsyncd.conf(5) man page for more
181 manpagesection(EXAMPLES)
183 Here are some examples of how I use rsync.
185 To backup my wife's home directory, which consists of large MS Word
186 files and mail folders, I use a cron job that runs
188 quote(rsync -Cavz . arvidsjaur:backup)
190 each night over a PPP link to a duplicate directory on my machine
193 To synchronize my samba source trees I use the following Makefile
197 rsync -avuzb --exclude '*~' samba:samba/ .
200 rsync -Cavuzb . samba:samba/
204 this allows me to sync with a CVS directory at the other end of the
205 link. I then do cvs operations on the remote machine, which saves a
206 lot of time as the remote cvs protocol isn't very efficient.
208 I mirror a directory between my "old" and "new" ftp sites with the
211 quote(rsync -az -e ssh --delete ~ftp/pub/samba/ nimbus:"~ftp/pub/tridge/samba")
213 this is launched from cron every few hours.
215 manpagesection(OPTIONS SUMMARY)
217 Here is a short summary of the options available in rsync. Please refer
218 to the detailed description below for a complete description.
221 -v, --verbose increase verbosity
222 -q, --quiet decrease verbosity
223 -c, --checksum always checksum
224 -a, --archive archive mode
225 -r, --recursive recurse into directories
226 -R, --relative use relative path names
227 -b, --backup make backups (default ~ suffix)
228 --backup-dir make backups into this directory
229 --suffix=SUFFIX define backup suffix
230 -u, --update update only (don't overwrite newer files)
231 -l, --links copy symlinks as symlinks
232 -L, --copy-links copy the referent of symlinks
233 --copy-unsafe-links copy links outside the source tree
234 --safe-links ignore links outside the destination tree
235 -H, --hard-links preserve hard links
236 -p, --perms preserve permissions
237 -o, --owner preserve owner (root only)
238 -g, --group preserve group
239 -D, --devices preserve devices (root only)
240 -t, --times preserve times
241 -S, --sparse handle sparse files efficiently
242 -n, --dry-run show what would have been transferred
243 -W, --whole-file copy whole files, no incremental checks
244 --no-whole-file turn off --whole-file
245 -x, --one-file-system don't cross filesystem boundaries
246 -B, --block-size=SIZE checksum blocking size (default 700)
247 -e, --rsh=COMMAND specify the remote shell to use
248 --rsync-path=PATH specify path to rsync on the remote machine
249 -C, --cvs-exclude auto ignore files in the same way CVS does
250 --existing only update files that already exist
251 --ignore-existing ignore files that already exist on the receiving side
252 --delete delete files that don't exist on the sending side
253 --delete-excluded also delete excluded files on the receiving side
254 --delete-after delete after transferring, not before
255 --ignore-errors delete even if there are IO errors
256 --max-delete=NUM don't delete more than NUM files
257 --partial keep partially transferred files
258 --force force deletion of directories even if not empty
259 --numeric-ids don't map uid/gid values by user/group name
260 --timeout=TIME set IO timeout in seconds
261 -I, --ignore-times don't exclude files that match length and time
262 --size-only only use file size when determining if a file should be transferred
263 --modify-window=NUM Timestamp window (seconds) for file match (default=0)
264 -T --temp-dir=DIR create temporary files in directory DIR
265 --compare-dest=DIR also compare destination files relative to DIR
266 -P equivalent to --partial --progress
267 -z, --compress compress file data
268 --exclude=PATTERN exclude files matching PATTERN
269 --exclude-from=FILE exclude patterns listed in FILE
270 --include=PATTERN don't exclude files matching PATTERN
271 --include-from=FILE don't exclude patterns listed in FILE
272 --version print version number
273 --daemon run as a rsync daemon
274 --no-detach do not detach from the parent
275 --address=ADDRESS bind to the specified address
276 --config=FILE specify alternate rsyncd.conf file
277 --port=PORT specify alternate rsyncd port number
278 --blocking-io use blocking IO for the remote shell
279 --no-blocking-io turn off --blocking-io
280 --stats give some file transfer stats
281 --progress show progress during transfer
282 --log-format=FORMAT log file transfers using specified format
283 --password-file=FILE get password from FILE
284 --bwlimit=KBPS limit I/O bandwidth, KBytes per second
285 --read-batch=PREFIX read batch fileset starting with PREFIX
286 --write-batch=PREFIX write batch fileset starting with PREFIX
287 -h, --help show this help screen
294 rsync uses the GNU long options package. Many of the command line
295 options have two variants, one short and one long. These are shown
296 below, separated by commas. Some options only have a long variant.
297 The '=' for options that take a parameter is optional; whitespace
301 dit(bf(-h, --help)) Print a short help page describing the options
304 dit(bf(--version)) print the rsync version number and exit
306 dit(bf(-v, --verbose)) This option increases the amount of information you
307 are given during the transfer. By default, rsync works silently. A
308 single -v will give you information about what files are being
309 transferred and a brief summary at the end. Two -v flags will give you
310 information on what files are being skipped and slightly more
311 information at the end. More than two -v flags should only be used if
312 you are debugging rsync.
314 dit(bf(-q, --quiet)) This option decreases the amount of information you
315 are given during the transfer, notably suppressing information messages
316 from the remote server. This flag is useful when invoking rsync from
319 dit(bf(-I, --ignore-times)) Normally rsync will skip any files that are
320 already the same length and have the same time-stamp. This option turns
323 dit(bf(--size-only)) Normally rsync will skip any files that are
324 already the same length and have the same time-stamp. With the
325 --size-only option files will be skipped if they have the same size,
326 regardless of timestamp. This is useful when starting to use rsync
327 after using another mirroring system which may not preserve timestamps
330 dit(bf(--modify-window)) When comparing two timestamps rsync treats
331 the timestamps as being equal if they are within the value of
332 modify_window. This is normally zero, but you may find it useful to
333 set this to a larger value in some situations. In particular, when
334 transferring to/from FAT filesystems which cannot represent times with
335 a 1 second resolution this option is useful.
337 dit(bf(-c, --checksum)) This forces the sender to checksum all files using
338 a 128-bit MD4 checksum before transfer. The checksum is then
339 explicitly checked on the receiver and any files of the same name
340 which already exist and have the same checksum and size on the
341 receiver are skipped. This option can be quite slow.
343 dit(bf(-a, --archive)) This is equivalent to -rlptgoD. It is a quick
344 way of saying you want recursion and want to preserve almost
347 Note however that bf(-a) bf(does not preserve hardlinks), because
348 finding multiply-linked files is expensive. You must separately
351 dit(bf(-r, --recursive)) This tells rsync to copy directories
352 recursively. If you don't specify this then rsync won't copy
355 dit(bf(-R, --relative)) Use relative paths. This means that the full path
356 names specified on the command line are sent to the server rather than
357 just the last parts of the filenames. This is particularly useful when
358 you want to send several different directories at the same time. For
359 example, if you used the command
361 verb(rsync foo/bar/foo.c remote:/tmp/)
363 then this would create a file called foo.c in /tmp/ on the remote
364 machine. If instead you used
366 verb(rsync -R foo/bar/foo.c remote:/tmp/)
368 then a file called /tmp/foo/bar/foo.c would be created on the remote
369 machine. The full path name is preserved.
371 dit(bf(-b, --backup)) With this option preexisting destination files are
372 renamed with a ~ extension as each file is transferred. You can
373 control the backup suffix using the --suffix option.
375 dit(bf(--backup-dir=DIR)) In combination with the --backup option, this
376 tells rsync to store all backups in the specified directory. This is
377 very useful for incremental backups. You can additionally
378 specify a backup suffix using the --suffix option
379 (otherwise the files backed up in the specified directory
380 will keep their original filenames).
382 dit(bf(--suffix=SUFFIX)) This option allows you to override the default
383 backup suffix used with the -b option. The default is a ~.
384 If --backup-dir and --suffix are both specified,
385 the SUFFIX is appended to the filename even in the backup directory.
387 dit(bf(-u, --update)) This forces rsync to skip any files for which the
388 destination file already exists and has a date later than the source
391 dit(bf(-l, --links)) When symlinks are encountered, recreate the
392 symlink on the destination.
394 dit(bf(-L, --copy-links)) When symlinks are encountered, the file that
395 they point to is copied, rather than the symlink.
397 dit(bf(--copy-unsafe-links)) This tells rsync to copy the referent of
398 symbolic links that point outside the source tree. Absolute symlinks
399 are also treated like ordinary files, and so are any symlinks in the
400 source path itself when --relative is used.
402 dit(bf(--safe-links)) This tells rsync to ignore any symbolic links
403 which point outside the destination tree. All absolute symlinks are
404 also ignored. Using this option in conjunction with --relative may
405 give unexpected results.
407 dit(bf(-H, --hard-links)) This tells rsync to recreate hard links on
408 the remote system to be the same as the local system. Without this
409 option hard links are treated like regular files.
411 Note that rsync can only detect hard links if both parts of the link
412 are in the list of files being sent.
414 This option can be quite slow, so only use it if you need it.
416 dit(bf(-W, --whole-file)) With this option the incremental rsync algorithm
417 is not used and the whole file is sent as-is instead. The transfer may be
418 faster if this option is used when the bandwidth between the source and
419 target machines is higher than the bandwidth to disk (especially when the
420 "disk" is actually a networked file system). This is the default when both
421 the source and target are on the local machine.
423 dit(bf(--no-whole-file)) Turn off --whole-file, for use when it is the
426 dit(bf(-p, --perms)) This option causes rsync to update the remote
427 permissions to be the same as the local permissions.
429 dit(bf(-o, --owner)) This option causes rsync to set the owner of the
430 destination file to be the same as the source file. On most systems,
431 only the super-user can set file ownership. Note that if the remote system
432 is a daemon using chroot, the --numeric-ids option is implied because the
433 remote system cannot get access to the usernames from /etc/passwd.
435 dit(bf(-g, --group)) This option causes rsync to set the group of the
436 destination file to be the same as the source file. If the receiving
437 program is not running as the super-user, only groups that the
438 receiver is a member of will be preserved (by group name, not group id
441 dit(bf(-D, --devices)) This option causes rsync to transfer character and
442 block device information to the remote system to recreate these
443 devices. This option is only available to the super-user.
445 dit(bf(-t, --times)) This tells rsync to transfer modification times along
446 with the files and update them on the remote system. Note that if this
447 option is not used, the optimization that excludes files that have not been
448 modified cannot be effective; in other words, a missing -t or -a will
449 cause the next transfer to behave as if it used -I, and all files will have
450 their checksums compared and show up in log messages even if they haven't
453 dit(bf(-n, --dry-run)) This tells rsync to not do any file transfers,
454 instead it will just report the actions it would have taken.
456 dit(bf(-S, --sparse)) Try to handle sparse files efficiently so they take
457 up less space on the destination.
459 NOTE: Don't use this option when the destination is a Solaris "tmpfs"
460 filesystem. It doesn't seem to handle seeks over null regions
461 correctly and ends up corrupting the files.
463 dit(bf(-x, --one-file-system)) This tells rsync not to cross filesystem
464 boundaries when recursing. This is useful for transferring the
465 contents of only one filesystem.
467 dit(bf(--existing)) This tells rsync not to create any new files -
468 only update files that already exist on the destination.
470 dit(bf(--ignore-existing))
471 This tells rsync not to update files that already exist on
474 dit(bf(--max-delete=NUM)) This tells rsync not to delete more than NUM
475 files or directories. This is useful when mirroring very large trees
476 to prevent disasters.
478 dit(bf(--delete)) This tells rsync to delete any files on the receiving
479 side that aren't on the sending side. Files that are excluded from
480 transfer are excluded from being deleted unless you use --delete-excluded.
482 This option has no effect if directory recursion is not selected.
484 This option can be dangerous if used incorrectly! It is a very good idea
485 to run first using the dry run option (-n) to see what files would be
486 deleted to make sure important files aren't listed.
488 If the sending side detects any IO errors then the deletion of any
489 files at the destination will be automatically disabled. This is to
490 prevent temporary filesystem failures (such as NFS errors) on the
491 sending side causing a massive deletion of files on the
492 destination. You can override this with the --ignore-errors option.
494 dit(bf(--delete-excluded)) In addition to deleting the files on the
495 receiving side that are not on the sending side, this tells rsync to also
496 delete any files on the receiving side that are excluded (see --exclude).
499 dit(bf(--delete-after)) By default rsync does file deletions before
500 transferring files to try to ensure that there is sufficient space on
501 the receiving filesystem. If you want to delete after transferring
502 then use the --delete-after switch. Implies --delete.
504 dit(bf(--ignore-errors)) Tells --delete to go ahead and delete files
505 even when there are IO errors.
507 dit(bf(--force)) This options tells rsync to delete directories even if
508 they are not empty when they are to be replaced by non-directories. This
509 is only relevant without --delete because deletions are now done depth-first.
510 Requires the --recursive option (which is implied by -a) to have any effect.
512 dit(bf(-B , --block-size=BLOCKSIZE)) This controls the block size used in
513 the rsync algorithm. See the technical report for details.
515 dit(bf(-e, --rsh=COMMAND)) This option allows you to choose an alternative
516 remote shell program to use for communication between the local and
517 remote copies of rsync. Typically, rsync is configured to use rsh by
518 default, but you may prefer to use ssh because of its high security.
520 Command-line arguments are permitted in COMMAND provided that COMMAND is
521 presented to rsync as a single argument. For example:
523 quote(-e "ssh -p 2234")
525 (Note that ssh users can alternately customize site-specific connect
526 options in their .ssh/config file.)
528 You can also choose the remote shell program using the RSYNC_RSH
529 environment variable, which accepts the same range of values as -e.
531 See also the --blocking-io option which is affected by this option.
533 dit(bf(--rsync-path=PATH)) Use this to specify the path to the copy of
534 rsync on the remote machine. Useful when it's not in your path. Note
535 that this is the full path to the binary, not just the directory that
538 dit(bf(--exclude=PATTERN)) This option allows you to selectively exclude
539 certain files from the list of files to be transferred. This is most
540 useful in combination with a recursive transfer.
542 You may use as many --exclude options on the command line as you like
543 to build up the list of files to exclude.
545 See the section on exclude patterns for information on the syntax of
548 dit(bf(--exclude-from=FILE)) This option is similar to the --exclude
549 option, but instead it adds all exclude patterns listed in the file
550 FILE to the exclude list. Blank lines in FILE and lines starting with
551 ';' or '#' are ignored.
553 dit(bf(--include=PATTERN)) This option tells rsync to not exclude the
554 specified pattern of filenames. This is useful as it allows you to
555 build up quite complex exclude/include rules.
557 See the section of exclude patterns for information on the syntax of
560 dit(bf(--include-from=FILE)) This specifies a list of include patterns
563 dit(bf(-C, --cvs-exclude)) This is a useful shorthand for excluding a
564 broad range of files that you often don't want to transfer between
565 systems. It uses the same algorithm that CVS uses to determine if
566 a file should be ignored.
568 The exclude list is initialized to:
570 quote(RCS SCCS CVS CVS.adm RCSLOG cvslog.* tags TAGS .make.state
571 .nse_depinfo *~ #* .#* ,* *.old *.bak *.BAK *.orig *.rej .del-*
572 *.a *.o *.obj *.so *.Z *.elc *.ln core)
574 then files listed in a $HOME/.cvsignore are added to the list and any
575 files listed in the CVSIGNORE environment variable (space delimited).
577 Finally, any file is ignored if it is in the same directory as a
578 .cvsignore file and matches one of the patterns listed therein. See
579 the bf(cvs(1)) manual for more information.
581 dit(bf(--csum-length=LENGTH)) By default the primary checksum used in
582 rsync is a very strong 16 byte MD4 checksum. In most cases you will
583 find that a truncated version of this checksum is quite efficient, and
584 this will decrease the size of the checksum data sent over the link,
585 making things faster.
587 You can choose the number of bytes in the truncated checksum using the
588 --csum-length option. Any value less than or equal to 16 is valid.
590 Note that if you use this option then you run the risk of ending up
591 with an incorrect target file. The risk with a value of 16 is
592 microscopic and can be safely ignored (the universe will probably end
593 before it fails) but with smaller values the risk is higher.
595 Current versions of rsync actually use an adaptive algorithm for the
596 checksum length by default, using a 16 byte file checksum to determine
597 if a 2nd pass is required with a longer block checksum. Only use this
598 option if you have read the source code and know what you are doing.
600 dit(bf(-T, --temp-dir=DIR)) This option instructs rsync to use DIR as a
601 scratch directory when creating temporary copies of the files
602 transferred on the receiving side. The default behavior is to create
603 the temporary files in the receiving directory.
605 dit(bf(--compare-dest=DIR)) This option instructs rsync to use DIR on
606 the destination machine as an additional directory to compare destination
607 files against when doing transfers. This is useful for doing transfers to
608 a new destination while leaving existing files intact, and then doing a
609 flash-cutover when all files have been successfully transferred (for
610 example by moving directories around and removing the old directory,
611 although this requires also doing the transfer with -I to avoid skipping
612 files that haven't changed). This option increases the usefulness of
613 --partial because partially transferred files will remain in the new
614 temporary destination until they have a chance to be completed. If DIR is
615 a relative path, it is relative to the destination directory.
617 dit(bf(-z, --compress)) With this option, rsync compresses any data from
618 the files that it sends to the destination machine. This
619 option is useful on slow links. The compression method used is the
620 same method that gzip uses.
622 Note this this option typically achieves better compression ratios
623 that can be achieved by using a compressing remote shell, or a
624 compressing transport, as it takes advantage of the implicit
625 information sent for matching data blocks.
627 dit(bf(--numeric-ids)) With this option rsync will transfer numeric group
628 and user ids rather than using user and group names and mapping them
631 By default rsync will use the user name and group name to determine
632 what ownership to give files. The special uid 0 and the special group
633 0 are never mapped via user/group names even if the --numeric-ids
634 option is not specified.
636 If the source system is a daemon using chroot, or if a user or group
637 name does not exist on the destination system, then the numeric id
638 from the source system is used instead.
640 dit(bf(--timeout=TIMEOUT)) This option allows you to set a maximum IO
641 timeout in seconds. If no data is transferred for the specified time
642 then rsync will exit. The default is 0, which means no timeout.
644 dit(bf(--daemon)) This tells rsync that it is to run as a daemon. The
645 daemon may be accessed using the bf(host::module) or
646 bf(rsync://host/module/) syntax.
648 If standard input is a socket then rsync will assume that it is being
649 run via inetd, otherwise it will detach from the current terminal and
650 become a background daemon. The daemon will read the config file
651 (/etc/rsyncd.conf) on each connect made by a client and respond to
652 requests accordingly. See the rsyncd.conf(5) man page for more
655 dit(bf(--no-detach)) When running as a daemon, this option instructs
656 rsync to not detach itself and become a background process. This
657 option is required when running as a service on Cygwin, and may also
658 be useful when rsync is supervised by a program such as
659 bf(daemontools) or AIX's bf(System Resource Controller).
660 bf(--no-detach) is also recommended when rsync is run under a
661 debugger. This option has no effect if rsync is run from inetd or
664 dit(bf(--address)) By default rsync will bind to the wildcard address
665 when run as a daemon with the --daemon option or when connecting to a
666 rsync server. The --address option allows you to specify a specific IP
667 address (or hostname) to bind to. This makes virtual hosting possible
668 in conjunction with the --config option.
670 dit(bf(--config=FILE)) This specifies an alternate config file than
671 the default /etc/rsyncd.conf. This is only relevant when --daemon is
674 dit(bf(--port=PORT)) This specifies an alternate TCP port number to use
675 rather than the default port 873.
677 dit(bf(--blocking-io)) This tells rsync to use blocking IO when launching
678 a remote shell transport. If -e or --rsh are not specified or are set to
679 the default "rsh", this defaults to blocking IO, otherwise it defaults to
680 non-blocking IO. You may find the --blocking-io option is needed for some
681 remote shells that can't handle non-blocking IO. (Note that ssh prefers
684 dit(bf(--no-blocking-io)) Turn off --blocking-io, for use when it is the
687 dit(bf(--log-format=FORMAT)) This allows you to specify exactly what the
688 rsync client logs to stdout on a per-file basis. The log format is
689 specified using the same format conventions as the log format option in
692 dit(bf(--stats)) This tells rsync to print a verbose set of statistics
693 on the file transfer, allowing you to tell how effective the rsync
694 algorithm is for your data.
696 dit(bf(--partial)) By default, rsync will delete any partially
697 transferred file if the transfer is interrupted. In some circumstances
698 it is more desirable to keep partially transferred files. Using the
699 --partial option tells rsync to keep the partial file which should
700 make a subsequent transfer of the rest of the file much faster.
702 dit(bf(--progress)) This option tells rsync to print information
703 showing the progress of the transfer. This gives a bored user
706 This option is normally combined with -v. Using this option without
707 the -v option will produce weird results on your display.
709 dit(bf(-P)) The -P option is equivalent to --partial --progress. I
710 found myself typing that combination quite often so I created an
711 option to make it easier.
713 dit(bf(--password-file)) This option allows you to provide a password
714 in a file for accessing a remote rsync server. Note that this option
715 is only useful when accessing a rsync server using the built in
716 transport, not when using a remote shell as the transport. The file
717 must not be world readable. It should contain just the password as a
720 dit(bf(--bwlimit=KBPS)) This option allows you to specify a maximum
721 transfer rate in kilobytes per second. This option is most effective when
722 using rsync with large files (several megabytes and up). Due to the nature
723 of rsync transfers, blocks of data are sent, then if rsync determines the
724 transfer was too fast, it will wait before sending the next data block. The
725 result is an average transfer rate equalling the specified limit. A value
726 of zero specifies no limit.
728 dit(bf(--write-batch=PREFIX)) Generate a set of files that can be
729 transferred as a batch update. Each filename in the set starts with
730 PREFIX. See the "BATCH MODE" section for details.
732 dit(bf(--read-batch=PREFIX)) Apply a previously generated change batch,
733 using the fileset whose filenames start with PREFIX. See the "BATCH
734 MODE" section for details.
738 manpagesection(EXCLUDE PATTERNS)
740 The exclude and include patterns specified to rsync allow for flexible
741 selection of which files to transfer and which files to skip.
743 rsync builds an ordered list of include/exclude options as specified on
744 the command line. When a filename is encountered, rsync checks the
745 name against each exclude/include pattern in turn. The first matching
746 pattern is acted on. If it is an exclude pattern, then that file is
747 skipped. If it is an include pattern then that filename is not
748 skipped. If no matching include/exclude pattern is found then the
749 filename is not skipped.
751 Note that when used with -r (which is implied by -a), every subcomponent of
752 every path is visited from top down, so include/exclude patterns get
753 applied recursively to each subcomponent.
755 Note also that the --include and --exclude options take one pattern
756 each. To add multiple patterns use the --include-from and
757 --exclude-from options or multiple --include and --exclude options.
759 The patterns can take several forms. The rules are:
762 it() if the pattern starts with a / then it is matched against the
763 start of the filename, otherwise it is matched against the end of
764 the filename. Thus "/foo" would match a file called "foo" at the base of
765 the tree. On the other hand, "foo" would match any file called "foo"
766 anywhere in the tree because the algorithm is applied recursively from
767 top down; it behaves as if each path component gets a turn at being the
768 end of the file name.
770 it() if the pattern ends with a / then it will only match a
771 directory, not a file, link or device.
773 it() if the pattern contains a wildcard character from the set
774 *?[ then expression matching is applied using the shell filename
775 matching rules. Otherwise a simple string match is used.
777 it() if the pattern includes a double asterisk "**" then all wildcards in
778 the pattern will match slashes, otherwise they will stop at slashes.
780 it() if the pattern contains a / (not counting a trailing /) then it
781 is matched against the full filename, including any leading
782 directory. If the pattern doesn't contain a / then it is matched
783 only against the final component of the filename. Again, remember
784 that the algorithm is applied recursively so "full filename" can
785 actually be any portion of a path.
787 it() if the pattern starts with "+ " (a plus followed by a space)
788 then it is always considered an include pattern, even if specified as
789 part of an exclude option. The "+ " part is discarded before matching.
791 it() if the pattern starts with "- " (a minus followed by a space)
792 then it is always considered an exclude pattern, even if specified as
793 part of an include option. The "- " part is discarded before matching.
795 it() if the pattern is a single exclamation mark ! then the current
796 include/exclude list is reset, removing all previously defined patterns.
799 The +/- rules are most useful in exclude lists, allowing you to have a
800 single exclude list that contains both include and exclude options.
802 If you end an exclude list with --exclude '*', note that since the
803 algorithm is applied recursively that unless you explicitly include
804 parent directories of files you want to include then the algorithm
805 will stop at the parent directories and never see the files below
806 them. To include all directories, use --include '*/' before the
809 Here are some exclude/include examples:
812 it() --exclude "*.o" would exclude all filenames matching *.o
813 it() --exclude "/foo" would exclude a file in the base directory called foo
814 it() --exclude "foo/" would exclude any directory called foo
815 it() --exclude "/foo/*/bar" would exclude any file called bar two
816 levels below a base directory called foo
817 it() --exclude "/foo/**/bar" would exclude any file called bar two
818 or more levels below a base directory called foo
819 it() --include "*/" --include "*.c" --exclude "*" would include all
820 directories and C source files
821 it() --include "foo/" --include "foo/bar.c" --exclude "*" would include
822 only foo/bar.c (the foo/ directory must be explicitly included or
823 it would be excluded by the "*")
826 manpagesection(BATCH MODE)
828 bf(Note:) Batch mode should be considered experimental in this version
829 of rsync. The interface or behaviour may change before it stabilizes.
831 Batch mode can be used to apply the same set of updates to many
832 identical systems. Suppose one has a tree which is replicated on a
833 number of hosts. Now suppose some changes have been made to this
834 source tree and those changes need to be propagated to the other
835 hosts. In order to do this using batch mode, rsync is run with the
836 write-batch option to apply the changes made to the source tree to one
837 of the destination trees. The write-batch option causes the rsync
838 client to store the information needed to repeat this operation against
839 other destination trees in a batch update fileset (see below). The
840 filename of each file in the fileset starts with a prefix specified by
841 the user as an argument to the write-batch option. This fileset is
842 then copied to each remote host, where rsync is run with the read-batch
843 option, again specifying the same prefix, and the destination tree.
844 Rsync updates the destination tree using the information stored in the
845 batch update fileset.
847 The fileset consists of 4 files:
850 it() bf(<prefix>.rsync_argvs) command-line arguments
851 it() bf(<prefix>.rsync_flist) rsync internal file metadata
852 it() bf(<prefix>.rsync_csums) rsync checksums
853 it() bf(<prefix>.rsync_delta) data blocks for file update & change
856 The .rsync_argvs file contains a command-line suitable for updating a
857 destination tree using that batch update fileset. It can be executed
858 using a Bourne(-like) shell, optionally passing in an alternate
859 destination tree pathname which is then used instead of the original
860 path. This is useful when the destination tree path differs from the
861 original destination tree path.
863 Generating the batch update fileset once saves having to perform the
864 file status, checksum and data block generation more than once when
865 updating multiple destination trees. Multicast transport protocols can
866 be used to transfer the batch update files in parallel to many hosts at
867 once, instead of sending the same data to every host individually.
872 $ rsync --write_batch=pfx -a /source/dir/ /adest/dir/
873 $ rcp pfx.rsync_* remote:
874 $ rsh remote rsync --read_batch=pfx -a /bdest/dir/
876 $ rsh remote ./pfx.rsync_argvs /bdest/dir/
879 In this example, rsync is used to update /adest/dir/ with /source/dir/
880 and the information to repeat this operation is stored in the files
881 pfx.rsync_*. These files are then copied to the machine named "remote".
882 Rsync is then invoked on "remote" to update /bdest/dir/ the same way as
883 /adest/dir/. The last line shows the rsync_argvs file being used to
888 The read-batch option expects the destination tree it is meant to update
889 to be identical to the destination tree that was used to create the
890 batch update fileset. When a difference between the destination trees
891 is encountered the update will fail at that point, leaving the
892 destination tree in a partially updated state. In that case, rsync can
893 be used in its regular (non-batch) mode of operation to fix up the
896 The rsync version used on all destinations should be identical to the
897 one used on the original destination.
899 The -z/--compress option does not work in batch mode and yields a usage
900 error. A separate compression tool can be used instead to reduce the
901 size of the batch update files for transport to the destination.
903 The -n/--dryrun option does not work in batch mode and yields a runtime
906 See bf(http://www.ils.unc.edu/i2dsi/unc_rsync+.html) for papers and technical
909 manpagesection(SYMBOLIC LINKS)
911 Three basic behaviours are possible when rsync encounters a symbolic
912 link in the source directory.
914 By default, symbolic links are not transferred at all. A message
915 "skipping non-regular" file is emitted for any symlinks that exist.
917 If bf(--links) is specified, then symlinks are recreated with the same
918 target on the destination. Note that bf(--archive) implies
921 If bf(--copy-links) is specified, then symlinks are "collapsed" by
922 copying their referent, rather than the symlink.
924 rsync also distinguishes "safe" and "unsafe" symbolic links. An
925 example where this might be used is a web site mirror that wishes
926 ensure the rsync module they copy does not include symbolic links to
927 bf(/etc/passwd) in the public section of the site. Using
928 bf(--copy-unsafe-links) will cause any links to be copied as the file
929 they point to on the destination. Using bf(--safe-links) will cause
930 unsafe links to be ommitted altogether.
932 Symbolic links are considered unsafe if they are absolute symlinks
933 (start with bf(/)), empty, or if they contain enough bf("..")
934 components to ascend from the directory being copied.
936 manpagesection(DIAGNOSTICS)
938 rsync occasionally produces error messages that may seem a little
939 cryptic. The one that seems to cause the most confusion is "protocol
940 version mismatch - is your shell clean?".
942 This message is usually caused by your startup scripts or remote shell
943 facility producing unwanted garbage on the stream that rsync is using
944 for its transport. The way to diagnose this problem is to run your
945 remote shell like this:
948 rsh remotehost /bin/true > out.dat
951 then look at out.dat. If everything is working correctly then out.dat
952 should be a zero length file. If you are getting the above error from
953 rsync then you will probably find that out.dat contains some text or
954 data. Look at the contents and try to work out what is producing
955 it. The most common cause is incorrectly configured shell startup
956 scripts (such as .cshrc or .profile) that contain output statements
957 for non-interactive logins.
959 If you are having trouble debugging include and exclude patterns, then
960 try specifying the -vv option. At this level of verbosity rsync will
961 show why each individual file is included or excluded.
963 manpagesection(EXIT VALUES)
966 dit(bf(RERR_SYNTAX 1)) Syntax or usage error
967 dit(bf(RERR_PROTOCOL 2)) Protocol incompatibility
968 dit(bf(RERR_FILESELECT 3)) Errors selecting input/output files, dirs
970 dit(bf(RERR_UNSUPPORTED 4)) Requested action not supported: an attempt
971 was made to manipulate 64-bit files on a platform that cannot support
972 them; or an option was speciifed that is supported by the client and
975 dit(bf(RERR_SOCKETIO 10)) Error in socket IO
976 dit(bf(RERR_FILEIO 11)) Error in file IO
977 dit(bf(RERR_STREAMIO 12)) Error in rsync protocol data stream
978 dit(bf(RERR_MESSAGEIO 13)) Errors with program diagnostics
979 dit(bf(RERR_IPC 14)) Error in IPC code
980 dit(bf(RERR_SIGNAL 20)) Received SIGUSR1 or SIGINT
981 dit(bf(RERR_WAITCHILD 21)) Some error returned by waitpid()
982 dit(bf(RERR_MALLOC 22)) Error allocating core memory buffers
983 dit(bf(RERR_TIMEOUT 30)) Timeout in data send/receive
986 manpagesection(ENVIRONMENT VARIABLES)
990 dit(bf(CVSIGNORE)) The CVSIGNORE environment variable supplements any
991 ignore patterns in .cvsignore files. See the --cvs-exclude option for
994 dit(bf(RSYNC_RSH)) The RSYNC_RSH environment variable allows you to
995 override the default shell used as the transport for rsync. Command line
996 options are permitted after the command name, just as in the -e option.
998 dit(bf(RSYNC_PROXY)) The RSYNC_PROXY environment variable allows you to
999 redirect your rsync client to use a web proxy when connecting to a
1000 rsync daemon. You should set RSYNC_PROXY to a hostname:port pair.
1002 dit(bf(RSYNC_PASSWORD)) Setting RSYNC_PASSWORD to the required
1003 password allows you to run authenticated rsync connections to a rsync
1004 daemon without user intervention. Note that this does not supply a
1005 password to a shell transport such as ssh.
1007 dit(bf(USER) or bf(LOGNAME)) The USER or LOGNAME environment variables
1008 are used to determine the default username sent to a rsync server.
1010 dit(bf(HOME)) The HOME environment variable is used to find the user's
1011 default .cvsignore file.
1023 manpagediagnostics()
1027 times are transferred as unix time_t values
1029 file permissions, devices etc are transferred as native numerical
1032 see also the comments on the --delete option
1034 Please report bugs! The rsync bug tracking system is online at
1035 url(http://rsync.samba.org/rsync/)(http://rsync.samba.org/rsync/)
1037 manpagesection(VERSION)
1038 This man page is current for version 2.0 of rsync
1040 manpagesection(CREDITS)
1042 rsync is distributed under the GNU public license. See the file
1043 COPYING for details.
1045 A WEB site is available at
1046 url(http://rsync.samba.org/)(http://rsync.samba.org/). The site
1047 includes an FAQ-O-Matic which may cover questions unanswered by this
1050 The primary ftp site for rsync is
1051 url(ftp://rsync.samba.org/pub/rsync)(ftp://rsync.samba.org/pub/rsync).
1053 We would be delighted to hear from you if you like this program.
1055 This program uses the excellent zlib compression library written by
1056 Jean-loup Gailly and Mark Adler.
1058 manpagesection(THANKS)
1060 Thanks to Richard Brent, Brendan Mackay, Bill Waite, Stephen Rothwell
1061 and David Bell for helpful suggestions, patches and testing of rsync.
1062 I've probably missed some people, my apologies if I have.
1064 Especial thanks also to: David Dykstra, Jos Backus, Sebastian Krahmer.
1069 rsync was written by Andrew Tridgell <tridge@samba.org> and Paul
1072 rsync is now maintained by Martin Pool <mbp@samba.org>.
1074 Mailing lists for support and development are available at
1075 url(http://lists.samba.org)(lists.samba.org)
1077 If you suspect you have found a security vulnerability in rsync,
1078 please send it directly to Martin Pool and Andrew Tridgell. For other
1079 enquiries, please use the mailing list.