Make the -e text a little less chatty, and mention the legality of
[rsync/rsync.git] / rsync.yo
1 mailto(rsync-bugs@samba.org)
2 manpage(rsync)(1)(25 Jan 2002)()()
3 manpagename(rsync)(faster, flexible replacement for rcp)
4 manpagesynopsis()
5
6 rsync [OPTION]... SRC [SRC]... [USER@]HOST:DEST
7
8 rsync [OPTION]... [USER@]HOST:SRC DEST
9
10 rsync [OPTION]... SRC [SRC]... DEST
11
12 rsync [OPTION]... [USER@]HOST::SRC [DEST]
13
14 rsync [OPTION]... SRC [SRC]... [USER@]HOST::DEST
15
16 rsync [OPTION]... rsync://[USER@]HOST[:PORT]/SRC [DEST]
17
18 manpagedescription()
19
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
23 exists.
24
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.
29
30 Some of the additional features of rsync are:
31
32 itemize(
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
40        mirroring)
41 )
42
43 manpagesection(GENERAL)
44
45 There are six different ways of using rsync. They are:
46
47 itemize(
48         it() for copying local files. This is invoked when neither
49              source nor destination path contains a : separator
50
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
54         single : separator.
55
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.
59
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.
63
64         it() for copying from the local machine to a remote rsync
65         server. This is invoked when the destination path contains a ::
66         separator. 
67
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
70         local destination.  
71 )
72
73 Note that in all cases (other than listing) at least one of the source
74 and destination paths must be local.
75
76 manpagesection(SETUP)
77
78 See the file README for installation instructions.
79
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.
85
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.
88
89 One common substitute is to use ssh, which offers a high degree of
90 security.
91
92 Note that rsync must be installed on both the source and destination
93 machines. 
94
95 manpagesection(USAGE)
96
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.
99
100 Perhaps the best way to explain the syntax is some examples:
101
102 quote(rsync *.c foo:src/)
103
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.
109
110 quote(rsync -avz foo:src/bar /data/tmp)
111
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.
118
119 quote(rsync -avz foo:src/bar/ /data/tmp)
120
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.
127
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.
131
132 quote(rsync somehost.mydomain.com::)
133
134 this would list all the anonymous rsync modules available on the host
135 somehost.mydomain.com.  (See the following section for more details.)
136
137
138 manpagesection(CONNECTING TO AN RSYNC SERVER)
139
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. 
143
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.
148
149 Using rsync in this way is the same as using it with a remote shell except
150 that:
151
152 itemize(
153         it() you use a double colon :: instead of a single colon to
154         separate the hostname from the path. 
155
156         it() the remote server may print a message of the day when you
157         connect.
158
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.
161
162         it() if you specify no local destination then a listing of the
163         specified files on the remote server is provided.
164 )
165
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.
171
172 WARNING: On some systems environment variables are visible to all
173 users. On those systems using --password-file is recommended.
174
175 manpagesection(RUNNING AN RSYNC SERVER)
176
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
179 information. 
180
181 manpagesection(EXAMPLES)
182
183 Here are some examples of how I use rsync.
184
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
187
188 quote(rsync -Cavz . arvidsjaur:backup)
189
190 each night over a PPP link to a duplicate directory on my machine
191 "arvidsjaur".
192
193 To synchronize my samba source trees I use the following Makefile
194 targets:
195
196 quote(      get:nl()
197        rsync -avuzb --exclude '*~' samba:samba/ .
198
199       put:nl()
200        rsync -Cavuzb . samba:samba/
201
202       sync: get put)
203
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.
207
208 I mirror a directory between my "old" and "new" ftp sites with the
209 command
210
211 quote(rsync -az -e ssh --delete ~ftp/pub/samba/ nimbus:"~ftp/pub/tridge/samba")
212
213 this is launched from cron every few hours.
214
215 manpagesection(OPTIONS SUMMARY)
216
217 Here is a short summary of the options available in rsync. Please refer
218 to the detailed description below for a complete description.
219
220 verb(
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
288
289
290 )
291
292 manpageoptions()
293
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
298 can be used instead.
299
300 startdit()
301 dit(bf(-h, --help)) Print a short help page describing the options
302 available in rsync
303
304 dit(bf(--version)) print the rsync version number and exit
305
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.
313
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
317 cron.
318
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
321 off this behavior.
322
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
328 exactly.
329
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.
336
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.
342
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
345 everything.  
346
347 Note however that bf(-a) bf(does not preserve hardlinks), because
348 finding multiply-linked files is expensive.  You must separately
349 specify bf(-H).
350
351 dit(bf(-r, --recursive)) This tells rsync to copy directories
352 recursively. If you don't specify this then rsync won't copy
353 directories at all.
354
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
360
361 verb(rsync foo/bar/foo.c remote:/tmp/)
362
363 then this would create a file called foo.c in /tmp/ on the remote
364 machine. If instead you used
365
366 verb(rsync -R foo/bar/foo.c remote:/tmp/)
367
368 then a file called /tmp/foo/bar/foo.c would be created on the remote
369 machine. The full path name is preserved.
370
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.
374
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).
381
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.
386
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
389 file.
390
391 dit(bf(-l, --links)) When symlinks are encountered, recreate the
392 symlink on the destination.
393
394 dit(bf(-L, --copy-links)) When symlinks are encountered, the file that
395 they point to is copied, rather than the symlink.
396
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.
401
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. 
406
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.
410
411 Note that rsync can only detect hard links if both parts of the link
412 are in the list of files being sent.
413
414 This option can be quite slow, so only use it if you need it.
415
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.
422
423 dit(bf(--no-whole-file)) Turn off --whole-file, for use when it is the
424 default.
425
426 dit(bf(-p, --perms)) This option causes rsync to update the remote
427 permissions to be the same as the local permissions.
428
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.  
432
433 dit(bf(-g, --group)) This option causes rsync to set the group of the
434 destination file to be the same as the source file.  If the receiving
435 program is not running as the super-user, only groups that the
436 receiver is a member of will be preserved (by group name, not group id
437 number).
438
439 dit(bf(-D, --devices)) This option causes rsync to transfer character and
440 block device information to the remote system to recreate these
441 devices. This option is only available to the super-user.
442
443 dit(bf(-t, --times)) This tells rsync to transfer modification times along
444 with the files and update them on the remote system.  Note that if this
445 option is not used, the optimization that excludes files that have not been
446 modified cannot be effective; in other words, a missing -t or -a will
447 cause the next transfer to behave as if it used -I, and all files will have
448 their checksums compared and show up in log messages even if they haven't
449 changed.
450
451 dit(bf(-n, --dry-run)) This tells rsync to not do any file transfers,
452 instead it will just report the actions it would have taken.
453
454 dit(bf(-S, --sparse)) Try to handle sparse files efficiently so they take
455 up less space on the destination.
456
457 NOTE: Don't use this option when the destination is a Solaris "tmpfs"
458 filesystem. It doesn't seem to handle seeks over null regions
459 correctly and ends up corrupting the files.
460
461 dit(bf(-x, --one-file-system)) This tells rsync not to cross filesystem
462 boundaries  when recursing.  This  is useful for transferring the
463 contents of only one filesystem.
464
465 dit(bf(--existing)) This tells rsync not to create any new files -
466 only update files that already exist on the destination.
467
468 dit(bf(--ignore-existing))
469 This tells rsync not to update files that already exist on 
470 the destination. 
471
472 dit(bf(--max-delete=NUM)) This tells rsync not to delete more than NUM
473 files or directories. This is useful when mirroring very large trees
474 to prevent disasters.
475
476 dit(bf(--delete)) This tells rsync to delete any files on the receiving
477 side that aren't on the sending side.   Files that are excluded from
478 transfer are excluded from being deleted unless you use --delete-excluded.
479
480 This option has no effect if directory recursion is not selected.
481
482 This option can be dangerous if used incorrectly!  It is a very good idea
483 to run first using the dry run option (-n) to see what files would be
484 deleted to make sure important files aren't listed.
485
486 If the sending side detects any IO errors then the deletion of any
487 files at the destination will be automatically disabled. This is to
488 prevent temporary filesystem failures (such as NFS errors) on the
489 sending side causing a massive deletion of files on the
490 destination.  You can override this with the --ignore-errors option.
491
492 dit(bf(--delete-excluded)) In addition to deleting the files on the
493 receiving side that are not on the sending side, this tells rsync to also
494 delete any files on the receiving side that are excluded (see --exclude).
495 Implies --delete.
496
497 dit(bf(--delete-after)) By default rsync does file deletions before
498 transferring files to try to ensure that there is sufficient space on
499 the receiving filesystem. If you want to delete after transferring
500 then use the --delete-after switch. Implies --delete.
501
502 dit(bf(--ignore-errors)) Tells --delete to go ahead and delete files
503 even when there are IO errors.
504
505 dit(bf(--force)) This options tells rsync to delete directories even if
506 they are not empty when they are to be replaced by non-directories.  This
507 is only relevant without --delete because deletions are now done depth-first.
508 Requires the --recursive option (which is implied by -a) to have any effect.
509
510 dit(bf(-B , --block-size=BLOCKSIZE)) This controls the block size used in
511 the rsync algorithm. See the technical report for details.
512
513 dit(bf(-e, --rsh=COMMAND)) This option allows you to choose an alternative
514 remote shell program to use for communication between the local and
515 remote copies of rsync. Typically, rsync is configured to use rsh by
516 default, but you may prefer to use ssh because of its high security.
517
518 Command-line arguments are permitted in COMMAND provided that COMMAND is
519 presented to rsync as a single argument.  For example:
520
521 quote(-e "ssh -p 2234")
522
523 (Note that ssh users can alternately customize site-specific connect
524 options in their .ssh/config file.)
525
526 You can also choose the remote shell program using the RSYNC_RSH
527 environment variable, which accepts the same range of values as -e.
528
529 See also the --blocking-io option which is affected by this option.
530
531 dit(bf(--rsync-path=PATH)) Use this to specify the path to the copy of
532 rsync on the remote machine. Useful when it's not in your path. Note
533 that this is the full path to the binary, not just the directory that
534 the binary is in.
535
536 dit(bf(--exclude=PATTERN)) This option allows you to selectively exclude
537 certain files from the list of files to be transferred. This is most
538 useful in combination with a recursive transfer.
539
540 You may use as many --exclude options on the command line as you like
541 to build up the list of files to exclude.
542
543 See the section on exclude patterns for information on the syntax of 
544 this option.
545
546 dit(bf(--exclude-from=FILE)) This option is similar to the --exclude
547 option, but instead it adds all exclude patterns listed in the file
548 FILE to the exclude list.  Blank lines in FILE and lines starting with
549 ';' or '#' are ignored.
550
551 dit(bf(--include=PATTERN)) This option tells rsync to not exclude the
552 specified pattern of filenames. This is useful as it allows you to
553 build up quite complex exclude/include rules.
554
555 See the section of exclude patterns for information on the syntax of 
556 this option.
557
558 dit(bf(--include-from=FILE)) This specifies a list of include patterns
559 from a file.
560
561 dit(bf(-C, --cvs-exclude)) This is a useful shorthand for excluding a
562 broad range of files that you often don't want to transfer between
563 systems. It uses the same algorithm that CVS uses to determine if
564 a file should be ignored.
565
566 The exclude list is initialized to:
567
568 quote(RCS SCCS CVS CVS.adm RCSLOG cvslog.* tags TAGS .make.state
569 .nse_depinfo *~ #* .#* ,* *.old *.bak *.BAK *.orig *.rej .del-*
570 *.a *.o *.obj *.so *.Z *.elc *.ln core)
571
572 then files listed in a $HOME/.cvsignore are added to the list and any
573 files listed in the CVSIGNORE environment variable (space delimited).
574
575 Finally, any file is ignored if it is in the same directory as a
576 .cvsignore file and matches one of the patterns listed therein.  See
577 the bf(cvs(1)) manual for more information.
578
579 dit(bf(--csum-length=LENGTH)) By default the primary checksum used in
580 rsync is a very strong 16 byte MD4 checksum. In most cases you will
581 find that a truncated version of this checksum is quite efficient, and
582 this will decrease the size of the checksum data sent over the link,
583 making things faster. 
584
585 You can choose the number of bytes in the truncated checksum using the
586 --csum-length option. Any value less than or equal to 16 is valid.
587
588 Note that if you use this option then you run the risk of ending up
589 with an incorrect target file. The risk with a value of 16 is
590 microscopic and can be safely ignored (the universe will probably end
591 before it fails) but with smaller values the risk is higher.
592
593 Current versions of rsync actually use an adaptive algorithm for the
594 checksum length by default, using a 16 byte file checksum to determine
595 if a 2nd pass is required with a longer block checksum. Only use this
596 option if you have read the source code and know what you are doing.
597
598 dit(bf(-T, --temp-dir=DIR)) This option instructs rsync to use DIR as a
599 scratch directory when creating temporary copies of the files
600 transferred on the receiving side.  The default behavior is to create
601 the temporary files in the receiving directory.
602
603 dit(bf(--compare-dest=DIR)) This option instructs rsync to use DIR on
604 the destination machine as an additional directory to compare destination
605 files against when doing transfers.  This is useful for doing transfers to
606 a new destination while leaving existing files intact, and then doing a
607 flash-cutover when all files have been successfully transferred (for
608 example by moving directories around and removing the old directory,
609 although this requires also doing the transfer with -I to avoid skipping
610 files that haven't changed).  This option increases the usefulness of
611 --partial because partially transferred files will remain in the new
612 temporary destination until they have a chance to be completed.  If DIR is
613 a relative path, it is relative to the destination directory.
614
615 dit(bf(-z, --compress)) With this option, rsync compresses any data from
616 the files that it sends to the destination machine.  This
617 option is useful on slow links.  The compression method used is the
618 same method that gzip uses.
619
620 Note this this option typically achieves better compression ratios
621 that can be achieved by using a compressing remote shell, or a
622 compressing transport, as it takes advantage of the implicit
623 information sent for matching data blocks.
624
625 dit(bf(--numeric-ids)) With this option rsync will transfer numeric group
626 and user ids rather than using user and group names and mapping them
627 at both ends.
628
629 By default rsync will use the user name and group name to determine
630 what ownership to give files. The special uid 0 and the special group
631 0 are never mapped via user/group names even if the --numeric-ids
632 option is not specified.
633
634 If the source system is a daemon using chroot, or if a user or group
635 name does not exist on the destination system, then the numeric id
636 from the source system is used instead.
637
638 dit(bf(--timeout=TIMEOUT)) This option allows you to set a maximum IO
639 timeout in seconds. If no data is transferred for the specified time
640 then rsync will exit. The default is 0, which means no timeout.
641
642 dit(bf(--daemon)) This tells rsync that it is to run as a daemon.  The
643 daemon may be accessed using the bf(host::module) or
644 bf(rsync://host/module/) syntax.
645
646 If standard input is a socket then rsync will assume that it is being
647 run via inetd, otherwise it will detach from the current terminal and
648 become a background daemon.  The daemon will read the config file
649 (/etc/rsyncd.conf) on each connect made by a client and respond to
650 requests accordingly.  See the rsyncd.conf(5) man page for more
651 details.
652
653 dit(bf(--no-detach)) When running as a daemon, this option instructs
654 rsync to not detach itself and become a background process.  This
655 option is required when running as a service on Cygwin, and may also
656 be useful when rsync is supervised by a program such as
657 bf(daemontools) or AIX's bf(System Resource Controller).
658 bf(--no-detach) is also recommended when rsync is run under a
659 debugger.  This option has no effect if rsync is run from inetd or
660 sshd.
661
662 dit(bf(--address)) By default rsync will bind to the wildcard address
663 when run as a daemon with the --daemon option or when connecting to a
664 rsync server. The --address option allows you to specify a specific IP
665 address (or hostname) to bind to. This makes virtual hosting possible
666 in conjunction with the --config option.
667
668 dit(bf(--config=FILE)) This specifies an alternate config file than
669 the default /etc/rsyncd.conf. This is only relevant when --daemon is
670 specified. 
671
672 dit(bf(--port=PORT)) This specifies an alternate TCP port number to use
673 rather than the default port 873.
674
675 dit(bf(--blocking-io)) This tells rsync to use blocking IO when launching
676 a remote shell transport.  If -e or --rsh are not specified or are set to
677 the default "rsh", this defaults to blocking IO, otherwise it defaults to
678 non-blocking IO.  You may find the --blocking-io option is needed for some
679 remote shells that can't handle non-blocking IO.  (Note that ssh prefers
680 non-blocking IO.)
681
682 dit(bf(--no-blocking-io)) Turn off --blocking-io, for use when it is the
683 default.
684
685 dit(bf(--log-format=FORMAT)) This allows you to specify exactly what the
686 rsync client logs to stdout on a per-file basis. The log format is
687 specified using the same format conventions as the log format option in
688 rsyncd.conf.
689
690 dit(bf(--stats)) This tells rsync to print a verbose set of statistics
691 on the file transfer, allowing you to tell how effective the rsync
692 algorithm is for your data.
693
694 dit(bf(--partial)) By default, rsync will delete any partially
695 transferred file if the transfer is interrupted. In some circumstances
696 it is more desirable to keep partially transferred files. Using the
697 --partial option tells rsync to keep the partial file which should
698 make a subsequent transfer of the rest of the file much faster.
699
700 dit(bf(--progress)) This option tells rsync to print information
701 showing the progress of the transfer. This gives a bored user
702 something to watch.
703
704 This option is normally combined with -v. Using this option without
705 the -v option will produce weird results on your display.
706
707 dit(bf(-P)) The -P option is equivalent to --partial --progress. I
708 found myself typing that combination quite often so I created an
709 option to make it easier.
710
711 dit(bf(--password-file)) This option allows you to provide a password
712 in a file for accessing a remote rsync server. Note that this option
713 is only useful when accessing a rsync server using the built in
714 transport, not when using a remote shell as the transport. The file
715 must not be world readable. It should contain just the password as a
716 single line.
717
718 dit(bf(--bwlimit=KBPS)) This option allows you to specify a maximum
719 transfer rate in kilobytes per second. This option is most effective when
720 using rsync with large files (several megabytes and up). Due to the nature
721 of rsync transfers, blocks of data are sent, then if rsync determines the
722 transfer was too fast, it will wait before sending the next data block. The
723 result is an average transfer rate equalling the specified limit. A value
724 of zero specifies no limit.
725
726 dit(bf(--write-batch=PREFIX)) Generate a set of files that can be
727 transferred as a batch update. Each filename in the set starts with
728 PREFIX. See the "BATCH MODE" section for details.
729
730 dit(bf(--read-batch=PREFIX)) Apply a previously generated change batch,
731 using the fileset whose filenames start with PREFIX. See the "BATCH
732 MODE" section for details.
733
734 enddit()
735
736 manpagesection(EXCLUDE PATTERNS)
737
738 The exclude and include patterns specified to rsync allow for flexible
739 selection of which files to transfer and which files to skip.
740
741 rsync builds an ordered list of include/exclude options as specified on
742 the command line. When a filename is encountered, rsync checks the
743 name against each exclude/include pattern in turn. The first matching
744 pattern is acted on. If it is an exclude pattern, then that file is
745 skipped. If it is an include pattern then that filename is not
746 skipped. If no matching include/exclude pattern is found then the
747 filename is not skipped.
748
749 Note that when used with -r (which is implied by -a), every subcomponent of
750 every path is visited from top down, so include/exclude patterns get
751 applied recursively to each subcomponent.
752
753 Note also that the --include and --exclude options take one pattern
754 each. To add multiple patterns use the --include-from and
755 --exclude-from options or multiple --include and --exclude options. 
756
757 The patterns can take several forms. The rules are:
758
759 itemize(
760   it() if the pattern starts with a / then it is matched against the
761   start of the filename, otherwise it is matched against the end of
762   the filename.  Thus "/foo" would match a file called "foo" at the base of
763   the tree.  On the other hand, "foo" would match any file called "foo"
764   anywhere in the tree because the algorithm is applied recursively from
765   top down; it behaves as if each path component gets a turn at being the
766   end of the file name.
767
768   it() if the pattern ends with a / then it will only match a
769   directory, not a file, link or device.
770
771   it() if the pattern contains a wildcard character from the set
772   *?[ then expression matching is applied using the shell filename
773   matching rules. Otherwise a simple string match is used.
774
775   it() if the pattern includes a double asterisk "**" then all wildcards in
776   the pattern will match slashes, otherwise they will stop at slashes.
777
778   it() if the pattern contains a / (not counting a trailing /) then it
779   is matched against the full filename, including any leading
780   directory. If the pattern doesn't contain a / then it is matched
781   only against the final component of the filename.  Again, remember
782   that the algorithm is applied recursively so "full filename" can 
783   actually be any portion of a path.
784
785   it() if the pattern starts with "+ " (a plus followed by a space)
786   then it is always considered an include pattern, even if specified as
787   part of an exclude option. The "+ " part is discarded before matching.
788
789   it() if the pattern starts with "- " (a minus followed by a space)
790   then it is always considered an exclude pattern, even if specified as
791   part of an include option. The "- " part is discarded before matching.
792
793   it() if the pattern is a single exclamation mark ! then the current
794   include/exclude list is reset, removing all previously defined patterns.
795 )
796
797 The +/- rules are most useful in exclude lists, allowing you to have a
798 single exclude list that contains both include and exclude options.
799
800 If you end an exclude list with --exclude '*', note that since the
801 algorithm is applied recursively that unless you explicitly include
802 parent directories of files you want to include then the algorithm
803 will stop at the parent directories and never see the files below
804 them.  To include all directories, use --include '*/' before the
805 --exclude '*'.
806
807 Here are some exclude/include examples:
808
809 itemize(
810   it() --exclude "*.o" would exclude all filenames matching *.o
811   it() --exclude "/foo" would exclude a file in the base directory called foo
812   it() --exclude "foo/" would exclude any directory called foo
813   it() --exclude "/foo/*/bar" would exclude any file called bar two
814   levels below a base directory called foo
815   it() --exclude "/foo/**/bar" would exclude any file called bar two
816   or more levels below a base directory called foo
817   it() --include "*/" --include "*.c" --exclude "*" would include all 
818   directories and C source files
819   it() --include "foo/" --include "foo/bar.c" --exclude "*" would include
820   only foo/bar.c (the foo/ directory must be explicitly included or
821   it would be excluded by the "*")
822 )
823
824 manpagesection(BATCH MODE)
825
826 bf(Note:) Batch mode should be considered experimental in this version
827 of rsync. The interface or behaviour may change before it stabilizes.
828
829 Batch mode can be used to apply the same set of updates to many
830 identical systems. Suppose one has a tree which is replicated on a
831 number of hosts.  Now suppose some changes have been made to this
832 source tree and those changes need to be propagated to the other
833 hosts. In order to do this using batch mode, rsync is run with the
834 write-batch option to apply the changes made to the source tree to one
835 of the destination trees.  The write-batch option causes the rsync
836 client to store the information needed to repeat this operation against
837 other destination trees in a batch update fileset (see below).  The
838 filename of each file in the fileset starts with a prefix specified by
839 the user as an argument to the write-batch option.  This fileset is
840 then copied to each remote host, where rsync is run with the read-batch
841 option, again specifying the same prefix, and the destination tree.
842 Rsync updates the destination tree using the information stored in the
843 batch update fileset.
844
845 The fileset consists of 4 files:
846
847 itemize(
848 it() bf(<prefix>.rsync_argvs) command-line arguments
849 it() bf(<prefix>.rsync_flist) rsync internal file metadata
850 it() bf(<prefix>.rsync_csums) rsync checksums
851 it() bf(<prefix>.rsync_delta) data blocks for file update & change
852 )
853
854 The .rsync_argvs file contains a command-line suitable for updating a
855 destination tree using that batch update fileset. It can be executed
856 using a Bourne(-like) shell, optionally passing in an alternate
857 destination tree pathname which is then used instead of the original
858 path. This is useful when the destination tree path differs from the
859 original destination tree path.
860
861 Generating the batch update fileset once saves having to perform the
862 file status, checksum and data block generation more than once when
863 updating multiple destination trees. Multicast transport protocols can
864 be used to transfer the batch update files in parallel to many hosts at
865 once, instead of sending the same data to every host individually.
866
867 Example:
868
869 verb(
870 $ rsync --write_batch=pfx -a /source/dir/ /adest/dir/
871 $ rcp pfx.rsync_* remote:
872 $ rsh remote rsync --read_batch=pfx -a /bdest/dir/
873 # or alternatively
874 $ rsh remote ./pfx.rsync_argvs /bdest/dir/
875 )
876
877 In this example, rsync is used to update /adest/dir/ with /source/dir/
878 and the information to repeat this operation is stored in the files
879 pfx.rsync_*. These files are then copied to the machine named "remote".
880 Rsync is then invoked on "remote" to update /bdest/dir/ the same way as
881 /adest/dir/. The last line shows the rsync_argvs file being used to
882 invoke rsync.
883
884 Caveats:
885
886 The read-batch option expects the destination tree it is meant to update
887 to be identical to the destination tree that was used to create the
888 batch update fileset.  When a difference between the destination trees
889 is encountered the update will fail at that point, leaving the
890 destination tree in a partially updated state. In that case, rsync can
891 be used in its regular (non-batch) mode of operation to fix up the
892 destination tree.
893
894 The rsync version used on all destinations should be identical to the
895 one used on the original destination.
896
897 The -z/--compress option does not work in batch mode and yields a usage
898 error. A separate compression tool can be used instead to reduce the
899 size of the batch update files for transport to the destination.
900
901 The -n/--dryrun option does not work in batch mode and yields a runtime
902 error.
903
904 See bf(http://www.ils.unc.edu/i2dsi/unc_rsync+.html) for papers and technical
905 reports.
906
907 manpagesection(SYMBOLIC LINKS)
908
909 Three basic behaviours are possible when rsync encounters a symbolic
910 link in the source directory.
911
912 By default, symbolic links are not transferred at all.  A message
913 "skipping non-regular" file is emitted for any symlinks that exist.
914
915 If bf(--links) is specified, then symlinks are recreated with the same
916 target on the destination.  Note that bf(--archive) implies
917 bf(--links).
918
919 If bf(--copy-links) is specified, then symlinks are "collapsed" by
920 copying their referent, rather than the symlink.
921
922 rsync also distinguishes "safe" and "unsafe" symbolic links.  An
923 example where this might be used is a web site mirror that wishes
924 ensure the rsync module they copy does not include symbolic links to
925 bf(/etc/passwd) in the public section of the site.  Using
926 bf(--copy-unsafe-links) will cause any links to be copied as the file
927 they point to on the destination.  Using bf(--safe-links) will cause
928 unsafe links to be ommitted altogether.
929
930 Symbolic links are considered unsafe if they are absolute symlinks
931 (start with bf(/)), empty, or if they contain enough bf("..")
932 components to ascend from the directory being copied.
933
934 manpagesection(DIAGNOSTICS)
935
936 rsync occasionally produces error messages that may seem a little
937 cryptic. The one that seems to cause the most confusion is "protocol
938 version mismatch - is your shell clean?".
939
940 This message is usually caused by your startup scripts or remote shell
941 facility producing unwanted garbage on the stream that rsync is using
942 for its transport. The way to diagnose this problem is to run your
943 remote shell like this:
944
945 verb(
946    rsh remotehost /bin/true > out.dat
947 )
948        
949 then look at out.dat. If everything is working correctly then out.dat
950 should be a zero length file. If you are getting the above error from
951 rsync then you will probably find that out.dat contains some text or
952 data. Look at the contents and try to work out what is producing
953 it. The most common cause is incorrectly configured shell startup
954 scripts (such as .cshrc or .profile) that contain output statements
955 for non-interactive logins.
956
957 If you are having trouble debugging include and exclude patterns, then
958 try specifying the -vv option.  At this level of verbosity rsync will
959 show why each individual file is included or excluded.
960
961 manpagesection(EXIT VALUES)
962
963 startdit()
964 dit(bf(RERR_SYNTAX     1))       Syntax or usage error 
965 dit(bf(RERR_PROTOCOL   2))       Protocol incompatibility 
966 dit(bf(RERR_FILESELECT 3))       Errors selecting input/output files, dirs
967
968 dit(bf(RERR_UNSUPPORTED 4)) Requested action not supported: an attempt
969 was made to manipulate 64-bit files on a platform that cannot support
970 them; or an option was speciifed that is supported by the client and
971 not by the server.
972
973 dit(bf(RERR_SOCKETIO   10))      Error in socket IO 
974 dit(bf(RERR_FILEIO     11))      Error in file IO 
975 dit(bf(RERR_STREAMIO   12))      Error in rsync protocol data stream 
976 dit(bf(RERR_MESSAGEIO  13))      Errors with program diagnostics 
977 dit(bf(RERR_IPC        14))      Error in IPC code 
978 dit(bf(RERR_SIGNAL     20))      Received SIGUSR1 or SIGINT 
979 dit(bf(RERR_WAITCHILD  21))      Some error returned by waitpid() 
980 dit(bf(RERR_MALLOC     22))      Error allocating core memory buffers 
981 dit(bf(RERR_TIMEOUT    30))      Timeout in data send/receive 
982 enddit()
983
984 manpagesection(ENVIRONMENT VARIABLES)
985
986 startdit()
987
988 dit(bf(CVSIGNORE)) The CVSIGNORE environment variable supplements any
989 ignore patterns in .cvsignore files. See the --cvs-exclude option for
990 more details.
991
992 dit(bf(RSYNC_RSH)) The RSYNC_RSH environment variable allows you to
993 override the default shell used as the transport for rsync.  Command line
994 options are permitted after the command name, just as in the -e option.
995
996 dit(bf(RSYNC_PROXY)) The RSYNC_PROXY environment variable allows you to
997 redirect your rsync client to use a web proxy when connecting to a
998 rsync daemon. You should set RSYNC_PROXY to a hostname:port pair.
999
1000 dit(bf(RSYNC_PASSWORD)) Setting RSYNC_PASSWORD to the required
1001 password allows you to run authenticated rsync connections to a rsync
1002 daemon without user intervention. Note that this does not supply a
1003 password to a shell transport such as ssh.
1004
1005 dit(bf(USER) or bf(LOGNAME)) The USER or LOGNAME environment variables
1006 are used to determine the default username sent to a rsync server.
1007
1008 dit(bf(HOME)) The HOME environment variable is used to find the user's
1009 default .cvsignore file.
1010
1011 enddit()
1012
1013 manpagefiles()
1014
1015 /etc/rsyncd.conf
1016
1017 manpageseealso()
1018
1019 rsyncd.conf(5)
1020
1021 manpagediagnostics()
1022
1023 manpagebugs()
1024
1025 times are transferred as unix time_t values
1026
1027 file permissions, devices etc are transferred as native numerical
1028 values
1029
1030 see also the comments on the --delete option
1031
1032 Please report bugs! The rsync bug tracking system is online at
1033 url(http://rsync.samba.org/rsync/)(http://rsync.samba.org/rsync/)
1034
1035 manpagesection(VERSION)
1036 This man page is current for version 2.0 of rsync
1037
1038 manpagesection(CREDITS)
1039
1040 rsync is distributed under the GNU public license.  See the file
1041 COPYING for details.
1042
1043 A WEB site is available at
1044 url(http://rsync.samba.org/)(http://rsync.samba.org/).  The site
1045 includes an FAQ-O-Matic which may cover questions unanswered by this
1046 manual page.
1047
1048 The primary ftp site for rsync is
1049 url(ftp://rsync.samba.org/pub/rsync)(ftp://rsync.samba.org/pub/rsync).
1050
1051 We would be delighted to hear from you if you like this program.
1052
1053 This program uses the excellent zlib compression library written by
1054 Jean-loup Gailly and Mark Adler.
1055
1056 manpagesection(THANKS)
1057
1058 Thanks to Richard Brent, Brendan Mackay, Bill Waite, Stephen Rothwell
1059 and David Bell for helpful suggestions, patches and testing of rsync.
1060 I've probably missed some people, my apologies if I have.
1061
1062 Especial thanks also to: David Dykstra, Jos Backus, Sebastian Krahmer.
1063
1064
1065 manpageauthor()
1066
1067 rsync was written by Andrew Tridgell <tridge@samba.org> and Paul
1068 Mackerras.
1069
1070 rsync is now maintained by Martin Pool <mbp@samba.org>.  
1071
1072 Mailing lists for support and development are available at
1073 url(http://lists.samba.org)(lists.samba.org) 
1074
1075 If you suspect you have found a security vulnerability in rsync,
1076 please send it directly to Martin Pool and Andrew Tridgell.  For other
1077 enquiries, please use the mailing list.