Fix for device nodes. (dann frazier) (Debian #129135)
[rsync/rsync.git] / rsync.yo
... / ...
CommitLineData
1mailto(rsync-bugs@samba.org)
2manpage(rsync)(1)(14 Dec 2001)()()
3manpagename(rsync)(faster, flexible replacement for rcp)
4manpagesynopsis()
5
6rsync [OPTION]... SRC [SRC]... [USER@]HOST:DEST
7
8rsync [OPTION]... [USER@]HOST:SRC DEST
9
10rsync [OPTION]... SRC [SRC]... DEST
11
12rsync [OPTION]... [USER@]HOST::SRC [DEST]
13
14rsync [OPTION]... SRC [SRC]... [USER@]HOST::DEST
15
16rsync [OPTION]... rsync://[USER@]HOST[:PORT]/SRC [DEST]
17
18manpagedescription()
19
20rsync is a program that behaves in much the same way that rcp does,
21but has many more options and uses the rsync remote-update protocol to
22greatly speed up file transfers when the destination file already
23exists.
24
25The rsync remote-update protocol allows rsync to transfer just the
26differences between two sets of files across the network link, using
27an efficient checksum-search algorithm described in the technical
28report that accompanies this package.
29
30Some of the additional features of rsync are:
31
32itemize(
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
43manpagesection(GENERAL)
44
45There are six different ways of using rsync. They are:
46
47itemize(
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
73Note that in all cases (other than listing) at least one of the source
74and destination paths must be local.
75
76manpagesection(SETUP)
77
78See the file README for installation instructions.
79
80Once installed you can use rsync to any machine that you can use rsh
81to. rsync uses rsh for its communications, unless both the source and
82destination are local.
83
84You can also specify an alternative to rsh, either by using the -e
85command line option, or by setting the RSYNC_RSH environment variable.
86
87One common substitute is to use ssh, which offers a high degree of
88security.
89
90Note that rsync must be installed on both the source and destination
91machines.
92
93manpagesection(USAGE)
94
95You use rsync in the same way you use rcp. You must specify a source
96and a destination, one of which may be remote.
97
98Perhaps the best way to explain the syntax is some examples:
99
100quote(rsync *.c foo:src/)
101
102this would transfer all files matching the pattern *.c from the
103current directory to the directory src on the machine foo. If any of
104the files already exist on the remote system then the rsync
105remote-update protocol is used to update the file by sending only the
106differences. See the tech report for details.
107
108quote(rsync -avz foo:src/bar /data/tmp)
109
110this would recursively transfer all files from the directory src/bar on the
111machine foo into the /data/tmp/bar directory on the local machine. The
112files are transferred in "archive" mode, which ensures that symbolic
113links, devices, attributes, permissions, ownerships etc are preserved
114in the transfer. Additionally, compression will be used to reduce the
115size of data portions of the transfer.
116
117quote(rsync -avz foo:src/bar/ /data/tmp)
118
119a trailing slash on the source changes this behavior to transfer
120all files from the directory src/bar on the machine foo into the
121/data/tmp/. A trailing / on a source name means "copy the
122contents of this directory". Without a trailing slash it means "copy
123the directory". This difference becomes particularly important when
124using the --delete option.
125
126You can also use rsync in local-only mode, where both the source and
127destination don't have a ':' in the name. In this case it behaves like
128an improved copy command.
129
130quote(rsync somehost.mydomain.com::)
131
132this would list all the anonymous rsync modules available on the host
133somehost.mydomain.com. (See the following section for more details.)
134
135
136manpagesection(CONNECTING TO AN RSYNC SERVER)
137
138It is also possible to use rsync without using rsh or ssh as the
139transport. In this case you will connect to a remote rsync server
140running on TCP port 873.
141
142You may establish the connection via a web proxy by setting the
143environment variable RSYNC_PROXY to a hostname:port pair pointing to
144your web proxy. Note that your web proxy's configuration must allow
145proxying to port 873.
146
147Using rsync in this way is the same as using it with rsh or ssh except
148that:
149
150itemize(
151 it() you use a double colon :: instead of a single colon to
152 separate the hostname from the path.
153
154 it() the remote server may print a message of the day when you
155 connect.
156
157 it() if you specify no path name on the remote server then the
158 list of accessible paths on the server will be shown.
159
160 it() if you specify no local destination then a listing of the
161 specified files on the remote server is provided.
162)
163
164Some paths on the remote server may require authentication. If so then
165you will receive a password prompt when you connect. You can avoid the
166password prompt by setting the environment variable RSYNC_PASSWORD to
167the password you want to use or using the --password-file option. This
168may be useful when scripting rsync.
169
170WARNING: On some systems environment variables are visible to all
171users. On those systems using --password-file is recommended.
172
173manpagesection(RUNNING AN RSYNC SERVER)
174
175An rsync server is configured using a config file which by default is
176called /etc/rsyncd.conf. Please see the rsyncd.conf(5) man page for more
177information.
178
179manpagesection(EXAMPLES)
180
181Here are some examples of how I use rsync.
182
183To backup my wife's home directory, which consists of large MS Word
184files and mail folders, I use a cron job that runs
185
186quote(rsync -Cavz . arvidsjaur:backup)
187
188each night over a PPP link to a duplicate directory on my machine
189"arvidsjaur".
190
191To synchronize my samba source trees I use the following Makefile
192targets:
193
194quote( get:nl()
195 rsync -avuzb --exclude '*~' samba:samba/ .
196
197 put:nl()
198 rsync -Cavuzb . samba:samba/
199
200 sync: get put)
201
202this allows me to sync with a CVS directory at the other end of the
203link. I then do cvs operations on the remote machine, which saves a
204lot of time as the remote cvs protocol isn't very efficient.
205
206I mirror a directory between my "old" and "new" ftp sites with the
207command
208
209quote(rsync -az -e ssh --delete ~ftp/pub/samba/ nimbus:"~ftp/pub/tridge/samba")
210
211this is launched from cron every few hours.
212
213manpagesection(OPTIONS SUMMARY)
214
215Here is a short summary of the options available in rsync. Please refer
216to the detailed description below for a complete description.
217
218verb(
219 -v, --verbose increase verbosity
220 -q, --quiet decrease verbosity
221 -c, --checksum always checksum
222 -a, --archive archive mode
223 -r, --recursive recurse into directories
224 -R, --relative use relative path names
225 -b, --backup make backups (default ~ suffix)
226 --backup-dir make backups into this directory
227 --suffix=SUFFIX override backup suffix
228 -u, --update update only (don't overwrite newer files)
229 -l, --links copy symlinks as symlinks
230 -L, --copy-links copy the referent of symlinks
231 --copy-unsafe-links copy links outside the source tree
232 --safe-links ignore links outside the destination tree
233 -H, --hard-links preserve hard links
234 -p, --perms preserve permissions
235 -o, --owner preserve owner (root only)
236 -g, --group preserve group
237 -D, --devices preserve devices (root only)
238 -t, --times preserve times
239 -S, --sparse handle sparse files efficiently
240 -n, --dry-run show what would have been transferred
241 -W, --whole-file copy whole files, no incremental checks
242 -x, --one-file-system don't cross filesystem boundaries
243 -B, --block-size=SIZE checksum blocking size (default 700)
244 -e, --rsh=COMMAND specify rsh replacement
245 --rsync-path=PATH specify path to rsync on the remote machine
246 -C, --cvs-exclude auto ignore files in the same way CVS does
247 --existing only update files that already exist
248 --delete delete files that don't exist on the sending side
249 --delete-excluded also delete excluded files on the receiving side
250 --delete-after delete after transferring, not before
251 --ignore-errors delete even if there are IO errors
252 --max-delete=NUM don't delete more than NUM files
253 --partial keep partially transferred files
254 --force force deletion of directories even if not empty
255 --numeric-ids don't map uid/gid values by user/group name
256 --timeout=TIME set IO timeout in seconds
257 -I, --ignore-times don't exclude files that match length and time
258 --size-only only use file size when determining if a file should be transferred
259 --modify-window=NUM Timestamp window (seconds) for file match (default=0)
260 -T --temp-dir=DIR create temporary files in directory DIR
261 --compare-dest=DIR also compare destination files relative to DIR
262 -P equivalent to --partial --progress
263 -z, --compress compress file data
264 --exclude=PATTERN exclude files matching PATTERN
265 --exclude-from=FILE exclude patterns listed in FILE
266 --include=PATTERN don't exclude files matching PATTERN
267 --include-from=FILE don't exclude patterns listed in FILE
268 --version print version number
269 --daemon run as a rsync daemon
270 --no-detach do not detach from the parent
271 --address=ADDRESS bind to the specified address
272 --config=FILE specify alternate rsyncd.conf file
273 --port=PORT specify alternate rsyncd port number
274 --blocking-io use blocking IO for the remote shell
275 --stats give some file transfer stats
276 --progress show progress during transfer
277 --log-format=FORMAT log file transfers using specified format
278 --password-file=FILE get password from FILE
279 --bwlimit=KBPS limit I/O bandwidth, KBytes per second
280 --read-batch=FILE read batch file
281 --write-batch write batch file
282 -h, --help show this help screen
283
284
285)
286
287manpageoptions()
288
289rsync uses the GNU long options package. Many of the command line
290options have two variants, one short and one long. These are shown
291below, separated by commas. Some options only have a long variant.
292The '=' for options that take a parameter is optional; whitespace
293can be used instead.
294
295startdit()
296dit(bf(-h, --help)) Print a short help page describing the options
297available in rsync
298
299dit(bf(--version)) print the rsync version number and exit
300
301dit(bf(-v, --verbose)) This option increases the amount of information you
302are given during the transfer. By default, rsync works silently. A
303single -v will give you information about what files are being
304transferred and a brief summary at the end. Two -v flags will give you
305information on what files are being skipped and slightly more
306information at the end. More than two -v flags should only be used if
307you are debugging rsync.
308
309dit(bf(-q, --quiet)) This option decreases the amount of information you
310are given during the transfer, notably suppressing information messages
311from the remote server. This flag is useful when invoking rsync from
312cron.
313
314dit(bf(-I, --ignore-times)) Normally rsync will skip any files that are
315already the same length and have the same time-stamp. This option turns
316off this behavior.
317
318dit(bf(--size-only)) Normally rsync will skip any files that are
319already the same length and have the same time-stamp. With the
320--size-only option files will be skipped if they have the same size,
321regardless of timestamp. This is useful when starting to use rsync
322after using another mirroring system which may not preserve timestamps
323exactly.
324
325dit(bf(--modify-window)) When comparing two timestamps rsync treats
326the timestamps as being equal if they are within the value of
327modify_window. This is normally zero, but you may find it useful to
328set this to a larger value in some situations. In particular, when
329transferring to/from FAT filesystems which cannot represent times with
330a 1 second resolution this option is useful.
331
332dit(bf(-c, --checksum)) This forces the sender to checksum all files using
333a 128-bit MD4 checksum before transfer. The checksum is then
334explicitly checked on the receiver and any files of the same name
335which already exist and have the same checksum and size on the
336receiver are skipped. This option can be quite slow.
337
338dit(bf(-a, --archive)) This is equivalent to -rlptgoD. It is a quick
339way of saying you want recursion and want to preserve almost
340everything.
341
342Note however that bf(-a) bf(does not preserve hardlinks), because
343finding multiply-linked files is expensive. You must separately
344specify bf(-H).
345
346dit(bf(-r, --recursive)) This tells rsync to copy directories
347recursively. If you don't specify this then rsync won't copy
348directories at all.
349
350dit(bf(-R, --relative)) Use relative paths. This means that the full path
351names specified on the command line are sent to the server rather than
352just the last parts of the filenames. This is particularly useful when
353you want to send several different directories at the same time. For
354example, if you used the command
355
356verb(rsync foo/bar/foo.c remote:/tmp/)
357
358then this would create a file called foo.c in /tmp/ on the remote
359machine. If instead you used
360
361verb(rsync -R foo/bar/foo.c remote:/tmp/)
362
363then a file called /tmp/foo/bar/foo.c would be created on the remote
364machine. The full path name is preserved.
365
366dit(bf(-b, --backup)) With this option preexisting destination files are
367renamed with a ~ extension as each file is transferred. You can
368control the backup suffix using the --suffix option.
369
370dit(bf(--backup-dir=DIR)) In combination with the --backup option, this
371tells rsync to store all backups in the specified directory. This is
372very useful for incremental backups.
373
374dit(bf(--suffix=SUFFIX)) This option allows you to override the default
375backup suffix used with the -b option. The default is a ~.
376
377dit(bf(-u, --update)) This forces rsync to skip any files for which the
378destination file already exists and has a date later than the source
379file.
380
381dit(bf(-l, --links)) When symlinks are encountered, recreate the
382symlink on the destination.
383
384dit(bf(-L, --copy-links)) When symlinks are encountered, the file that
385they point to is copied, rather than the symlink.
386
387dit(bf(--copy-unsafe-links)) This tells rsync to copy the referent of
388symbolic links that point outside the source tree. Absolute symlinks
389are also treated like ordinary files, and so are any symlinks in the
390source path itself when --relative is used.
391
392dit(bf(--safe-links)) This tells rsync to ignore any symbolic links
393which point outside the destination tree. All absolute symlinks are
394also ignored. Using this option in conjunction with --relative may
395give unexpected results.
396
397dit(bf(-H, --hard-links)) This tells rsync to recreate hard links on
398the remote system to be the same as the local system. Without this
399option hard links are treated like regular files.
400
401Note that rsync can only detect hard links if both parts of the link
402are in the list of files being sent.
403
404This option can be quite slow, so only use it if you need it.
405
406dit(bf(-W, --whole-file)) With this option the incremental rsync algorithm
407is not used and the whole file is sent as-is instead. The transfer may be
408faster if this option is used when the bandwidth between the source and
409target machines is higher than the bandwidth to disk (especially when the
410"disk" is actually a networked file system). This is the default when both
411the source and target are on the local machine.
412
413dit(bf(-p, --perms)) This option causes rsync to update the remote
414permissions to be the same as the local permissions.
415
416dit(bf(-o, --owner)) This option causes rsync to set the owner of the
417destination file to be the same as the source file. On most systems,
418only the super-user can set file ownership.
419
420dit(bf(-g, --group)) This option causes rsync to set the group of the
421destination file to be the same as the source file. If the receiving
422program is not running as the super-user, only groups that the
423receiver is a member of will be preserved (by group name, not group id
424number).
425
426dit(bf(-D, --devices)) This option causes rsync to transfer character and
427block device information to the remote system to recreate these
428devices. This option is only available to the super-user.
429
430dit(bf(-t, --times)) This tells rsync to transfer modification times along
431with the files and update them on the remote system. Note that if this
432option is not used, the optimization that excludes files that have not been
433modified cannot be effective; in other words, a missing -t or -a will
434cause the next transfer to behave as if it used -I, and all files will have
435their checksums compared and show up in log messages even if they haven't
436changed.
437
438dit(bf(-n, --dry-run)) This tells rsync to not do any file transfers,
439instead it will just report the actions it would have taken.
440
441dit(bf(-S, --sparse)) Try to handle sparse files efficiently so they take
442up less space on the destination.
443
444NOTE: Don't use this option when the destination is a Solaris "tmpfs"
445filesystem. It doesn't seem to handle seeks over null regions
446correctly and ends up corrupting the files.
447
448dit(bf(-x, --one-file-system)) This tells rsync not to cross filesystem
449boundaries when recursing. This is useful for transferring the
450contents of only one filesystem.
451
452dit(bf(--existing)) This tells rsync not to create any new files -
453only update files that already exist on the destination.
454
455dit(bf(--max-delete=NUM)) This tells rsync not to delete more than NUM
456files or directories. This is useful when mirroring very large trees
457to prevent disasters.
458
459dit(bf(--delete)) This tells rsync to delete any files on the receiving
460side that aren't on the sending side. Files that are excluded from
461transfer are excluded from being deleted unless you use --delete-excluded.
462
463This option has no effect if directory recursion is not selected.
464
465This option can be dangerous if used incorrectly! It is a very good idea
466to run first using the dry run option (-n) to see what files would be
467deleted to make sure important files aren't listed.
468
469If the sending side detects any IO errors then the deletion of any
470files at the destination will be automatically disabled. This is to
471prevent temporary filesystem failures (such as NFS errors) on the
472sending side causing a massive deletion of files on the
473destination. You can override this with the --ignore-errors option.
474
475dit(bf(--delete-excluded)) In addition to deleting the files on the
476receiving side that are not on the sending side, this tells rsync to also
477delete any files on the receiving side that are excluded (see --exclude).
478
479dit(bf(--delete-after)) By default rsync does file deletions before
480transferring files to try to ensure that there is sufficient space on
481the receiving filesystem. If you want to delete after transferring
482then use the --delete-after switch.
483
484dit(bf(--ignore-errors)) Tells --delete to go ahead and delete files
485even when there are IO errors.
486
487dit(bf(--force)) This options tells rsync to delete directories even if
488they are not empty. This applies to both the --delete option and to
489cases where rsync tries to copy a normal file but the destination
490contains a directory of the same name.
491
492Since this option was added, deletions were reordered to be done depth-first
493so it is hardly ever needed anymore except in very obscure cases.
494
495dit(bf(-B , --block-size=BLOCKSIZE)) This controls the block size used in
496the rsync algorithm. See the technical report for details.
497
498dit(bf(-e, --rsh=COMMAND)) This option allows you to choose an alternative
499remote shell program to use for communication between the local and
500remote copies of rsync. By default, rsync will use rsh, but you may
501like to instead use ssh because of its high security.
502
503You can also choose the remote shell program using the RSYNC_RSH
504environment variable.
505
506See also the --blocking-io option which is affected by this option.
507
508dit(bf(--rsync-path=PATH)) Use this to specify the path to the copy of
509rsync on the remote machine. Useful when it's not in your path. Note
510that this is the full path to the binary, not just the directory that
511the binary is in.
512
513dit(bf(--exclude=PATTERN)) This option allows you to selectively exclude
514certain files from the list of files to be transferred. This is most
515useful in combination with a recursive transfer.
516
517You may use as many --exclude options on the command line as you like
518to build up the list of files to exclude.
519
520See the section on exclude patterns for information on the syntax of
521this option.
522
523dit(bf(--exclude-from=FILE)) This option is similar to the --exclude
524option, but instead it adds all exclude patterns listed in the file
525FILE to the exclude list. Blank lines in FILE and lines starting with
526';' or '#' are ignored.
527
528dit(bf(--include=PATTERN)) This option tells rsync to not exclude the
529specified pattern of filenames. This is useful as it allows you to
530build up quite complex exclude/include rules.
531
532See the section of exclude patterns for information on the syntax of
533this option.
534
535dit(bf(--include-from=FILE)) This specifies a list of include patterns
536from a file.
537
538dit(bf(-C, --cvs-exclude)) This is a useful shorthand for excluding a
539broad range of files that you often don't want to transfer between
540systems. It uses the same algorithm that CVS uses to determine if
541a file should be ignored.
542
543The exclude list is initialized to:
544
545quote(RCS SCCS CVS CVS.adm RCSLOG cvslog.* tags TAGS .make.state
546.nse_depinfo *~ #* .#* ,* *.old *.bak *.BAK *.orig *.rej .del-*
547*.a *.o *.obj *.so *.Z *.elc *.ln core)
548
549then files listed in a $HOME/.cvsignore are added to the list and any
550files listed in the CVSIGNORE environment variable (space delimited).
551
552Finally, any file is ignored if it is in the same directory as a
553.cvsignore file and matches one of the patterns listed therein. See
554the bf(cvs(1)) manual for more information.
555
556dit(bf(--csum-length=LENGTH)) By default the primary checksum used in
557rsync is a very strong 16 byte MD4 checksum. In most cases you will
558find that a truncated version of this checksum is quite efficient, and
559this will decrease the size of the checksum data sent over the link,
560making things faster.
561
562You can choose the number of bytes in the truncated checksum using the
563--csum-length option. Any value less than or equal to 16 is valid.
564
565Note that if you use this option then you run the risk of ending up
566with an incorrect target file. The risk with a value of 16 is
567microscopic and can be safely ignored (the universe will probably end
568before it fails) but with smaller values the risk is higher.
569
570Current versions of rsync actually use an adaptive algorithm for the
571checksum length by default, using a 16 byte file checksum to determine
572if a 2nd pass is required with a longer block checksum. Only use this
573option if you have read the source code and know what you are doing.
574
575dit(bf(-T, --temp-dir=DIR)) This option instructs rsync to use DIR as a
576scratch directory when creating temporary copies of the files
577transferred on the receiving side. The default behavior is to create
578the temporary files in the receiving directory.
579
580dit(bf(--compare-dest=DIR)) This option instructs rsync to use DIR on
581the destination machine as an additional directory to compare destination
582files against when doing transfers. This is useful for doing transfers to
583a new destination while leaving existing files intact, and then doing a
584flash-cutover when all files have been successfully transferred (for
585example by moving directories around and removing the old directory,
586although this requires also doing the transfer with -I to avoid skipping
587files that haven't changed). This option increases the usefulness of
588--partial because partially transferred files will remain in the new
589temporary destination until they have a chance to be completed. If DIR is
590a relative path, it is relative to the destination directory.
591
592dit(bf(-z, --compress)) With this option, rsync compresses any data from
593the files that it sends to the destination machine. This
594option is useful on slow links. The compression method used is the
595same method that gzip uses.
596
597Note this this option typically achieves better compression ratios
598that can be achieved by using a compressing remote shell, or a
599compressing transport, as it takes advantage of the implicit
600information sent for matching data blocks.
601
602dit(bf(--numeric-ids)) With this option rsync will transfer numeric group
603and user ids rather than using user and group names and mapping them
604at both ends.
605
606By default rsync will use the user name and group name to determine
607what ownership to give files. The special uid 0 and the special group
6080 are never mapped via user/group names even if the --numeric-ids
609option is not specified.
610
611If the source system is a daemon using chroot, or if a user or group
612name does not exist on the destination system, then the numeric id
613from the source system is used instead.
614
615dit(bf(--timeout=TIMEOUT)) This option allows you to set a maximum IO
616timeout in seconds. If no data is transferred for the specified time
617then rsync will exit. The default is 0, which means no timeout.
618
619dit(bf(--daemon)) This tells rsync that it is to run as a daemon. The
620daemon may be accessed using the bf(host::module) or
621bf(rsync://host/module/) syntax.
622
623If standard input is a socket then rsync will assume that it is being
624run via inetd, otherwise it will detach from the current terminal and
625become a background daemon. The daemon will read the config file
626(/etc/rsyncd.conf) on each connect made by a client and respond to
627requests accordingly. See the rsyncd.conf(5) man page for more
628details.
629
630dit(bf(--no-detach)) When running as a daemon, this option instructs
631rsync to not detach itself and become a background process. This
632option is required when running as a service on Cygwin, and may also
633be useful when rsync is supervised by a program such as
634bf(daemontools) or AIX's bf(System Resource Controller).
635bf(--no-detach) is also recommended when rsync is run under a
636debugger. This option has no effect if rsync is run from inetd or
637sshd.
638
639dit(bf(--address)) By default rsync will bind to the wildcard address
640when run as a daemon with the --daemon option or when connecting to a
641rsync server. The --address option allows you to specify a specific IP
642address (or hostname) to bind to. This makes virtual hosting possible
643in conjunction with the --config option.
644
645dit(bf(--config=FILE)) This specifies an alternate config file than
646the default /etc/rsyncd.conf. This is only relevant when --daemon is
647specified.
648
649dit(bf(--port=PORT)) This specifies an alternate TCP port number to use
650rather than the default port 873.
651
652dit(bf(--blocking-io)) This tells rsync to use blocking IO when launching
653a remote shell transport. If -e or --rsh are not specified or are set to
654the default "rsh", this defaults to blocking IO, otherwise it defaults to
655non-blocking IO. You may find the --blocking-io option is needed for some
656remote shells that can't handle non-blocking IO. Ssh prefers blocking IO.
657
658dit(bf(--log-format=FORMAT)) This allows you to specify exactly what the
659rsync client logs to stdout on a per-file basis. The log format is
660specified using the same format conventions as the log format option in
661rsyncd.conf.
662
663dit(bf(--stats)) This tells rsync to print a verbose set of statistics
664on the file transfer, allowing you to tell how effective the rsync
665algorithm is for your data.
666
667dit(bf(--partial)) By default, rsync will delete any partially
668transferred file if the transfer is interrupted. In some circumstances
669it is more desirable to keep partially transferred files. Using the
670--partial option tells rsync to keep the partial file which should
671make a subsequent transfer of the rest of the file much faster.
672
673dit(bf(--progress)) This option tells rsync to print information
674showing the progress of the transfer. This gives a bored user
675something to watch.
676
677This option is normally combined with -v. Using this option without
678the -v option will produce weird results on your display.
679
680dit(bf(-P)) The -P option is equivalent to --partial --progress. I
681found myself typing that combination quite often so I created an
682option to make it easier.
683
684dit(bf(--password-file)) This option allows you to provide a password
685in a file for accessing a remote rsync server. Note that this option
686is only useful when accessing a rsync server using the built in
687transport, not when using a remote shell as the transport. The file
688must not be world readable. It should contain just the password as a
689single line.
690
691dit(bf(--bwlimit=KBPS)) This option allows you to specify a maximum
692transfer rate in kilobytes per second. This option is most effective when
693using rsync with large files (several megabytes and up). Due to the nature
694of rsync transfers, blocks of data are sent, then if rsync determines the
695transfer was too fast, it will wait before sending the next data block. The
696result is an average transfer rate equalling the specified limit. A value
697of zero specifies no limit.
698
699dit(bf(--read-batch)) Apply a previously generated change batch.
700
701dit(bf(--write-batch)) Generate a set of files that can be transferred
702as a batch update.
703
704enddit()
705
706manpagesection(EXCLUDE PATTERNS)
707
708The exclude and include patterns specified to rsync allow for flexible
709selection of which files to transfer and which files to skip.
710
711rsync builds an ordered list of include/exclude options as specified on
712the command line. When a filename is encountered, rsync checks the
713name against each exclude/include pattern in turn. The first matching
714pattern is acted on. If it is an exclude pattern, then that file is
715skipped. If it is an include pattern then that filename is not
716skipped. If no matching include/exclude pattern is found then the
717filename is not skipped.
718
719Note that when used with -r (which is implied by -a), every subcomponent of
720every path is visited from top down, so include/exclude patterns get
721applied recursively to each subcomponent.
722
723Note also that the --include and --exclude options take one pattern
724each. To add multiple patterns use the --include-from and
725--exclude-from options or multiple --include and --exclude options.
726
727The patterns can take several forms. The rules are:
728
729itemize(
730 it() if the pattern starts with a / then it is matched against the
731 start of the filename, otherwise it is matched against the end of
732 the filename. Thus "/foo" would match a file called "foo" at the base of
733 the tree. On the other hand, "foo" would match any file called "foo"
734 anywhere in the tree because the algorithm is applied recursively from
735 top down; it behaves as if each path component gets a turn at being the
736 end of the file name.
737
738 it() if the pattern ends with a / then it will only match a
739 directory, not a file, link or device.
740
741 it() if the pattern contains a wildcard character from the set
742 *?[ then expression matching is applied using the shell filename
743 matching rules. Otherwise a simple string match is used.
744
745 it() if the pattern includes a double asterisk "**" then all wildcards in
746 the pattern will match slashes, otherwise they will stop at slashes.
747
748 it() if the pattern contains a / (not counting a trailing /) then it
749 is matched against the full filename, including any leading
750 directory. If the pattern doesn't contain a / then it is matched
751 only against the final component of the filename. Again, remember
752 that the algorithm is applied recursively so "full filename" can
753 actually be any portion of a path.
754
755 it() if the pattern starts with "+ " (a plus followed by a space)
756 then it is always considered an include pattern, even if specified as
757 part of an exclude option. The "+ " part is discarded before matching.
758
759 it() if the pattern starts with "- " (a minus followed by a space)
760 then it is always considered an exclude pattern, even if specified as
761 part of an include option. The "- " part is discarded before matching.
762
763 it() if the pattern is a single exclamation mark ! then the current
764 include/exclude list is reset, removing all previously defined patterns.
765)
766
767The +/- rules are most useful in exclude lists, allowing you to have a
768single exclude list that contains both include and exclude options.
769
770If you end an exclude list with --exclude '*', note that since the
771algorithm is applied recursively that unless you explicitly include
772parent directories of files you want to include then the algorithm
773will stop at the parent directories and never see the files below
774them. To include all directories, use --include '*/' before the
775--exclude '*'.
776
777Here are some exclude/include examples:
778
779itemize(
780 it() --exclude "*.o" would exclude all filenames matching *.o
781 it() --exclude "/foo" would exclude a file in the base directory called foo
782 it() --exclude "foo/" would exclude any directory called foo
783 it() --exclude "/foo/*/bar" would exclude any file called bar two
784 levels below a base directory called foo
785 it() --exclude "/foo/**/bar" would exclude any file called bar two
786 or more levels below a base directory called foo
787 it() --include "*/" --include "*.c" --exclude "*" would include all
788 directories and C source files
789 it() --include "foo/" --include "foo/bar.c" --exclude "*" would include
790 only foo/bar.c (the foo/ directory must be explicitly included or
791 it would be excluded by the "*")
792)
793
794manpagesection(BATCH MODE)
795
796bf(Note:) Batch mode should be considered experimental in this version
797of rsync. The interface or behaviour may change before it stabilizes.
798
799The following call generates 4 files that encapsulate the information
800for synchronizing the contents of bf(target_dir) with the updates found in
801bf(src_dir)
802
803quote(
804$ rsync --write-batch [other rsync options here] \nl()
805 /somewhere/src_dir /somewhere/target_dir
806)
807
808The generated files are labeled with a common timestamp:
809
810itemize(
811it() bf(rsync_argvs.<timestamp>) command-line arguments
812it() bf(rsync_flist.<timestamp>) rsync internal file metadata
813it() bf(rsync_csums.<timestamp>) rsync checksums
814it() bf(rsync_delta.<timestamp>) data blocks for file update & change
815)
816
817See bf(http://www.ils.unc.edu/i2dsi/unc_rsync+.html) for papers and technical
818reports.
819
820manpagesection(SYMBOLIC LINKS)
821
822Three basic behaviours are possible when rsync encounters a symbolic
823link in the source directory.
824
825By default, symbolic links are not transferred at all. A message
826"skipping non-regular" file is emitted for any symlinks that exist.
827
828If bf(--links) is specified, then symlinks are recreated with the same
829target on the destination. Note that bf(--archive) implies
830bf(--links).
831
832If bf(--copy-links) is specified, then symlinks are "collapsed" by
833copying their referent, rather than the symlink.
834
835rsync also distinguishes "safe" and "unsafe" symbolic links. An
836example where this might be used is a web site mirror that wishes
837ensure the rsync module they copy does not include symbolic links to
838bf(/etc/passwd) in the public section of the site. Using
839bf(--copy-unsafe-links) will cause any links to be copied as the file
840they point to on the destination. Using bf(--safe-links) will cause
841unsafe links to be ommitted altogether.
842
843manpagesection(DIAGNOSTICS)
844
845rsync occasionally produces error messages that may seem a little
846cryptic. The one that seems to cause the most confusion is "protocol
847version mismatch - is your shell clean?".
848
849This message is usually caused by your startup scripts or remote shell
850facility producing unwanted garbage on the stream that rsync is using
851for its transport. The way to diagnose this problem is to run your
852remote shell like this:
853
854verb(
855 rsh remotehost /bin/true > out.dat
856)
857
858then look at out.dat. If everything is working correctly then out.dat
859should be a zero length file. If you are getting the above error from
860rsync then you will probably find that out.dat contains some text or
861data. Look at the contents and try to work out what is producing
862it. The most common cause is incorrectly configured shell startup
863scripts (such as .cshrc or .profile) that contain output statements
864for non-interactive logins.
865
866If you are having trouble debugging include and exclude patterns, then
867try specifying the -vv option. At this level of verbosity rsync will
868show why each individual file is included or excluded.
869
870manpagesection(EXIT VALUES)
871
872startdit()
873dit(bf(RERR_SYNTAX 1)) Syntax or usage error
874dit(bf(RERR_PROTOCOL 2)) Protocol incompatibility
875dit(bf(RERR_FILESELECT 3)) Errors selecting input/output files, dirs
876
877dit(bf(RERR_UNSUPPORTED 4)) Requested action not supported: an attempt
878was made to manipulate 64-bit files on a platform that cannot support
879them; or an option was speciifed that is supported by the client and
880not by the server.
881
882dit(bf(RERR_SOCKETIO 10)) Error in socket IO
883dit(bf(RERR_FILEIO 11)) Error in file IO
884dit(bf(RERR_STREAMIO 12)) Error in rsync protocol data stream
885dit(bf(RERR_MESSAGEIO 13)) Errors with program diagnostics
886dit(bf(RERR_IPC 14)) Error in IPC code
887dit(bf(RERR_SIGNAL 20)) Received SIGUSR1 or SIGINT
888dit(bf(RERR_WAITCHILD 21)) Some error returned by waitpid()
889dit(bf(RERR_MALLOC 22)) Error allocating core memory buffers
890dit(bf(RERR_TIMEOUT 30)) Timeout in data send/receive
891enddit()
892
893manpagesection(ENVIRONMENT VARIABLES)
894
895startdit()
896
897dit(bf(CVSIGNORE)) The CVSIGNORE environment variable supplements any
898ignore patterns in .cvsignore files. See the --cvs-exclude option for
899more details.
900
901dit(bf(RSYNC_RSH)) The RSYNC_RSH environment variable allows you to
902override the default shell used as the transport for rsync. This can
903be used instead of the -e option.
904
905dit(bf(RSYNC_PROXY)) The RSYNC_PROXY environment variable allows you to
906redirect your rsync client to use a web proxy when connecting to a
907rsync daemon. You should set RSYNC_PROXY to a hostname:port pair.
908
909dit(bf(RSYNC_PASSWORD)) Setting RSYNC_PASSWORD to the required
910password allows you to run authenticated rsync connections to a rsync
911daemon without user intervention. Note that this does not supply a
912password to a shell transport such as ssh.
913
914dit(bf(USER) or bf(LOGNAME)) The USER or LOGNAME environment variables
915are used to determine the default username sent to a rsync server.
916
917dit(bf(HOME)) The HOME environment variable is used to find the user's
918default .cvsignore file.
919
920enddit()
921
922manpagefiles()
923
924/etc/rsyncd.conf
925
926manpageseealso()
927
928rsyncd.conf(5)
929
930manpagediagnostics()
931
932manpagebugs()
933
934times are transferred as unix time_t values
935
936file permissions, devices etc are transferred as native numerical
937values
938
939see also the comments on the --delete option
940
941Please report bugs! The rsync bug tracking system is online at
942url(http://rsync.samba.org/rsync/)(http://rsync.samba.org/rsync/)
943
944manpagesection(VERSION)
945This man page is current for version 2.0 of rsync
946
947manpagesection(CREDITS)
948
949rsync is distributed under the GNU public license. See the file
950COPYING for details.
951
952A WEB site is available at
953url(http://rsync.samba.org/)(http://rsync.samba.org/). The site
954includes an FAQ-O-Matic which may cover questions unanswered by this
955manual page.
956
957The primary ftp site for rsync is
958url(ftp://rsync.samba.org/pub/rsync)(ftp://rsync.samba.org/pub/rsync).
959
960We would be delighted to hear from you if you like this program.
961
962This program uses the excellent zlib compression library written by
963Jean-loup Gailly and Mark Adler.
964
965manpagesection(THANKS)
966
967Thanks to Richard Brent, Brendan Mackay, Bill Waite, Stephen Rothwell
968and David Bell for helpful suggestions, patches and testing of rsync.
969I've probably missed some people, my apologies if I have.
970
971Especial thanks also to: David Dykstra, Jos Backus, Sebastian Krahmer.
972
973
974manpageauthor()
975
976rsync was written by Andrew Tridgell <tridge@samba.org> and Paul
977Mackerras.
978
979rsync is now maintained by Martin Pool <mbp@samba.org>.
980
981Mailing lists for support and development are available at
982url(http://lists.samba.org)(lists.samba.org)
983
984If you suspect you have found a security vulnerability in rsync,
985please send it directly to Martin Pool and Andrew Tridgell. For other
986enquiries, please use the mailing list.