Mention that the --bwlimit may now be combined with --daemon.
[rsync/rsync.git] / rsync.yo
CommitLineData
9e3c856a 1mailto(rsync-bugs@samba.org)
618c8a73 2manpage(rsync)(1)(30 Sep 2004)()()
41059f75
AT
3manpagename(rsync)(faster, flexible replacement for rcp)
4manpagesynopsis()
5
9ef53907 6rsync [OPTION]... SRC [SRC]... [USER@]HOST:DEST
41059f75 7
9ef53907 8rsync [OPTION]... [USER@]HOST:SRC DEST
41059f75 9
9ef53907 10rsync [OPTION]... SRC [SRC]... DEST
41059f75 11
9ef53907 12rsync [OPTION]... [USER@]HOST::SRC [DEST]
41059f75 13
9ef53907 14rsync [OPTION]... SRC [SRC]... [USER@]HOST::DEST
41059f75 15
9ef53907 16rsync [OPTION]... rsync://[USER@]HOST[:PORT]/SRC [DEST]
039faa86 17
8d69d571
WD
18rsync [OPTION]... SRC [SRC]... rsync://[USER@]HOST[:PORT]/DEST
19
41059f75
AT
20manpagedescription()
21
22rsync is a program that behaves in much the same way that rcp does,
23but has many more options and uses the rsync remote-update protocol to
675ef1aa
WD
24greatly speed up file transfers when the destination file is being
25updated.
41059f75
AT
26
27The rsync remote-update protocol allows rsync to transfer just the
f39281ae 28differences between two sets of files across the network connection, using
41059f75
AT
29an efficient checksum-search algorithm described in the technical
30report that accompanies this package.
31
32Some of the additional features of rsync are:
33
34itemize(
b9f592fb 35 it() support for copying links, devices, owners, groups, and permissions
41059f75
AT
36 it() exclude and exclude-from options similar to GNU tar
37 it() a CVS exclude mode for ignoring the same files that CVS would ignore
43cd760f 38 it() can use any transparent remote shell, including ssh or rsh
41059f75
AT
39 it() does not require root privileges
40 it() pipelining of file transfers to minimize latency costs
41 it() support for anonymous or authenticated rsync servers (ideal for
42 mirroring)
43)
44
45manpagesection(GENERAL)
46
bef49340 47There are eight different ways of using rsync. They are:
41059f75
AT
48
49itemize(
50 it() for copying local files. This is invoked when neither
51 source nor destination path contains a : separator
52
53 it() for copying from the local machine to a remote machine using
43cd760f
WD
54 a remote shell program as the transport (such as ssh or
55 rsh). This is invoked when the destination path contains a
41059f75
AT
56 single : separator.
57
58 it() for copying from a remote machine to the local machine
6c7c2ef3 59 using a remote shell program. This is invoked when the source
41059f75
AT
60 contains a : separator.
61
62 it() for copying from a remote rsync server to the local
63 machine. This is invoked when the source path contains a ::
bb18e755 64 separator or an rsync:// URL.
41059f75
AT
65
66 it() for copying from the local machine to a remote rsync
67 server. This is invoked when the destination path contains a ::
bb18e755 68 separator or an rsync:// URL.
039faa86 69
bef49340
WD
70 it() for copying from a remote machine using a remote shell
71 program as the transport, using rsync server on the remote
72 machine. This is invoked when the source path contains a ::
73 separator and the --rsh=COMMAND (aka "-e COMMAND") option is
74 also provided.
75
76 it() for copying from the local machine to a remote machine
77 using a remote shell program as the transport, using rsync
78 server on the remote machine. This is invoked when the
79 destination path contains a :: separator and the
4d888108 80 --rsh=COMMAND option is also provided.
bef49340 81
039faa86
AT
82 it() for listing files on a remote machine. This is done the
83 same way as rsync transfers except that you leave off the
84 local destination.
41059f75
AT
85)
86
14d43f1f
DD
87Note that in all cases (other than listing) at least one of the source
88and destination paths must be local.
41059f75
AT
89
90manpagesection(SETUP)
91
92See the file README for installation instructions.
93
1bbf83c0
WD
94Once installed, you can use rsync to any machine that you can access via
95a remote shell (as well as some that you can access using the rsync
43cd760f 96daemon-mode protocol). For remote transfers, a modern rsync uses ssh
1bbf83c0 97for its communications, but it may have been configured to use a
43cd760f 98different remote shell by default, such as rsh or remsh.
41059f75 99
1bbf83c0 100You can also specify any remote shell you like, either by using the -e
41059f75
AT
101command line option, or by setting the RSYNC_RSH environment variable.
102
103One common substitute is to use ssh, which offers a high degree of
104security.
105
8e987130
AT
106Note that rsync must be installed on both the source and destination
107machines.
108
41059f75
AT
109manpagesection(USAGE)
110
111You use rsync in the same way you use rcp. You must specify a source
112and a destination, one of which may be remote.
113
4d888108 114Perhaps the best way to explain the syntax is with some examples:
41059f75 115
675ef1aa 116quote(rsync -t *.c foo:src/)
41059f75 117
8a97fc2e 118This would transfer all files matching the pattern *.c from the
41059f75
AT
119current directory to the directory src on the machine foo. If any of
120the files already exist on the remote system then the rsync
121remote-update protocol is used to update the file by sending only the
122differences. See the tech report for details.
123
124quote(rsync -avz foo:src/bar /data/tmp)
125
8a97fc2e 126This would recursively transfer all files from the directory src/bar on the
41059f75
AT
127machine foo into the /data/tmp/bar directory on the local machine. The
128files are transferred in "archive" mode, which ensures that symbolic
b5accaba 129links, devices, attributes, permissions, ownerships, etc. are preserved
14d43f1f 130in the transfer. Additionally, compression will be used to reduce the
41059f75
AT
131size of data portions of the transfer.
132
133quote(rsync -avz foo:src/bar/ /data/tmp)
134
8a97fc2e
WD
135A trailing slash on the source changes this behavior to avoid creating an
136additional directory level at the destination. You can think of a trailing
137/ on a source as meaning "copy the contents of this directory" as opposed
138to "copy the directory by name", but in both cases the attributes of the
139containing directory are transferred to the containing directory on the
140destination. In other words, each of the following commands copies the
141files in the same way, including their setting of the attributes of
142/dest/foo:
143
675ef1aa
WD
144quote(rsync -av /src/foo /dest)
145quote(rsync -av /src/foo/ /dest/foo)
41059f75
AT
146
147You can also use rsync in local-only mode, where both the source and
148destination don't have a ':' in the name. In this case it behaves like
149an improved copy command.
150
14d43f1f
DD
151quote(rsync somehost.mydomain.com::)
152
8a97fc2e 153This would list all the anonymous rsync modules available on the host
14d43f1f
DD
154somehost.mydomain.com. (See the following section for more details.)
155
41059f75 156
675ef1aa
WD
157manpagesection(ADVANCED USAGE)
158
159The syntax for requesting multiple files from a remote host involves using
160quoted spaces in the SRC. Some examples:
161
162quote(rsync host::'modname/dir1/file1 modname/dir2/file2' /dest)
163
164This would copy file1 and file2 into /dest from an rsync daemon. Each
165additional arg must include the same "modname/" prefix as the first one,
166and must be preceded by a single space. All other spaces are assumed
167to be a part of the filenames.
168
169quote(rsync -av host:'dir1/file1 dir2/file2' /dest)
170
171This would copy file1 and file2 into /dest using a remote shell. This
172word-splitting is done by the remote shell, so if it doesn't work it means
173that the remote shell isn't configured to split its args based on
174whitespace (a very rare setting, but not unknown). If you need to transfer
175a filename that contains whitespace, you'll need to either escape the
176whitespace in a way that the remote shell will understand, or use wildcards
177in place of the spaces. Two examples of this are:
178
179quote(rsync -av host:'file\ name\ with\ spaces' /dest)
180quote(rsync -av host:file?name?with?spaces /dest)
181
182This latter example assumes that your shell passes through unmatched
183wildcards. If it complains about "no match", put the name in quotes.
184
185
41059f75
AT
186manpagesection(CONNECTING TO AN RSYNC SERVER)
187
1bbf83c0 188It is also possible to use rsync without a remote shell as the
41059f75
AT
189transport. In this case you will connect to a remote rsync server
190running on TCP port 873.
191
eb06fa95 192You may establish the connection via a web proxy by setting the
4c3b4b25 193environment variable RSYNC_PROXY to a hostname:port pair pointing to
4d888108
WD
194your web proxy. Note that your web proxy's configuration must support
195proxy connections to port 873.
4c3b4b25 196
1bbf83c0 197Using rsync in this way is the same as using it with a remote shell except
41059f75
AT
198that:
199
200itemize(
201 it() you use a double colon :: instead of a single colon to
bb18e755 202 separate the hostname from the path or an rsync:// URL.
41059f75
AT
203
204 it() the remote server may print a message of the day when you
14d43f1f 205 connect.
41059f75
AT
206
207 it() if you specify no path name on the remote server then the
208 list of accessible paths on the server will be shown.
14d43f1f 209
f7632fc6 210 it() if you specify no local destination then a listing of the
14d43f1f 211 specified files on the remote server is provided.
41059f75
AT
212)
213
4c3d16be
AT
214Some paths on the remote server may require authentication. If so then
215you will receive a password prompt when you connect. You can avoid the
216password prompt by setting the environment variable RSYNC_PASSWORD to
65575e96
AT
217the password you want to use or using the --password-file option. This
218may be useful when scripting rsync.
4c3d16be 219
3bc67f0c 220WARNING: On some systems environment variables are visible to all
65575e96 221users. On those systems using --password-file is recommended.
3bc67f0c 222
bef49340
WD
223manpagesection(CONNECTING TO AN RSYNC SERVER OVER A REMOTE SHELL PROGRAM)
224
225It is sometimes useful to be able to set up file transfers using rsync
43cd760f
WD
226server capabilities on the remote machine, while still using ssh or
227rsh for transport. This is especially useful when you want to connect
bef49340
WD
228to a remote machine via ssh (for encryption or to get through a
229firewall), but you still want to have access to the rsync server
230features (see RUNNING AN RSYNC SERVER OVER A REMOTE SHELL PROGRAM,
231below).
232
233From the user's perspective, using rsync in this way is the same as
234using it to connect to an rsync server, except that you must
235explicitly set the remote shell program on the command line with
236--rsh=COMMAND. (Setting RSYNC_RSH in the environment will not turn on
237this functionality.)
238
239In order to distinguish between the remote-shell user and the rsync
240server user, you can use '-l user' on your remote-shell command:
241
242quote(rsync -av --rsh="ssh -l ssh-user" rsync-user@host::module[/path] local-path)
243
244The "ssh-user" will be used at the ssh level; the "rsync-user" will be
245used to check against the rsyncd.conf on the remote host.
246
41059f75
AT
247manpagesection(RUNNING AN RSYNC SERVER)
248
4d888108 249An rsync server is configured using a configuration file. Please see the
30e8c8e1
DD
250rsyncd.conf(5) man page for more information. By default the configuration
251file is called /etc/rsyncd.conf, unless rsync is running over a remote
252shell program and is not running as root; in that case, the default name
253is rsyncd.conf in the current directory on the remote computer
254(typically $HOME).
41059f75 255
bef49340
WD
256manpagesection(RUNNING AN RSYNC SERVER OVER A REMOTE SHELL PROGRAM)
257
258See the rsyncd.conf(5) man page for full information on the rsync
259server configuration file.
260
261Several configuration options will not be available unless the remote
262user is root (e.g. chroot, setuid/setgid, etc.). There is no need to
263configure inetd or the services map to include the rsync server port
264if you run an rsync server only via a remote shell program.
265
e6f9e388
WD
266To run an rsync server out of a single-use ssh key, see this section
267in the rsyncd.conf(5) man page.
bef49340 268
41059f75
AT
269manpagesection(EXAMPLES)
270
271Here are some examples of how I use rsync.
272
14d43f1f
DD
273To backup my wife's home directory, which consists of large MS Word
274files and mail folders, I use a cron job that runs
41059f75
AT
275
276quote(rsync -Cavz . arvidsjaur:backup)
277
f39281ae 278each night over a PPP connection to a duplicate directory on my machine
41059f75
AT
279"arvidsjaur".
280
281To synchronize my samba source trees I use the following Makefile
282targets:
283
284quote( get:nl()
285 rsync -avuzb --exclude '*~' samba:samba/ .
286
287 put:nl()
288 rsync -Cavuzb . samba:samba/
289
290 sync: get put)
291
292this allows me to sync with a CVS directory at the other end of the
f39281ae 293connection. I then do cvs operations on the remote machine, which saves a
41059f75
AT
294lot of time as the remote cvs protocol isn't very efficient.
295
296I mirror a directory between my "old" and "new" ftp sites with the
297command
298
299quote(rsync -az -e ssh --delete ~ftp/pub/samba/ nimbus:"~ftp/pub/tridge/samba")
300
301this is launched from cron every few hours.
302
c95da96a
AT
303manpagesection(OPTIONS SUMMARY)
304
14d43f1f 305Here is a short summary of the options available in rsync. Please refer
c95da96a
AT
306to the detailed description below for a complete description.
307
308verb(
309 -v, --verbose increase verbosity
b86f0cef 310 -q, --quiet decrease verbosity
c95da96a 311 -c, --checksum always checksum
06891710 312 -a, --archive archive mode, equivalent to -rlptgoD
c95da96a
AT
313 -r, --recursive recurse into directories
314 -R, --relative use relative path names
f177b7cc
WD
315 --no-relative turn off --relative
316 --no-implied-dirs don't send implied dirs with -R
915dd207 317 -b, --backup make backups (see --suffix & --backup-dir)
5b56cc19 318 --backup-dir make backups into this directory
915dd207 319 --suffix=SUFFIX backup suffix (default ~ w/o --backup-dir)
c95da96a 320 -u, --update update only (don't overwrite newer files)
75b243a5 321 --inplace update the destination files inplace
716e73d4 322 -K, --keep-dirlinks treat symlinked dir on receiver as dir
eb06fa95 323 -l, --links copy symlinks as symlinks
7af4227a
WD
324 -L, --copy-links copy the referent of all symlinks
325 --copy-unsafe-links copy the referent of "unsafe" symlinks
326 --safe-links ignore "unsafe" symlinks
c95da96a
AT
327 -H, --hard-links preserve hard links
328 -p, --perms preserve permissions
329 -o, --owner preserve owner (root only)
330 -g, --group preserve group
331 -D, --devices preserve devices (root only)
332 -t, --times preserve times
333 -S, --sparse handle sparse files efficiently
334 -n, --dry-run show what would have been transferred
335 -W, --whole-file copy whole files, no incremental checks
93689aa5 336 --no-whole-file turn off --whole-file
c95da96a 337 -x, --one-file-system don't cross filesystem boundaries
3ed8eb3f 338 -B, --block-size=SIZE force a fixed checksum block-size
915dd207 339 -e, --rsh=COMMAND specify the remote shell
d9fcc198 340 --rsync-path=PATH specify path to rsync on the remote machine
1347d512 341 --existing only update files that already exist
915dd207
WD
342 --ignore-existing ignore files that already exist on receiver
343 --delete delete files that don't exist on sender
344 --delete-excluded also delete excluded files on receiver
d48c8065 345 --delete-after receiver deletes after transfer, not before
b5accaba 346 --ignore-errors delete even if there are I/O errors
0b73ca12 347 --max-delete=NUM don't delete more than NUM files
3610c458 348 --max-size=SIZE don't transfer any file larger than SIZE
c95da96a 349 --partial keep partially transferred files
44cad59f 350 --partial-dir=DIR put a partially transferred file into DIR
915dd207 351 --force force deletion of dirs even if not empty
c95da96a 352 --numeric-ids don't map uid/gid values by user/group name
b5accaba 353 --timeout=TIME set I/O timeout in seconds
915dd207
WD
354 -I, --ignore-times turn off mod time & file size quick check
355 --size-only ignore mod time for quick check (use size)
f6aeaa74 356 --modify-window=NUM compare mod times with reduced accuracy
c95da96a 357 -T --temp-dir=DIR create temporary files in directory DIR
915dd207 358 --compare-dest=DIR also compare received files relative to DIR
59c95e42 359 --link-dest=DIR create hardlinks to DIR for unchanged files
d9fcc198 360 -P equivalent to --partial --progress
c95da96a 361 -z, --compress compress file data
f177b7cc 362 -C, --cvs-exclude auto ignore files in the same way CVS does
2acf81eb 363 --exclude=PATTERN exclude files matching PATTERN
9ef53907 364 --exclude-from=FILE exclude patterns listed in FILE
2acf81eb 365 --include=PATTERN don't exclude files matching PATTERN
9ef53907 366 --include-from=FILE don't exclude patterns listed in FILE
f177b7cc 367 --files-from=FILE read FILE for list of source-file names
915dd207 368 -0 --from0 all file lists are delimited by nulls
c95da96a 369 --version print version number
b5accaba 370 --blocking-io use blocking I/O for the remote shell
93689aa5 371 --no-blocking-io turn off --blocking-io
c95da96a 372 --stats give some file transfer stats
eb86d661 373 --progress show progress during transfer
b6062654 374 --log-format=FORMAT log file transfers using specified format
9ef53907 375 --password-file=FILE get password from FILE
ef5d23eb 376 --bwlimit=KBPS limit I/O bandwidth, KBytes per second
b9f592fb
WD
377 --write-batch=FILE write a batch to FILE
378 --read-batch=FILE read a batch from FILE
c8d895de 379 --checksum-seed=NUM set block/file checksum seed
e40a46de
WD
380 -4 --ipv4 prefer IPv4
381 -6 --ipv6 prefer IPv6
c95da96a 382 -h, --help show this help screen
bdf278f7 383)
6902ed17 384
bdf278f7 385Rsync can also be run as a daemon, in which case the following options are accepted:
6902ed17 386
bdf278f7
WD
387verb(
388 --daemon run as an rsync daemon
389 --address=ADDRESS bind to the specified address
1f69bec4 390 --bwlimit=KBPS limit I/O bandwidth, KBytes per second
bdf278f7
WD
391 --config=FILE specify alternate rsyncd.conf file
392 --no-detach do not detach from the parent
393 --port=PORT specify alternate rsyncd port number
394 -4 --ipv4 prefer IPv4
395 -6 --ipv6 prefer IPv6
396 -h, --help show this help screen
c95da96a
AT
397)
398
41059f75
AT
399manpageoptions()
400
401rsync uses the GNU long options package. Many of the command line
402options have two variants, one short and one long. These are shown
14d43f1f 403below, separated by commas. Some options only have a long variant.
b5679335
DD
404The '=' for options that take a parameter is optional; whitespace
405can be used instead.
41059f75
AT
406
407startdit()
408dit(bf(-h, --help)) Print a short help page describing the options
bdf278f7 409available in rsync.
41059f75 410
bdf278f7 411dit(bf(--version)) print the rsync version number and exit.
41059f75
AT
412
413dit(bf(-v, --verbose)) This option increases the amount of information you
14d43f1f 414are given during the transfer. By default, rsync works silently. A
41059f75
AT
415single -v will give you information about what files are being
416transferred and a brief summary at the end. Two -v flags will give you
417information on what files are being skipped and slightly more
418information at the end. More than two -v flags should only be used if
14d43f1f 419you are debugging rsync.
41059f75 420
b86f0cef
DD
421dit(bf(-q, --quiet)) This option decreases the amount of information you
422are given during the transfer, notably suppressing information messages
423from the remote server. This flag is useful when invoking rsync from
424cron.
425
41059f75 426dit(bf(-I, --ignore-times)) Normally rsync will skip any files that are
915dd207
WD
427already the same size and have the same modification time-stamp.
428This option turns off this "quick check" behavior.
41059f75 429
a03a9f4e 430dit(bf(--size-only)) Normally rsync will not transfer any files that are
915dd207 431already the same size and have the same modification time-stamp. With the
a03a9f4e 432--size-only option, files will not be transferred if they have the same size,
f83f0548
AT
433regardless of timestamp. This is useful when starting to use rsync
434after using another mirroring system which may not preserve timestamps
435exactly.
436
5b56cc19
AT
437dit(bf(--modify-window)) When comparing two timestamps rsync treats
438the timestamps as being equal if they are within the value of
439modify_window. This is normally zero, but you may find it useful to
440set this to a larger value in some situations. In particular, when
38843171
DD
441transferring to Windows FAT filesystems which cannot represent times
442with a 1 second resolution --modify-window=1 is useful.
5b56cc19 443
41059f75
AT
444dit(bf(-c, --checksum)) This forces the sender to checksum all files using
445a 128-bit MD4 checksum before transfer. The checksum is then
446explicitly checked on the receiver and any files of the same name
447which already exist and have the same checksum and size on the
a03a9f4e 448receiver are not transferred. This option can be quite slow.
41059f75 449
e7bf3e5e
MP
450dit(bf(-a, --archive)) This is equivalent to -rlptgoD. It is a quick
451way of saying you want recursion and want to preserve almost
452everything.
453
454Note however that bf(-a) bf(does not preserve hardlinks), because
455finding multiply-linked files is expensive. You must separately
456specify bf(-H).
41059f75 457
24986abd
AT
458dit(bf(-r, --recursive)) This tells rsync to copy directories
459recursively. If you don't specify this then rsync won't copy
460directories at all.
41059f75
AT
461
462dit(bf(-R, --relative)) Use relative paths. This means that the full path
463names specified on the command line are sent to the server rather than
464just the last parts of the filenames. This is particularly useful when
14d43f1f
DD
465you want to send several different directories at the same time. For
466example, if you used the command
41059f75
AT
467
468verb(rsync foo/bar/foo.c remote:/tmp/)
469
470then this would create a file called foo.c in /tmp/ on the remote
471machine. If instead you used
472
473verb(rsync -R foo/bar/foo.c remote:/tmp/)
474
475then a file called /tmp/foo/bar/foo.c would be created on the remote
f177b7cc
WD
476machine -- the full path name is preserved.
477
478dit(bf(--no-relative)) Turn off the --relative option. This is only
479needed if you want to use --files-from without its implied --relative
480file processing.
481
482dit(bf(--no-implied-dirs)) When combined with the --relative option, the
483implied directories in each path are not explicitly duplicated as part
484of the transfer. This makes the transfer more optimal and also allows
485the two sides to have non-matching symlinks in the implied part of the
486path. For instance, if you transfer the file "/path/foo/file" with -R,
487the default is for rsync to ensure that "/path" and "/path/foo" on the
488destination exactly match the directories/symlinks of the source. Using
489the --no-implied-dirs option would omit both of these implied dirs,
490which means that if "/path" was a real directory on one machine and a
491symlink of the other machine, rsync would not try to change this.
41059f75 492
b19fd07c
WD
493dit(bf(-b, --backup)) With this option, preexisting destination files are
494renamed as each file is transferred or deleted. You can control where the
495backup file goes and what (if any) suffix gets appended using the
496--backup-dir and --suffix options.
41059f75 497
66203a98
AT
498dit(bf(--backup-dir=DIR)) In combination with the --backup option, this
499tells rsync to store all backups in the specified directory. This is
759ac870
DD
500very useful for incremental backups. You can additionally
501specify a backup suffix using the --suffix option
502(otherwise the files backed up in the specified directory
503will keep their original filenames).
0b79c324
WD
504If DIR is a relative path, it is relative to the destination directory
505(which changes in a recursive transfer).
66203a98 506
b5679335 507dit(bf(--suffix=SUFFIX)) This option allows you to override the default
b19fd07c
WD
508backup suffix used with the --backup (-b) option. The default suffix is a ~
509if no --backup-dir was specified, otherwise it is an empty string.
9ef53907 510
41059f75
AT
511dit(bf(-u, --update)) This forces rsync to skip any files for which the
512destination file already exists and has a date later than the source
513file.
514
adddd075
WD
515In the currently implementation, a difference of file format is always
516considered to be important enough for an update, no matter what date
517is on the objects. In other words, if the source has a directory or a
518symlink where the destination has a file, the transfer would occur
519regardless of the timestamps. This might change in the future (feel
520free to comment on this on the mailing list if you have an opinion).
521
716e73d4
WD
522dit(bf(-K, --keep-dirlinks)) On the receiving side, if a symlink is
523pointing to a directory, it will be treated as matching a directory
524from the sender.
525
a3221d2a
WD
526dit(bf(--inplace)) This causes rsync not to create a new copy of the file
527and then move it into place. Instead rsync will overwrite the existing
98f51bfb 528file, meaning that the rsync algorithm can't extract the full amount of
183150b7
WD
529network reduction it might otherwise (since it does not yet try to sort
530data matches -- a future version may improve this).
a3221d2a 531
183150b7
WD
532This option is useful for transfer of large files with block-based changes
533or appended data, and also on systems that are disk bound, not network
534bound.
535
536The option implies --partial (since an interrupted transfer does not delete
537the file), but conflicts with --partial-dir, --compare-dest, and
538--link-dest (a future rsync version will hopefully update the protocol to
539remove these restrictions).
a3221d2a 540
399371e7 541WARNING: The file's data will be in an inconsistent state during the
98f51bfb 542transfer (and possibly afterward if the transfer gets interrupted), so you
399371e7 543should not use this option to update files that are in use. Also note that
75b243a5
WD
544rsync will be unable to update a file inplace that is not writable by the
545receiving user.
a3221d2a 546
eb06fa95
MP
547dit(bf(-l, --links)) When symlinks are encountered, recreate the
548symlink on the destination.
41059f75 549
eb06fa95 550dit(bf(-L, --copy-links)) When symlinks are encountered, the file that
ef855d19
WD
551they point to (the referent) is copied, rather than the symlink. In older
552versions of rsync, this option also had the side-effect of telling the
553receiving side to follow symlinks, such as symlinks to directories. In a
554modern rsync such as this one, you'll need to specify --keep-dirlinks (-K)
555to get this extra behavior. The only exception is when sending files to
556an rsync that is too old to understand -K -- in that case, the -L option
557will still have the side-effect of -K on that older receiving rsync.
b5313607 558
eb06fa95 559dit(bf(--copy-unsafe-links)) This tells rsync to copy the referent of
7af4227a 560symbolic links that point outside the copied tree. Absolute symlinks
eb06fa95
MP
561are also treated like ordinary files, and so are any symlinks in the
562source path itself when --relative is used.
41059f75 563
d310a212 564dit(bf(--safe-links)) This tells rsync to ignore any symbolic links
7af4227a 565which point outside the copied tree. All absolute symlinks are
d310a212 566also ignored. Using this option in conjunction with --relative may
14d43f1f 567give unexpected results.
d310a212 568
41059f75
AT
569dit(bf(-H, --hard-links)) This tells rsync to recreate hard links on
570the remote system to be the same as the local system. Without this
571option hard links are treated like regular files.
572
573Note that rsync can only detect hard links if both parts of the link
574are in the list of files being sent.
575
576This option can be quite slow, so only use it if you need it.
577
578dit(bf(-W, --whole-file)) With this option the incremental rsync algorithm
a1a440c2
DD
579is not used and the whole file is sent as-is instead. The transfer may be
580faster if this option is used when the bandwidth between the source and
6eb770bb 581destination machines is higher than the bandwidth to disk (especially when the
4d888108 582"disk" is actually a networked filesystem). This is the default when both
6eb770bb 583the source and destination are specified as local paths.
41059f75 584
93689aa5
DD
585dit(bf(--no-whole-file)) Turn off --whole-file, for use when it is the
586default.
587
8dc74608
WD
588dit(bf(-p, --perms)) This option causes rsync to set the destination
589permissions to be the same as the source permissions.
590
591Without this option, each new file gets its permissions set based on the
592source file's permissions and the umask at the receiving end, while all
593other files (including updated files) retain their existing permissions
594(which is the same behavior as other file-copy utilities, such as cp).
41059f75 595
eb06fa95
MP
596dit(bf(-o, --owner)) This option causes rsync to set the owner of the
597destination file to be the same as the source file. On most systems,
a2b0471f
WD
598only the super-user can set file ownership. By default, the preservation
599is done by name, but may fall back to using the ID number in some
600circumstances. See the --numeric-ids option for a full discussion.
41059f75 601
eb06fa95
MP
602dit(bf(-g, --group)) This option causes rsync to set the group of the
603destination file to be the same as the source file. If the receiving
604program is not running as the super-user, only groups that the
a2b0471f
WD
605receiver is a member of will be preserved. By default, the preservation
606is done by name, but may fall back to using the ID number in some
607circumstances. See the --numeric-ids option for a full discussion.
41059f75
AT
608
609dit(bf(-D, --devices)) This option causes rsync to transfer character and
610block device information to the remote system to recreate these
611devices. This option is only available to the super-user.
612
613dit(bf(-t, --times)) This tells rsync to transfer modification times along
baf3e504
DD
614with the files and update them on the remote system. Note that if this
615option is not used, the optimization that excludes files that have not been
616modified cannot be effective; in other words, a missing -t or -a will
d0bc3520
WD
617cause the next transfer to behave as if it used -I, causing all files to be
618updated (though the rsync algorithm will make the update fairly efficient
619if the files haven't actually changed, you're much better off using -t).
41059f75
AT
620
621dit(bf(-n, --dry-run)) This tells rsync to not do any file transfers,
622instead it will just report the actions it would have taken.
623
624dit(bf(-S, --sparse)) Try to handle sparse files efficiently so they take
625up less space on the destination.
626
d310a212
AT
627NOTE: Don't use this option when the destination is a Solaris "tmpfs"
628filesystem. It doesn't seem to handle seeks over null regions
629correctly and ends up corrupting the files.
630
41059f75
AT
631dit(bf(-x, --one-file-system)) This tells rsync not to cross filesystem
632boundaries when recursing. This is useful for transferring the
633contents of only one filesystem.
634
1347d512
AT
635dit(bf(--existing)) This tells rsync not to create any new files -
636only update files that already exist on the destination.
637
3d6feada
MP
638dit(bf(--ignore-existing))
639This tells rsync not to update files that already exist on
640the destination.
641
0b73ca12
AT
642dit(bf(--max-delete=NUM)) This tells rsync not to delete more than NUM
643files or directories. This is useful when mirroring very large trees
644to prevent disasters.
645
3610c458
WD
646dit(bf(--max-size=SIZE)) This tells rsync to avoid transferring any
647file that is larger than the specified SIZE. The SIZE value can be
648suffixed with a letter to indicate a size multiplier (K, M, or G) and
649may be a fractional value (e.g. "--max-size=1.5m").
650
41059f75 651dit(bf(--delete)) This tells rsync to delete any files on the receiving
b33b791e
DD
652side that aren't on the sending side. Files that are excluded from
653transfer are excluded from being deleted unless you use --delete-excluded.
41059f75 654
24986abd
AT
655This option has no effect if directory recursion is not selected.
656
b33b791e
DD
657This option can be dangerous if used incorrectly! It is a very good idea
658to run first using the dry run option (-n) to see what files would be
659deleted to make sure important files aren't listed.
41059f75 660
b5accaba 661If the sending side detects any I/O errors then the deletion of any
3e578a19
AT
662files at the destination will be automatically disabled. This is to
663prevent temporary filesystem failures (such as NFS errors) on the
664sending side causing a massive deletion of files on the
2c5548d2 665destination. You can override this with the --ignore-errors option.
41059f75 666
b33b791e
DD
667dit(bf(--delete-excluded)) In addition to deleting the files on the
668receiving side that are not on the sending side, this tells rsync to also
669delete any files on the receiving side that are excluded (see --exclude).
786c3687 670Implies --delete.
b33b791e 671
d48c8065
WD
672dit(bf(--delete-after)) By default rsync does file deletions on the
673receiving side before transferring files to try to ensure that there is
674sufficient space on the receiving filesystem. If you want to delete
675after transferring, use the --delete-after switch. Implies --delete.
57df171b 676
2c5548d2 677dit(bf(--ignore-errors)) Tells --delete to go ahead and delete files
b5accaba 678even when there are I/O errors.
2c5548d2 679
b695d088
DD
680dit(bf(--force)) This options tells rsync to delete directories even if
681they are not empty when they are to be replaced by non-directories. This
682is only relevant without --delete because deletions are now done depth-first.
683Requires the --recursive option (which is implied by -a) to have any effect.
41059f75 684
3ed8eb3f
WD
685dit(bf(-B, --block-size=BLOCKSIZE)) This forces the block size used in
686the rsync algorithm to a fixed value. It is normally selected based on
687the size of each file being updated. See the technical report for details.
41059f75 688
b5679335 689dit(bf(-e, --rsh=COMMAND)) This option allows you to choose an alternative
41059f75 690remote shell program to use for communication between the local and
43cd760f
WD
691remote copies of rsync. Typically, rsync is configured to use ssh by
692default, but you may prefer to use rsh on a local network.
41059f75 693
bef49340 694If this option is used with bf([user@]host::module/path), then the
4d888108 695remote shell em(COMMAND) will be used to run an rsync server on the
bef49340
WD
696remote host, and all data will be transmitted through that remote
697shell connection, rather than through a direct socket connection to a
2d4ca358
DD
698running rsync server on the remote host. See the section "CONNECTING
699TO AN RSYNC SERVER OVER A REMOTE SHELL PROGRAM" above.
bef49340 700
ea7f8108
WD
701Command-line arguments are permitted in COMMAND provided that COMMAND is
702presented to rsync as a single argument. For example:
98393ae2 703
ea7f8108 704quote(-e "ssh -p 2234")
98393ae2
WD
705
706(Note that ssh users can alternately customize site-specific connect
707options in their .ssh/config file.)
708
41059f75 709You can also choose the remote shell program using the RSYNC_RSH
ea7f8108 710environment variable, which accepts the same range of values as -e.
41059f75 711
735a816e
DD
712See also the --blocking-io option which is affected by this option.
713
b5679335 714dit(bf(--rsync-path=PATH)) Use this to specify the path to the copy of
d73ee7b7
AT
715rsync on the remote machine. Useful when it's not in your path. Note
716that this is the full path to the binary, not just the directory that
717the binary is in.
41059f75 718
f177b7cc
WD
719dit(bf(-C, --cvs-exclude)) This is a useful shorthand for excluding a
720broad range of files that you often don't want to transfer between
721systems. It uses the same algorithm that CVS uses to determine if
722a file should be ignored.
723
724The exclude list is initialized to:
725
2a383be0
WD
726quote(RCS SCCS CVS CVS.adm RCSLOG cvslog.* tags TAGS .make.state
727.nse_depinfo *~ #* .#* ,* _$* *$ *.old *.bak *.BAK *.orig *.rej
728.del-* *.a *.olb *.o *.obj *.so *.exe *.Z *.elc *.ln core .svn/)
f177b7cc
WD
729
730then files listed in a $HOME/.cvsignore are added to the list and any
2a383be0
WD
731files listed in the CVSIGNORE environment variable (all cvsignore names
732are delimited by whitespace).
733
f177b7cc 734Finally, any file is ignored if it is in the same directory as a
2a383be0 735.cvsignore file and matches one of the patterns listed therein.
2a383be0 736See the bf(cvs(1)) manual for more information.
f177b7cc 737
b5679335 738dit(bf(--exclude=PATTERN)) This option allows you to selectively exclude
41059f75
AT
739certain files from the list of files to be transferred. This is most
740useful in combination with a recursive transfer.
741
41059f75
AT
742You may use as many --exclude options on the command line as you like
743to build up the list of files to exclude.
744
6156e72f 745See the EXCLUDE PATTERNS section for detailed information on this option.
41059f75 746
b5679335 747dit(bf(--exclude-from=FILE)) This option is similar to the --exclude
c48b22c8
AT
748option, but instead it adds all exclude patterns listed in the file
749FILE to the exclude list. Blank lines in FILE and lines starting with
750';' or '#' are ignored.
f8a94f0d
DD
751If em(FILE) is bf(-) the list will be read from standard input.
752
b5679335 753dit(bf(--include=PATTERN)) This option tells rsync to not exclude the
43bd68e5
AT
754specified pattern of filenames. This is useful as it allows you to
755build up quite complex exclude/include rules.
756
6156e72f 757See the EXCLUDE PATTERNS section for detailed information on this option.
43bd68e5 758
b5679335 759dit(bf(--include-from=FILE)) This specifies a list of include patterns
43bd68e5 760from a file.
c769702f 761If em(FILE) is "-" the list will be read from standard input.
f8a94f0d 762
f177b7cc
WD
763dit(bf(--files-from=FILE)) Using this option allows you to specify the
764exact list of files to transfer (as read from the specified FILE or "-"
c769702f 765for standard input). It also tweaks the default behavior of rsync to make
f177b7cc
WD
766transferring just the specified files and directories easier. For
767instance, the --relative option is enabled by default when this option
768is used (use --no-relative if you want to turn that off), all
769directories specified in the list are created on the destination (rather
770than being noisily skipped without -r), and the -a (--archive) option's
771behavior does not imply -r (--recursive) -- specify it explicitly, if
772you want it.
773
774The file names that are read from the FILE are all relative to the
775source dir -- any leading slashes are removed and no ".." references are
776allowed to go higher than the source dir. For example, take this
777command:
778
779quote(rsync -a --files-from=/tmp/foo /usr remote:/backup)
780
781If /tmp/foo contains the string "bin" (or even "/bin"), the /usr/bin
782directory will be created as /backup/bin on the remote host (but the
783contents of the /usr/bin dir would not be sent unless you specified -r
784or the names were explicitly listed in /tmp/foo). Also keep in mind
785that the effect of the (enabled by default) --relative option is to
786duplicate only the path info that is read from the file -- it does not
787force the duplication of the source-spec path (/usr in this case).
788
789In addition, the --files-from file can be read from the remote host
790instead of the local host if you specify a "host:" in front of the file
791(the host must match one end of the transfer). As a short-cut, you can
792specify just a prefix of ":" to mean "use the remote end of the
793transfer". For example:
794
795quote(rsync -a --files-from=:/path/file-list src:/ /tmp/copy)
796
797This would copy all the files specified in the /path/file-list file that
798was located on the remote "src" host.
799
800dit(bf(-0, --from0)) This tells rsync that the filenames it reads from a
801file are terminated by a null ('\0') character, not a NL, CR, or CR+LF.
802This affects --exclude-from, --include-from, and --files-from.
f01b6368
WD
803It does not affect --cvs-exclude (since all names read from a .cvsignore
804file are split on whitespace).
41059f75 805
b5679335 806dit(bf(-T, --temp-dir=DIR)) This option instructs rsync to use DIR as a
375a4556 807scratch directory when creating temporary copies of the files
41059f75
AT
808transferred on the receiving side. The default behavior is to create
809the temporary files in the receiving directory.
810
3473b5b4
DD
811dit(bf(--compare-dest=DIR)) This option instructs rsync to use DIR on
812the destination machine as an additional directory to compare destination
d53d7795
DD
813files against when doing transfers if the files are missing in the
814destination directory. This is useful for doing transfers to a new
815destination while leaving existing files intact, and then doing a
3473b5b4
DD
816flash-cutover when all files have been successfully transferred (for
817example by moving directories around and removing the old directory,
d53d7795
DD
818although this skips files that haven't changed; see also --link-dest).
819This option increases the usefulness of --partial because partially
820transferred files will remain in the new temporary destination until they
821have a chance to be completed. If DIR is a relative path, it is relative
e0204f56 822to the destination directory.
375a4556 823
59c95e42
DD
824dit(bf(--link-dest=DIR)) This option behaves like bf(--compare-dest) but
825also will create hard links from em(DIR) to the destination directory for
826unchanged files. Files with changed ownership or permissions will not be
827linked.
8429aa9e
WD
828An example:
829
830verb(
831 rsync -av --link-dest=$PWD/prior_dir host:src_dir/ new_dir/
832)
59c95e42 833
e0204f56
WD
834Like bf(--compare-dest) if DIR is a relative path, it is relative to the
835destination directory.
836Note that rsync versions prior to 2.6.1 had a bug that could prevent
837--link-dest from working properly for a non-root user when -o was specified
838(or implied by -a). If the receiving rsync is not new enough, you can work
839around this bug by avoiding the -o option.
840
41059f75 841dit(bf(-z, --compress)) With this option, rsync compresses any data from
089e73f8 842the files that it sends to the destination machine. This
f39281ae 843option is useful on slow connections. The compression method used is the
41059f75
AT
844same method that gzip uses.
845
846Note this this option typically achieves better compression ratios
847that can be achieved by using a compressing remote shell, or a
848compressing transport, as it takes advantage of the implicit
849information sent for matching data blocks.
850
851dit(bf(--numeric-ids)) With this option rsync will transfer numeric group
4d888108 852and user IDs rather than using user and group names and mapping them
41059f75
AT
853at both ends.
854
4d888108 855By default rsync will use the username and groupname to determine
41059f75 856what ownership to give files. The special uid 0 and the special group
14d43f1f 8570 are never mapped via user/group names even if the --numeric-ids
41059f75
AT
858option is not specified.
859
ec40899b
WD
860If a user or group has no name on the source system or it has no match
861on the destination system, then the numeric ID
862from the source system is used instead. See also the comments on the
a2b0471f
WD
863"use chroot" setting in the rsyncd.conf manpage for information on how
864the chroot setting affects rsync's ability to look up the names of the
865users and groups and what you can do about it.
41059f75 866
b5accaba 867dit(bf(--timeout=TIMEOUT)) This option allows you to set a maximum I/O
de2fd20e
AT
868timeout in seconds. If no data is transferred for the specified time
869then rsync will exit. The default is 0, which means no timeout.
41059f75 870
b5accaba 871dit(bf(--blocking-io)) This tells rsync to use blocking I/O when launching
314a74d7
WD
872a remote shell transport. If the remote shell is either rsh or remsh,
873rsync defaults to using
b5accaba
WD
874blocking I/O, otherwise it defaults to using non-blocking I/O. (Note that
875ssh prefers non-blocking I/O.)
64c704f0 876
93689aa5
DD
877dit(bf(--no-blocking-io)) Turn off --blocking-io, for use when it is the
878default.
879
3a64ad1f 880dit(bf(--log-format=FORMAT)) This allows you to specify exactly what the
14d43f1f 881rsync client logs to stdout on a per-file basis. The log format is
3a64ad1f
DD
882specified using the same format conventions as the log format option in
883rsyncd.conf.
b6062654 884
b72f24c7
AT
885dit(bf(--stats)) This tells rsync to print a verbose set of statistics
886on the file transfer, allowing you to tell how effective the rsync
e19452a9 887algorithm is for your data.
b72f24c7 888
d9fcc198
AT
889dit(bf(--partial)) By default, rsync will delete any partially
890transferred file if the transfer is interrupted. In some circumstances
891it is more desirable to keep partially transferred files. Using the
892--partial option tells rsync to keep the partial file which should
893make a subsequent transfer of the rest of the file much faster.
894
44cad59f
WD
895dit(bf(--partial-dir=DIR)) Turns on --partial mode, but tells rsync to
896put a partially transferred file into DIR instead of writing out the
897file to the destination dir. Rsync will also use a file found in this
898dir as data to speed up the transfer (i.e. when you redo the send after
899rsync creates a partial file) and delete such a file after it has served
b90a6d9f
WD
900its purpose. Note that if --whole-file is specified (or implied) that an
901existing partial-dir file will not be used to speedup the transfer (since
902rsync is sending files without using the incremental rsync algorithm).
44cad59f
WD
903
904Rsync will create the dir if it is missing (just the last dir -- not the
905whole path). This makes it easy to use a relative path (such as
906"--partial-dir=.rsync-partial") to have rsync create the partial-directory
907in the destination file's directory (rsync will also try to remove the DIR
908if a partial file was found to exist at the start of the transfer and the
909DIR was specified as a relative path).
910
a33857da
WD
911If the partial-dir value is not an absolute path, rsync will also add an
912--exclude of this value at the end of all your existing excludes. This
913will prevent partial-dir files from being transferred and also prevent the
914untimely deletion of partial-dir items on the receiving side. An example:
915the above --partial-dir option would add an "--exclude=.rsync-partial/"
916rule at the end of any other include/exclude rules. Note that if you are
917supplying your own include/exclude rules, you may need to manually insert a
918rule for this directory exclusion somewhere higher up in the list so that
919it has a high enough priority to be effective (e.g., if your rules specify
920a trailing --exclude=* rule, the auto-added rule will be ineffective).
44cad59f 921
b4d1e854
WD
922IMPORTANT: the --partial-dir should not be writable by other users or it
923is a security risk. E.g. AVOID "/tmp".
924
925You can also set the partial-dir value the RSYNC_PARTIAL_DIR environment
926variable. Setting this in the environment does not force --partial to be
927enabled, but rather it effects where partial files go when --partial (or
928-P) is used. For instance, instead of specifying --partial-dir=.rsync-tmp
929along with --progress, you could set RSYNC_PARTIAL_DIR=.rsync-tmp in your
930environment and then just use the -P option to turn on the use of the
931.rsync-tmp dir for partial transfers. The only time the --partial option
932does not look for this environment value is when --inplace was also
933specified (since --inplace conflicts with --partial-dir).
44cad59f 934
eb86d661
AT
935dit(bf(--progress)) This option tells rsync to print information
936showing the progress of the transfer. This gives a bored user
937something to watch.
e2559dbe 938Implies --verbose without incrementing verbosity.
7b10f91d 939
68f9910d
WD
940When the file is transferring, the data looks like this:
941
942verb(
943 782448 63% 110.64kB/s 0:00:04
944)
945
946This tells you the current file size, the percentage of the transfer that
947is complete, the current calculated file-completion rate (including both
948data over the wire and data being matched locally), and the estimated time
949remaining in this transfer.
950
951After the a file is complete, it the data looks like this:
952
953verb(
954 1238099 100% 146.38kB/s 0:00:08 (5, 57.1% of 396)
955)
956
957This tells you the final file size, that it's 100% complete, the final
958transfer rate for the file, the amount of elapsed time it took to transfer
959the file, and the addition of a total-transfer summary in parentheses.
960These additional numbers tell you how many files have been updated, and
961what percent of the total number of files has been scanned.
962
183150b7
WD
963dit(bf(-P)) The -P option is equivalent to --partial --progress. Its
964purpose is to make it much easier to specify these two options for a long
965transfer that may be interrupted.
d9fcc198 966
65575e96
AT
967dit(bf(--password-file)) This option allows you to provide a password
968in a file for accessing a remote rsync server. Note that this option
bb18e755 969is only useful when accessing an rsync server using the built in
65575e96 970transport, not when using a remote shell as the transport. The file
fc7952e7
AT
971must not be world readable. It should contain just the password as a
972single line.
65575e96 973
ef5d23eb
DD
974dit(bf(--bwlimit=KBPS)) This option allows you to specify a maximum
975transfer rate in kilobytes per second. This option is most effective when
976using rsync with large files (several megabytes and up). Due to the nature
977of rsync transfers, blocks of data are sent, then if rsync determines the
978transfer was too fast, it will wait before sending the next data block. The
4d888108 979result is an average transfer rate equaling the specified limit. A value
ef5d23eb
DD
980of zero specifies no limit.
981
b9f592fb 982dit(bf(--write-batch=FILE)) Record a file that can later be applied to
98f51bfb 983another identical destination with --read-batch. See the "BATCH MODE"
b9f592fb 984section for details.
6902ed17 985
b9f592fb 986dit(bf(--read-batch=FILE)) Apply all of the changes stored in FILE, a
c769702f 987file previously generated by --write-batch.
399371e7 988If em(FILE) is "-" the batch data will be read from standard input.
c769702f 989See the "BATCH MODE" section for details.
6902ed17 990
e40a46de
WD
991dit(bf(-4, --ipv4) or bf(-6, --ipv6)) Tells rsync to prefer IPv4/IPv6
992when creating sockets. This only affects sockets that rsync has direct
993control over, such as the outgoing socket when directly contacting an
bdf278f7 994rsync daemon (see also these options in the --daemon mode section).
e40a46de 995
c8d895de
WD
996dit(bf(--checksum-seed=NUM)) Set the MD4 checksum seed to the integer
997NUM. This 4 byte checksum seed is included in each block and file
998MD4 checksum calculation. By default the checksum seed is generated
b9f592fb 999by the server and defaults to the current time(). This option
c8d895de
WD
1000is used to set a specific checksum seed, which is useful for
1001applications that want repeatable block and file checksums, or
1002in the case where the user wants a more random checksum seed.
1003Note that setting NUM to 0 causes rsync to use the default of time()
b9f592fb 1004for checksum seed.
c8d895de 1005
41059f75
AT
1006enddit()
1007
bdf278f7
WD
1008The options allowed when starting an rsync daemon are as follows:
1009
1010startdit()
1011
1012dit(bf(--daemon)) This tells rsync that it is to run as a daemon. The
1013daemon may be accessed using the bf(host::module) or
1014bf(rsync://host/module/) syntax.
1015
1016If standard input is a socket then rsync will assume that it is being
1017run via inetd, otherwise it will detach from the current terminal and
1018become a background daemon. The daemon will read the config file
1019(rsyncd.conf) on each connect made by a client and respond to
1020requests accordingly. See the rsyncd.conf(5) man page for more
1021details.
1022
1023dit(bf(--address)) By default rsync will bind to the wildcard address
1024when run as a daemon with the --daemon option or when connecting to a
1025rsync server. The --address option allows you to specify a specific IP
1026address (or hostname) to bind to. This makes virtual hosting possible
1027in conjunction with the --config option.
1028
1f69bec4
WD
1029dit(bf(--bwlimit=KBPS)) This option allows you to specify a maximum
1030transfer rate in kilobytes per second for the data the daemon sends.
1031The client can still specify a smaller --bwlimit value, but their
1032requested value will be rounded down if they try to exceed it. See the
1033client version of this option (above) for some extra details.
1034
bdf278f7
WD
1035dit(bf(--config=FILE)) This specifies an alternate config file than
1036the default. This is only relevant when --daemon is specified.
1037The default is /etc/rsyncd.conf unless the daemon is running over
1038a remote shell program and the remote user is not root; in that case
1039the default is rsyncd.conf in the current directory (typically $HOME).
1040
1041dit(bf(--no-detach)) When running as a daemon, this option instructs
1042rsync to not detach itself and become a background process. This
1043option is required when running as a service on Cygwin, and may also
1044be useful when rsync is supervised by a program such as
1045bf(daemontools) or AIX's bf(System Resource Controller).
1046bf(--no-detach) is also recommended when rsync is run under a
1047debugger. This option has no effect if rsync is run from inetd or
1048sshd.
1049
1050dit(bf(--port=PORT)) This specifies an alternate TCP port number to use
1051rather than the default port 873.
1052
1053dit(bf(-4, --ipv4) or bf(-6, --ipv6)) Tells rsync to prefer IPv4/IPv6
1054when creating the incoming sockets that the rsync daemon will use to
1055listen for connections. One of these options may be required in older
1056versions of Linux to work around an IPv6 bug in the kernel (if you see
1057an "address already in use" error when nothing else is using the port,
1058try specifying --ipv6 or --ipv4 when starting the daemon).
1059
1060dit(bf(-h, --help)) When specified after --daemon, print a short help
1061page describing the options available for starting an rsync daemon.
1062
1063enddit()
1064
43bd68e5
AT
1065manpagesection(EXCLUDE PATTERNS)
1066
1067The exclude and include patterns specified to rsync allow for flexible
14d43f1f 1068selection of which files to transfer and which files to skip.
43bd68e5 1069
be92ac6c 1070Rsync builds an ordered list of include/exclude options as specified on
98606687 1071the command line. Rsync checks each file and directory
43bd68e5 1072name against each exclude/include pattern in turn. The first matching
23489269 1073pattern is acted on. If it is an exclude pattern, then that file is
43bd68e5
AT
1074skipped. If it is an include pattern then that filename is not
1075skipped. If no matching include/exclude pattern is found then the
1076filename is not skipped.
1077
a4b6f305
WD
1078The filenames matched against the exclude/include patterns are relative
1079to the "root of the transfer". If you think of the transfer as a
1080subtree of names that are being sent from sender to receiver, the root
1081is where the tree starts to be duplicated in the destination directory.
1082This root governs where patterns that start with a / match (see below).
1083
1084Because the matching is relative to the transfer-root, changing the
20af605e 1085trailing slash on a source path or changing your use of the --relative
a4b6f305
WD
1086option affects the path you need to use in your matching (in addition to
1087changing how much of the file tree is duplicated on the destination
1088system). The following examples demonstrate this.
1089
b5ebe6d9
WD
1090Let's say that we want to match two source files, one with an absolute
1091path of "/home/me/foo/bar", and one with a path of "/home/you/bar/baz".
1092Here is how the various command choices differ for a 2-source transfer:
a4b6f305
WD
1093
1094verb(
b5ebe6d9 1095 Example cmd: rsync -a /home/me /home/you /dest
a4b6f305 1096 +/- pattern: /me/foo/bar
b5ebe6d9 1097 +/- pattern: /you/bar/baz
a4b6f305 1098 Target file: /dest/me/foo/bar
b5ebe6d9 1099 Target file: /dest/you/bar/baz
a4b6f305 1100
b5ebe6d9 1101 Example cmd: rsync -a /home/me/ /home/you/ /dest
b5ebe6d9
WD
1102 +/- pattern: /foo/bar (note missing "me")
1103 +/- pattern: /bar/baz (note missing "you")
a4b6f305 1104 Target file: /dest/foo/bar
b5ebe6d9 1105 Target file: /dest/bar/baz
a4b6f305 1106
b5ebe6d9 1107 Example cmd: rsync -a --relative /home/me/ /home/you /dest
b5ebe6d9
WD
1108 +/- pattern: /home/me/foo/bar (note full path)
1109 +/- pattern: /home/you/bar/baz (ditto)
a4b6f305 1110 Target file: /dest/home/me/foo/bar
b5ebe6d9 1111 Target file: /dest/home/you/bar/baz
be92ac6c 1112
b5ebe6d9 1113 Example cmd: cd /home; rsync -a --relative me/foo you/ /dest
b5ebe6d9
WD
1114 +/- pattern: /me/foo/bar (starts at specified path)
1115 +/- pattern: /you/bar/baz (ditto)
be92ac6c 1116 Target file: /dest/me/foo/bar
b5ebe6d9 1117 Target file: /dest/you/bar/baz
a4b6f305
WD
1118)
1119
1120The easiest way to see what name you should include/exclude is to just
1121look at the output when using --verbose and put a / in front of the name
1122(use the --dry-run option if you're not yet ready to copy any files).
d1cce1dd 1123
be92ac6c
WD
1124Note that, when using the --recursive (-r) option (which is implied by -a),
1125every subcomponent of
a4b6f305 1126every path is visited from the top down, so include/exclude patterns get
27b9a19b 1127applied recursively to each subcomponent.
20af605e
WD
1128The exclude patterns actually short-circuit the directory traversal stage
1129when rsync finds the files to send. If a pattern excludes a particular
1130parent directory, it can render a deeper include pattern ineffectual
1131because rsync did not descend through that excluded section of the
1132hierarchy.
27b9a19b
DD
1133
1134Note also that the --include and --exclude options take one pattern
2fb139c1
AT
1135each. To add multiple patterns use the --include-from and
1136--exclude-from options or multiple --include and --exclude options.
1137
14d43f1f 1138The patterns can take several forms. The rules are:
43bd68e5
AT
1139
1140itemize(
d1cce1dd 1141
43bd68e5
AT
1142 it() if the pattern starts with a / then it is matched against the
1143 start of the filename, otherwise it is matched against the end of
d1cce1dd
S
1144 the filename.
1145 This is the equivalent of a leading ^ in regular expressions.
a4b6f305
WD
1146 Thus "/foo" would match a file called "foo" at the transfer-root
1147 (see above for how this is different from the filesystem-root).
d1cce1dd 1148 On the other hand, "foo" would match any file called "foo"
27b9a19b
DD
1149 anywhere in the tree because the algorithm is applied recursively from
1150 top down; it behaves as if each path component gets a turn at being the
1151 end of the file name.
43bd68e5
AT
1152
1153 it() if the pattern ends with a / then it will only match a
a4b6f305 1154 directory, not a file, link, or device.
43bd68e5
AT
1155
1156 it() if the pattern contains a wildcard character from the set
a8b9d4ed
DD
1157 *?[ then expression matching is applied using the shell filename
1158 matching rules. Otherwise a simple string match is used.
43bd68e5 1159
8a7846f9
WD
1160 it() the double asterisk pattern "**" will match slashes while a
1161 single asterisk pattern "*" will stop at slashes.
27b9a19b 1162
38499c1a
WD
1163 it() if the pattern contains a / (not counting a trailing /) or a "**"
1164 then it is matched against the full filename, including any leading
1165 directory. If the pattern doesn't contain a / or a "**", then it is
1166 matched only against the final component of the filename. Again,
1167 remember that the algorithm is applied recursively so "full filename" can
8a7846f9 1168 actually be any portion of a path below the starting directory.
43bd68e5
AT
1169
1170 it() if the pattern starts with "+ " (a plus followed by a space)
5a554d5b 1171 then it is always considered an include pattern, even if specified as
a03a9f4e 1172 part of an exclude option. The prefix is discarded before matching.
43bd68e5
AT
1173
1174 it() if the pattern starts with "- " (a minus followed by a space)
5a554d5b 1175 then it is always considered an exclude pattern, even if specified as
a03a9f4e 1176 part of an include option. The prefix is discarded before matching.
de2fd20e
AT
1177
1178 it() if the pattern is a single exclamation mark ! then the current
eb06fa95 1179 include/exclude list is reset, removing all previously defined patterns.
43bd68e5
AT
1180)
1181
b7dc46c0
WD
1182The +/- rules are most useful in a list that was read from a file, allowing
1183you to have a single exclude list that contains both include and exclude
20af605e 1184options in the proper order.
27b9a19b 1185
20af605e
WD
1186Remember that the matching occurs at every step in the traversal of the
1187directory hierarchy, so you must be sure that all the parent directories of
1188the files you want to include are not excluded. This is particularly
1189important when using a trailing '*' rule. For instance, this won't work:
43bd68e5 1190
20af605e
WD
1191verb(
1192 + /some/path/this-file-will-not-be-found
1193 + /file-is-included
1194 - *
1195)
1196
1197This fails because the parent directory "some" is excluded by the '*' rule,
1198so rsync never visits any of the files in the "some" or "some/path"
1199directories. One solution is to ask for all directories in the hierarchy
1200to be included by using a single rule: --include='*/' (put it somewhere
f28bd833 1201before the --exclude='*' rule). Another solution is to add specific
20af605e
WD
1202include rules for all the parent dirs that need to be visited. For
1203instance, this set of rules works fine:
1204
1205verb(
1206 + /some/
1207 + /some/path/
1208 + /some/path/this-file-is-found
1209 + /file-also-included
1210 - *
1211)
1212
1213Here are some examples of exclude/include matching:
43bd68e5
AT
1214
1215itemize(
1216 it() --exclude "*.o" would exclude all filenames matching *.o
a4b6f305 1217 it() --exclude "/foo" would exclude a file called foo in the transfer-root directory
43bd68e5 1218 it() --exclude "foo/" would exclude any directory called foo
a8b9d4ed 1219 it() --exclude "/foo/*/bar" would exclude any file called bar two
a4b6f305 1220 levels below a directory called foo in the transfer-root directory
a8b9d4ed 1221 it() --exclude "/foo/**/bar" would exclude any file called bar two
a4b6f305 1222 or more levels below a directory called foo in the transfer-root directory
43bd68e5 1223 it() --include "*/" --include "*.c" --exclude "*" would include all
5d5811f7
DD
1224 directories and C source files
1225 it() --include "foo/" --include "foo/bar.c" --exclude "*" would include
1226 only foo/bar.c (the foo/ directory must be explicitly included or
1227 it would be excluded by the "*")
43bd68e5
AT
1228)
1229
6902ed17
MP
1230manpagesection(BATCH MODE)
1231
2e3c1417 1232bf(Note:) Batch mode should be considered experimental in this version
7432ccf4
WD
1233of rsync. The interface and behavior have now stabilized, though, so
1234feel free to try this out.
088aac85
DD
1235
1236Batch mode can be used to apply the same set of updates to many
1237identical systems. Suppose one has a tree which is replicated on a
1238number of hosts. Now suppose some changes have been made to this
1239source tree and those changes need to be propagated to the other
1240hosts. In order to do this using batch mode, rsync is run with the
1241write-batch option to apply the changes made to the source tree to one
1242of the destination trees. The write-batch option causes the rsync
b9f592fb
WD
1243client to store in a "batch file" all the information needed to repeat
1244this operation against other, identical destination trees.
1245
1246To apply the recorded changes to another destination tree, run rsync
1247with the read-batch option, specifying the name of the same batch
1248file, and the destination tree. Rsync updates the destination tree
1249using the information stored in the batch file.
1250
1251For convenience, one additional file is creating when the write-batch
1252option is used. This file's name is created by appending
73e01568 1253".sh" to the batch filename. The .sh file contains
b9f592fb
WD
1254a command-line suitable for updating a destination tree using that
1255batch file. It can be executed using a Bourne(-like) shell, optionally
1256passing in an alternate destination tree pathname which is then used
1257instead of the original path. This is useful when the destination tree
1258path differs from the original destination tree path.
1259
1260Generating the batch file once saves having to perform the file
1261status, checksum, and data block generation more than once when
088aac85 1262updating multiple destination trees. Multicast transport protocols can
b9f592fb
WD
1263be used to transfer the batch update files in parallel to many hosts
1264at once, instead of sending the same data to every host individually.
088aac85 1265
4602eafa 1266Examples:
088aac85
DD
1267
1268verb(
98f51bfb
WD
1269 $ rsync --write-batch=foo -a host:/source/dir/ /adest/dir/
1270 $ scp foo* remote:
1271 $ ssh remote ./foo.sh /bdest/dir/
4602eafa
WD
1272)
1273
1274verb(
98f51bfb
WD
1275 $ rsync --write-batch=foo -a /source/dir/ /adest/dir/
1276 $ ssh remote rsync --read-batch=- -a /bdest/dir/ <foo
4602eafa
WD
1277)
1278
98f51bfb
WD
1279In these examples, rsync is used to update /adest/dir/ from /source/dir/
1280and the information to repeat this operation is stored in "foo" and
1281"foo.sh". The host "remote" is then updated with the batched data going
1282into the directory /bdest/dir. The differences between the two examples
1283reveals some of the flexibility you have in how you deal with batches:
1284
1285itemize(
1286
1287 it() The first example shows that the initial copy doesn't have to be
1288 local -- you can push or pull data to/from a remote host using either the
1289 remote-shell syntax or rsync daemon syntax, as desired.
6902ed17 1290
98f51bfb
WD
1291 it() The first example uses the created "foo.sh" file to get the right
1292 rsync options when running the read-batch command on the remote host.
1293
1294 it() The second example reads the batch data via standard input so that
1295 the batch file doesn't need to be copied to the remote machine first.
1296 This example avoids the foo.sh script because it needed to use a modified
1297 --read-batch option, but you could edit the script file if you wished to
1298 make use of it (just be sure that no other option is trying to use
1299 standard input, such as the "--exclude-from=-" option).
1300
1301)
088aac85
DD
1302
1303Caveats:
1304
98f51bfb 1305The read-batch option expects the destination tree that it is updating
088aac85
DD
1306to be identical to the destination tree that was used to create the
1307batch update fileset. When a difference between the destination trees
7432ccf4
WD
1308is encountered the update might be discarded with no error (if the file
1309appears to be up-to-date already) or the file-update may be attempted
1310and then, if the file fails to verify, the update discarded with an
1311error. This means that it should be safe to re-run a read-batch operation
59d73bf3 1312if the command got interrupted. If you wish to force the batched-update to
7432ccf4 1313always be attempted regardless of the file's size and date, use the -I
59d73bf3
WD
1314option (when reading the batch).
1315If an error occurs, the destination tree will probably be in a
7432ccf4 1316partially updated state. In that case, rsync can
088aac85
DD
1317be used in its regular (non-batch) mode of operation to fix up the
1318destination tree.
1319
b9f592fb 1320The rsync version used on all destinations must be at least as new as the
59d73bf3
WD
1321one used to generate the batch file. Rsync will die with an error if the
1322protocol version in the batch file is too new for the batch-reading rsync
1323to handle.
088aac85 1324
98f51bfb 1325The --dry-run (-n) option does not work in batch mode and yields a runtime
088aac85
DD
1326error.
1327
7432ccf4
WD
1328When reading a batch file, rsync will force the value of certain options
1329to match the data in the batch file if you didn't set them to the same
1330as the batch-writing command. Other options can (and should) be changed.
1331For instance
b9f592fb
WD
1332--write-batch changes to --read-batch, --files-from is dropped, and the
1333--include/--exclude options are not needed unless --delete is specified
7432ccf4 1334without --delete-excluded.
b9f592fb 1335
98f51bfb
WD
1336The code that creates the BATCH.sh file transforms any include/exclude
1337options into a single list that is appended as a "here" document to the
1338shell script file. An advanced user can use this to modify the exclude
1339list if a change in what gets deleted by --delete is desired. A normal
1340user can ignore this detail and just use the shell script as an easy way
1341to run the appropriate --read-batch command for the batched data.
1342
59d73bf3
WD
1343The original batch mode in rsync was based on "rsync+", but the latest
1344version uses a new implementation.
6902ed17 1345
eb06fa95
MP
1346manpagesection(SYMBOLIC LINKS)
1347
f28bd833 1348Three basic behaviors are possible when rsync encounters a symbolic
eb06fa95
MP
1349link in the source directory.
1350
1351By default, symbolic links are not transferred at all. A message
1352"skipping non-regular" file is emitted for any symlinks that exist.
1353
1354If bf(--links) is specified, then symlinks are recreated with the same
1355target on the destination. Note that bf(--archive) implies
1356bf(--links).
1357
1358If bf(--copy-links) is specified, then symlinks are "collapsed" by
1359copying their referent, rather than the symlink.
1360
1361rsync also distinguishes "safe" and "unsafe" symbolic links. An
1362example where this might be used is a web site mirror that wishes
1363ensure the rsync module they copy does not include symbolic links to
1364bf(/etc/passwd) in the public section of the site. Using
1365bf(--copy-unsafe-links) will cause any links to be copied as the file
1366they point to on the destination. Using bf(--safe-links) will cause
4d888108 1367unsafe links to be omitted altogether.
eb06fa95 1368
7bd0cf5b
MP
1369Symbolic links are considered unsafe if they are absolute symlinks
1370(start with bf(/)), empty, or if they contain enough bf("..")
1371components to ascend from the directory being copied.
1372
d310a212
AT
1373manpagesection(DIAGNOSTICS)
1374
14d43f1f 1375rsync occasionally produces error messages that may seem a little
d310a212
AT
1376cryptic. The one that seems to cause the most confusion is "protocol
1377version mismatch - is your shell clean?".
1378
1379This message is usually caused by your startup scripts or remote shell
1380facility producing unwanted garbage on the stream that rsync is using
14d43f1f 1381for its transport. The way to diagnose this problem is to run your
d310a212
AT
1382remote shell like this:
1383
1384verb(
43cd760f 1385 ssh remotehost /bin/true > out.dat
d310a212
AT
1386)
1387
1388then look at out.dat. If everything is working correctly then out.dat
2cfeab21 1389should be a zero length file. If you are getting the above error from
d310a212
AT
1390rsync then you will probably find that out.dat contains some text or
1391data. Look at the contents and try to work out what is producing
14d43f1f 1392it. The most common cause is incorrectly configured shell startup
d310a212
AT
1393scripts (such as .cshrc or .profile) that contain output statements
1394for non-interactive logins.
1395
e6c64e79
MP
1396If you are having trouble debugging include and exclude patterns, then
1397try specifying the -vv option. At this level of verbosity rsync will
1398show why each individual file is included or excluded.
1399
55b64e4b
MP
1400manpagesection(EXIT VALUES)
1401
1402startdit()
a73de5f3
WD
1403dit(bf(0)) Success
1404dit(bf(1)) Syntax or usage error
1405dit(bf(2)) Protocol incompatibility
1406dit(bf(3)) Errors selecting input/output files, dirs
1407dit(bf(4)) Requested action not supported: an attempt
8212336a 1408was made to manipulate 64-bit files on a platform that cannot support
f28bd833 1409them; or an option was specified that is supported by the client and
8212336a 1410not by the server.
a73de5f3 1411dit(bf(5)) Error starting client-server protocol
b5accaba
WD
1412dit(bf(10)) Error in socket I/O
1413dit(bf(11)) Error in file I/O
a73de5f3
WD
1414dit(bf(12)) Error in rsync protocol data stream
1415dit(bf(13)) Errors with program diagnostics
1416dit(bf(14)) Error in IPC code
1417dit(bf(20)) Received SIGUSR1 or SIGINT
1418dit(bf(21)) Some error returned by waitpid()
1419dit(bf(22)) Error allocating core memory buffers
3c1e2ad9
WD
1420dit(bf(23)) Partial transfer due to error
1421dit(bf(24)) Partial transfer due to vanished source files
a73de5f3 1422dit(bf(30)) Timeout in data send/receive
55b64e4b
MP
1423enddit()
1424
de2fd20e
AT
1425manpagesection(ENVIRONMENT VARIABLES)
1426
1427startdit()
1428
1429dit(bf(CVSIGNORE)) The CVSIGNORE environment variable supplements any
1430ignore patterns in .cvsignore files. See the --cvs-exclude option for
1431more details.
1432
1433dit(bf(RSYNC_RSH)) The RSYNC_RSH environment variable allows you to
ea7f8108
WD
1434override the default shell used as the transport for rsync. Command line
1435options are permitted after the command name, just as in the -e option.
de2fd20e 1436
4c3b4b25
AT
1437dit(bf(RSYNC_PROXY)) The RSYNC_PROXY environment variable allows you to
1438redirect your rsync client to use a web proxy when connecting to a
1439rsync daemon. You should set RSYNC_PROXY to a hostname:port pair.
1440
de2fd20e 1441dit(bf(RSYNC_PASSWORD)) Setting RSYNC_PASSWORD to the required
bb18e755 1442password allows you to run authenticated rsync connections to an rsync
de2fd20e
AT
1443daemon without user intervention. Note that this does not supply a
1444password to a shell transport such as ssh.
1445
1446dit(bf(USER) or bf(LOGNAME)) The USER or LOGNAME environment variables
bb18e755 1447are used to determine the default username sent to an rsync server.
4b2f6a7c 1448If neither is set, the username defaults to "nobody".
de2fd20e 1449
14d43f1f 1450dit(bf(HOME)) The HOME environment variable is used to find the user's
de2fd20e
AT
1451default .cvsignore file.
1452
1453enddit()
1454
41059f75
AT
1455manpagefiles()
1456
30e8c8e1 1457/etc/rsyncd.conf or rsyncd.conf
41059f75
AT
1458
1459manpageseealso()
1460
1461rsyncd.conf(5)
1462
1463manpagediagnostics()
1464
1465manpagebugs()
1466
1467times are transferred as unix time_t values
1468
f28bd833 1469When transferring to FAT filesystems rsync may re-sync
38843171
DD
1470unmodified files.
1471See the comments on the --modify-window option.
1472
b5accaba 1473file permissions, devices, etc. are transferred as native numerical
41059f75
AT
1474values
1475
a87b3b2a 1476see also the comments on the --delete option
41059f75 1477
38843171
DD
1478Please report bugs! See the website at
1479url(http://rsync.samba.org/)(http://rsync.samba.org/)
41059f75
AT
1480
1481manpagesection(CREDITS)
1482
1483rsync is distributed under the GNU public license. See the file
1484COPYING for details.
1485
41059f75 1486A WEB site is available at
3cd5eb3b
MP
1487url(http://rsync.samba.org/)(http://rsync.samba.org/). The site
1488includes an FAQ-O-Matic which may cover questions unanswered by this
1489manual page.
9e3c856a
AT
1490
1491The primary ftp site for rsync is
1492url(ftp://rsync.samba.org/pub/rsync)(ftp://rsync.samba.org/pub/rsync).
41059f75
AT
1493
1494We would be delighted to hear from you if you like this program.
1495
9e3c856a
AT
1496This program uses the excellent zlib compression library written by
1497Jean-loup Gailly and Mark Adler.
41059f75
AT
1498
1499manpagesection(THANKS)
1500
1501Thanks to Richard Brent, Brendan Mackay, Bill Waite, Stephen Rothwell
7ff701e8
MP
1502and David Bell for helpful suggestions, patches and testing of rsync.
1503I've probably missed some people, my apologies if I have.
1504
ce5f2732 1505Especial thanks also to: David Dykstra, Jos Backus, Sebastian Krahmer,
98f51bfb 1506Martin Pool, Wayne Davison, J.W. Schultz.
41059f75
AT
1507
1508manpageauthor()
1509
ce5f2732
MP
1510rsync was originally written by Andrew Tridgell and Paul Mackerras.
1511Many people have later contributed to it.
3cd5eb3b 1512
a5d74a18 1513Mailing lists for support and development are available at
7ff701e8 1514url(http://lists.samba.org)(lists.samba.org)