Use the new am_starting_up value in who_am_i().
[rsync/rsync.git] / rsync.yo
... / ...
CommitLineData
1mailto(rsync-bugs@samba.org)
2manpage(rsync)(1)(22 Feb 2005)()()
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
18rsync [OPTION]... SRC [SRC]... rsync://[USER@]HOST[:PORT]/DEST
19
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
24greatly speed up file transfers when the destination file is being
25updated.
26
27The rsync remote-update protocol allows rsync to transfer just the
28differences between two sets of files across the network connection, using
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(
35 it() support for copying links, devices, owners, groups, and permissions
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
38 it() can use any transparent remote shell, including ssh or rsh
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
47There are eight different ways of using rsync. They are:
48
49itemize(
50 it() for copying local files. This is invoked when neither
51 source nor destination path contains a : separator
52 it() for copying from the local machine to a remote machine using
53 a remote shell program as the transport (such as ssh or
54 rsh). This is invoked when the destination path contains a
55 single : separator.
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 it() for copying from a remote rsync server to the local
60 machine. This is invoked when the source path contains a ::
61 separator or an rsync:// URL.
62 it() for copying from the local machine to a remote rsync
63 server. This is invoked when the destination path contains a ::
64 separator or an rsync:// URL.
65 it() for copying from a remote machine using a remote shell
66 program as the transport, using rsync server on the remote
67 machine. This is invoked when the source path contains a ::
68 separator and the bf(--rsh=COMMAND) (aka "bf(-e COMMAND)") option is
69 also provided.
70 it() for copying from the local machine to a remote machine
71 using a remote shell program as the transport, using rsync
72 server on the remote machine. This is invoked when the
73 destination path contains a :: separator and the
74 bf(--rsh=COMMAND) option is also provided.
75 it() for listing files on a remote machine. This is done the
76 same way as rsync transfers except that you leave off the
77 local destination.
78)
79
80Note that in all cases (other than listing) at least one of the source
81and destination paths must be local.
82
83manpagesection(SETUP)
84
85See the file README for installation instructions.
86
87Once installed, you can use rsync to any machine that you can access via
88a remote shell (as well as some that you can access using the rsync
89daemon-mode protocol). For remote transfers, a modern rsync uses ssh
90for its communications, but it may have been configured to use a
91different remote shell by default, such as rsh or remsh.
92
93You can also specify any remote shell you like, either by using the bf(-e)
94command line option, or by setting the RSYNC_RSH environment variable.
95
96One common substitute is to use ssh, which offers a high degree of
97security.
98
99Note that rsync must be installed on both the source and destination
100machines.
101
102manpagesection(USAGE)
103
104You use rsync in the same way you use rcp. You must specify a source
105and a destination, one of which may be remote.
106
107Perhaps the best way to explain the syntax is with some examples:
108
109quote(tt(rsync -t *.c foo:src/))
110
111This would transfer all files matching the pattern *.c from the
112current directory to the directory src on the machine foo. If any of
113the files already exist on the remote system then the rsync
114remote-update protocol is used to update the file by sending only the
115differences. See the tech report for details.
116
117quote(tt(rsync -avz foo:src/bar /data/tmp))
118
119This would recursively transfer all files from the directory src/bar on the
120machine foo into the /data/tmp/bar directory on the local machine. The
121files are transferred in "archive" mode, which ensures that symbolic
122links, devices, attributes, permissions, ownerships, etc. are preserved
123in the transfer. Additionally, compression will be used to reduce the
124size of data portions of the transfer.
125
126quote(tt(rsync -avz foo:src/bar/ /data/tmp))
127
128A trailing slash on the source changes this behavior to avoid creating an
129additional directory level at the destination. You can think of a trailing
130/ on a source as meaning "copy the contents of this directory" as opposed
131to "copy the directory by name", but in both cases the attributes of the
132containing directory are transferred to the containing directory on the
133destination. In other words, each of the following commands copies the
134files in the same way, including their setting of the attributes of
135/dest/foo:
136
137quote(
138tt(rsync -av /src/foo /dest)nl()
139tt(rsync -av /src/foo/ /dest/foo)nl()
140)
141
142You can also use rsync in local-only mode, where both the source and
143destination don't have a ':' in the name. In this case it behaves like
144an improved copy command.
145
146quote(tt(rsync somehost.mydomain.com::))
147
148This would list all the anonymous rsync modules available on the host
149somehost.mydomain.com. (See the following section for more details.)
150
151manpagesection(ADVANCED USAGE)
152
153The syntax for requesting multiple files from a remote host involves using
154quoted spaces in the SRC. Some examples:
155
156quote(tt(rsync host::'modname/dir1/file1 modname/dir2/file2' /dest))
157
158This would copy file1 and file2 into /dest from an rsync daemon. Each
159additional arg must include the same "modname/" prefix as the first one,
160and must be preceded by a single space. All other spaces are assumed
161to be a part of the filenames.
162
163quote(tt(rsync -av host:'dir1/file1 dir2/file2' /dest))
164
165This would copy file1 and file2 into /dest using a remote shell. This
166word-splitting is done by the remote shell, so if it doesn't work it means
167that the remote shell isn't configured to split its args based on
168whitespace (a very rare setting, but not unknown). If you need to transfer
169a filename that contains whitespace, you'll need to either escape the
170whitespace in a way that the remote shell will understand, or use wildcards
171in place of the spaces. Two examples of this are:
172
173quote(
174tt(rsync -av host:'file\ name\ with\ spaces' /dest)nl()
175tt(rsync -av host:file?name?with?spaces /dest)nl()
176)
177
178This latter example assumes that your shell passes through unmatched
179wildcards. If it complains about "no match", put the name in quotes.
180
181manpagesection(CONNECTING TO AN RSYNC SERVER)
182
183It is also possible to use rsync without a remote shell as the
184transport. In this case you will connect to a remote rsync server
185running on TCP port 873.
186
187You may establish the connection via a web proxy by setting the
188environment variable RSYNC_PROXY to a hostname:port pair pointing to
189your web proxy. Note that your web proxy's configuration must support
190proxy connections to port 873.
191
192Using rsync in this way is the same as using it with a remote shell except
193that:
194
195itemize(
196 it() you use a double colon :: instead of a single colon to
197 separate the hostname from the path or an rsync:// URL.
198 it() the remote server may print a message of the day when you
199 connect.
200 it() if you specify no path name on the remote server then the
201 list of accessible paths on the server will be shown.
202 it() if you specify no local destination then a listing of the
203 specified files on the remote server is provided.
204)
205
206Some paths on the remote server may require authentication. If so then
207you will receive a password prompt when you connect. You can avoid the
208password prompt by setting the environment variable RSYNC_PASSWORD to
209the password you want to use or using the bf(--password-file) option. This
210may be useful when scripting rsync.
211
212WARNING: On some systems environment variables are visible to all
213users. On those systems using bf(--password-file) is recommended.
214
215manpagesection(CONNECTING TO AN RSYNC SERVER OVER A REMOTE SHELL PROGRAM)
216
217It is sometimes useful to be able to set up file transfers using rsync
218server capabilities on the remote machine, while still using ssh or
219rsh for transport. This is especially useful when you want to connect
220to a remote machine via ssh (for encryption or to get through a
221firewall), but you still want to have access to the rsync server
222features (see RUNNING AN RSYNC SERVER OVER A REMOTE SHELL PROGRAM,
223below).
224
225From the user's perspective, using rsync in this way is the same as
226using it to connect to an rsync server, except that you must
227explicitly set the remote shell program on the command line with
228bf(--rsh=COMMAND). (Setting RSYNC_RSH in the environment will not turn on
229this functionality.)
230
231In order to distinguish between the remote-shell user and the rsync
232server user, you can use '-l user' on your remote-shell command:
233
234verb( rsync -av --rsh="ssh -l ssh-user" \
235 rsync-user@host::module[/path] local-path)
236
237The "ssh-user" will be used at the ssh level; the "rsync-user" will be
238used to check against the rsyncd.conf on the remote host.
239
240manpagesection(RUNNING AN RSYNC SERVER)
241
242An rsync server is configured using a configuration file. Please see the
243rsyncd.conf(5) man page for more information. By default the configuration
244file is called /etc/rsyncd.conf, unless rsync is running over a remote
245shell program and is not running as root; in that case, the default name
246is rsyncd.conf in the current directory on the remote computer
247(typically $HOME).
248
249manpagesection(RUNNING AN RSYNC SERVER OVER A REMOTE SHELL PROGRAM)
250
251See the rsyncd.conf(5) man page for full information on the rsync
252server configuration file.
253
254Several configuration options will not be available unless the remote
255user is root (e.g. chroot, setuid/setgid, etc.). There is no need to
256configure inetd or the services map to include the rsync server port
257if you run an rsync server only via a remote shell program.
258
259To run an rsync server out of a single-use ssh key, see this section
260in the rsyncd.conf(5) man page.
261
262manpagesection(EXAMPLES)
263
264Here are some examples of how I use rsync.
265
266To backup my wife's home directory, which consists of large MS Word
267files and mail folders, I use a cron job that runs
268
269quote(tt(rsync -Cavz . arvidsjaur:backup))
270
271each night over a PPP connection to a duplicate directory on my machine
272"arvidsjaur".
273
274To synchronize my samba source trees I use the following Makefile
275targets:
276
277verb( get:
278 rsync -avuzb --exclude '*~' samba:samba/ .
279 put:
280 rsync -Cavuzb . samba:samba/
281 sync: get put)
282
283this allows me to sync with a CVS directory at the other end of the
284connection. I then do CVS operations on the remote machine, which saves a
285lot of time as the remote CVS protocol isn't very efficient.
286
287I mirror a directory between my "old" and "new" ftp sites with the
288command:
289
290tt(rsync -az -e ssh --delete ~ftp/pub/samba nimbus:"~ftp/pub/tridge")
291
292This is launched from cron every few hours.
293
294manpagesection(OPTIONS SUMMARY)
295
296Here is a short summary of the options available in rsync. Please refer
297to the detailed description below for a complete description. verb(
298 -v, --verbose increase verbosity
299 -q, --quiet suppress non-error messages
300 -c, --checksum always checksum
301 -c, --checksum skip based on checksum, not mod-time & size
302 -a, --archive archive mode; same as -rlptgoD (no -H)
303 -r, --recursive recurse into directories
304 -R, --relative use relative path names
305 --no-relative turn off --relative
306 --no-implied-dirs don't send implied dirs with -R
307 -b, --backup make backups (see --suffix & --backup-dir)
308 --backup-dir=DIR make backups into hierarchy based in DIR
309 --suffix=SUFFIX backup suffix (default ~ w/o --backup-dir)
310 -u, --update skip files that are newer on the receiver
311 --inplace update destination files in-place
312 -d, --dirs transfer directories without recursing
313 -l, --links copy symlinks as symlinks
314 -L, --copy-links transform symlink into referent file/dir
315 --copy-unsafe-links only "unsafe" symlinks are transformed
316 --safe-links ignore symlinks that point outside the tree
317 -H, --hard-links preserve hard links
318 -K, --keep-dirlinks treat symlinked dir on receiver as dir
319 -p, --perms preserve permissions
320 -o, --owner preserve owner (root only)
321 -g, --group preserve group
322 -D, --devices preserve devices (root only)
323 -t, --times preserve times
324 -O, --omit-dir-times omit directories when preserving times
325 -S, --sparse handle sparse files efficiently
326 -n, --dry-run show what would have been transferred
327 -W, --whole-file copy files whole (without rsync algorithm)
328 --no-whole-file always use incremental rsync algorithm
329 -x, --one-file-system don't cross filesystem boundaries
330 -B, --block-size=SIZE force a fixed checksum block-size
331 -e, --rsh=COMMAND specify the remote shell to use
332 --rsync-path=PATH specify path to rsync on the remote machine
333 --existing only update files that already exist
334 --ignore-existing ignore files that already exist on receiver
335 --remove-sent-files sent files/symlinks are removed from sender
336 --del an alias for --delete-during
337 --delete delete files that don't exist on sender
338 --delete-before receiver deletes before transfer (default)
339 --delete-during receiver deletes during xfer, not before
340 --delete-after receiver deletes after transfer, not before
341 --delete-excluded also delete excluded files on receiver
342 --ignore-errors delete even if there are I/O errors
343 --force force deletion of dirs even if not empty
344 --max-delete=NUM don't delete more than NUM files
345 --max-size=SIZE don't transfer any file larger than SIZE
346 --partial keep partially transferred files
347 --partial-dir=DIR put a partially transferred file into DIR
348 --delay-updates put all updated files into place at end
349 --numeric-ids don't map uid/gid values by user/group name
350 --timeout=TIME set I/O timeout in seconds
351 -I, --ignore-times don't skip files that match size and time
352 --size-only skip files that match in size
353 --modify-window=NUM compare mod-times with reduced accuracy
354 -T, --temp-dir=DIR create temporary files in directory DIR
355 -y, --fuzzy find similar file for basis if no dest file
356 --compare-dest=DIR also compare received files relative to DIR
357 --link-dest=DIR hardlink to files in DIR when unchanged
358 -z, --compress compress file data during the transfer
359 -C, --cvs-exclude auto-ignore files in the same way CVS does
360 -f, --filter=RULE add a file-filtering RULE
361 -F same as --filter='dir-merge /.rsync-filter'
362 repeated: --filter='- .rsync-filter'
363 --exclude=PATTERN exclude files matching PATTERN
364 --exclude-from=FILE read exclude patterns from FILE
365 --include=PATTERN don't exclude files matching PATTERN
366 --include-from=FILE read include patterns from FILE
367 --files-from=FILE read list of source-file names from FILE
368 -0, --from0 all *from file lists are delimited by nulls
369 --version print version number
370 --port=PORT specify double-colon alternate port number
371 --blocking-io use blocking I/O for the remote shell
372 --no-blocking-io turn off blocking I/O when it is default
373 --stats give some file-transfer stats
374 --progress show progress during transfer
375 -P same as --partial --progress
376 -i, --itemize-changes output a change-summary for all updates
377 --log-format=FORMAT log file-transfers using specified format
378 --password-file=FILE read password from FILE
379 --list-only list the files instead of copying them
380 --bwlimit=KBPS limit I/O bandwidth; KBytes per second
381 --write-batch=FILE write a batched update to FILE
382 --read-batch=FILE read a batched update from FILE
383 --checksum-seed=NUM set block/file checksum seed (advanced)
384 -4, --ipv4 prefer IPv4
385 -6, --ipv6 prefer IPv6
386 -h, --help show this help screen)
387
388Rsync can also be run as a daemon, in which case the following options are
389accepted: verb(
390 --daemon run as an rsync daemon
391 --address=ADDRESS bind to the specified address
392 --bwlimit=KBPS limit I/O bandwidth; KBytes per second
393 --config=FILE specify alternate rsyncd.conf file
394 --no-detach do not detach from the parent
395 --port=PORT listen on alternate port number
396 -v, --verbose increase verbosity
397 -4, --ipv4 prefer IPv4
398 -6, --ipv6 prefer IPv6
399 -h, --help show this help screen)
400
401manpageoptions()
402
403rsync uses the GNU long options package. Many of the command line
404options have two variants, one short and one long. These are shown
405below, separated by commas. Some options only have a long variant.
406The '=' for options that take a parameter is optional; whitespace
407can be used instead.
408
409startdit()
410dit(bf(-h, --help)) Print a short help page describing the options
411available in rsync.
412
413dit(bf(--version)) print the rsync version number and exit.
414
415dit(bf(-v, --verbose)) This option increases the amount of information you
416are given during the transfer. By default, rsync works silently. A
417single bf(-v) will give you information about what files are being
418transferred and a brief summary at the end. Two bf(-v) flags will give you
419information on what files are being skipped and slightly more
420information at the end. More than two bf(-v) flags should only be used if
421you are debugging rsync.
422
423Note that the names of the transferred files that are output are done using
424a default bf(--log-format) of "%n%L", which tells you just the name of the
425file and, if the item is a symlink, where it points. At the single bf(-v)
426level of verbosity, this does not mention when a file gets its attributes
427changed. If you ask for an itemized list of changed attributes (either
428bf(--itemize-changes) or adding "%i" to the bf(--log-format) setting), the
429output (on the client) increases to mention all items that are changed in
430any way. See the bf(--log-format) option for more details.
431
432dit(bf(-q, --quiet)) This option decreases the amount of information you
433are given during the transfer, notably suppressing information messages
434from the remote server. This flag is useful when invoking rsync from
435cron.
436
437dit(bf(-I, --ignore-times)) Normally rsync will skip any files that are
438already the same size and have the same modification time-stamp.
439This option turns off this "quick check" behavior.
440
441dit(bf(--size-only)) Normally rsync will not transfer any files that are
442already the same size and have the same modification time-stamp. With the
443bf(--size-only) option, files will not be transferred if they have the same size,
444regardless of timestamp. This is useful when starting to use rsync
445after using another mirroring system which may not preserve timestamps
446exactly.
447
448dit(bf(--modify-window)) When comparing two timestamps, rsync treats the
449timestamps as being equal if they differ by no more than the modify-window
450value. This is normally 0 (for an exact match), but you may find it useful
451to set this to a larger value in some situations. In particular, when
452transferring to or from an MS Windows FAT filesystem (which represents
453times with a 2-second resolution), bf(--modify-window=1) is useful
454(allowing times to differ by up to 1 second).
455
456dit(bf(-c, --checksum)) This forces the sender to checksum all files using
457a 128-bit MD4 checksum before transfer. The checksum is then
458explicitly checked on the receiver and any files of the same name
459which already exist and have the same checksum and size on the
460receiver are not transferred. This option can be quite slow.
461
462dit(bf(-a, --archive)) This is equivalent to bf(-rlptgoD). It is a quick
463way of saying you want recursion and want to preserve almost
464everything. The only exception to this is if bf(--files-from) was
465specified, in which case bf(-r) is not implied.
466
467Note that bf(-a) bf(does not preserve hardlinks), because
468finding multiply-linked files is expensive. You must separately
469specify bf(-H).
470
471dit(bf(-r, --recursive)) This tells rsync to copy directories
472recursively. See also bf(--dirs) (bf(-d)).
473
474dit(bf(-R, --relative)) Use relative paths. This means that the full path
475names specified on the command line are sent to the server rather than
476just the last parts of the filenames. This is particularly useful when
477you want to send several different directories at the same time. For
478example, if you used the command
479
480quote(tt( rsync /foo/bar/foo.c remote:/tmp/))
481
482then this would create a file called foo.c in /tmp/ on the remote
483machine. If instead you used
484
485quote(tt( rsync -R /foo/bar/foo.c remote:/tmp/))
486
487then a file called /tmp/foo/bar/foo.c would be created on the remote
488machine -- the full path name is preserved. To limit the amount of
489path information that is sent, do something like this:
490
491quote(
492tt( cd /foo)nl()
493tt( rsync -R bar/foo.c remote:/tmp/)nl()
494)
495
496That would create /tmp/bar/foo.c on the remote machine.
497
498dit(bf(--no-relative)) Turn off the bf(--relative) option. This is only
499needed if you want to use bf(--files-from) without its implied bf(--relative)
500file processing.
501
502dit(bf(--no-implied-dirs)) When combined with the bf(--relative) option, the
503implied directories in each path are not explicitly duplicated as part
504of the transfer. This makes the transfer more optimal and also allows
505the two sides to have non-matching symlinks in the implied part of the
506path. For instance, if you transfer the file "/path/foo/file" with bf(-R),
507the default is for rsync to ensure that "/path" and "/path/foo" on the
508destination exactly match the directories/symlinks of the source. Using
509the bf(--no-implied-dirs) option would omit both of these implied dirs,
510which means that if "/path" was a real directory on one machine and a
511symlink of the other machine, rsync would not try to change this.
512
513dit(bf(-b, --backup)) With this option, preexisting destination files are
514renamed as each file is transferred or deleted. You can control where the
515backup file goes and what (if any) suffix gets appended using the
516bf(--backup-dir) and bf(--suffix) options.
517
518dit(bf(--backup-dir=DIR)) In combination with the bf(--backup) option, this
519tells rsync to store all backups in the specified directory. This is
520very useful for incremental backups. You can additionally
521specify a backup suffix using the bf(--suffix) option
522(otherwise the files backed up in the specified directory
523will keep their original filenames).
524If DIR is a relative path, it is relative to the destination directory
525(which changes in a recursive transfer).
526
527dit(bf(--suffix=SUFFIX)) This option allows you to override the default
528backup suffix used with the bf(--backup) (bf(-b)) option. The default suffix is a ~
529if no -bf(-backup-dir) was specified, otherwise it is an empty string.
530
531dit(bf(-u, --update)) This forces rsync to skip any files which exist on
532the destination and have a modified time that is newer than the source
533file. (If an existing destination file has a modify time equal to the
534source file's, it will be updated if the sizes are different.)
535
536In the current implementation of bf(--update), a difference of file format
537between the sender and receiver is always
538considered to be important enough for an update, no matter what date
539is on the objects. In other words, if the source has a directory or a
540symlink where the destination has a file, the transfer would occur
541regardless of the timestamps. This might change in the future (feel
542free to comment on this on the mailing list if you have an opinion).
543
544dit(bf(--inplace)) This causes rsync not to create a new copy of the file
545and then move it into place. Instead rsync will overwrite the existing
546file, meaning that the rsync algorithm can't accomplish the full amount of
547network reduction it might be able to otherwise (since it does not yet try
548to sort data matches). One exception to this is if you combine the option
549with bf(--backup), since rsync is smart enough to use the backup file as the
550basis file for the transfer.
551
552This option is useful for transfer of large files with block-based changes
553or appended data, and also on systems that are disk bound, not network
554bound.
555
556The option implies bf(--partial) (since an interrupted transfer does not delete
557the file), but conflicts with bf(--partial-dir) and bf(--delay-updates).
558Prior to rsync 2.6.4 bf(--inplace) was also incompatible with bf(--compare-dest)
559and bf(--link-dest).
560
561WARNING: The file's data will be in an inconsistent state during the
562transfer (and possibly afterward if the transfer gets interrupted), so you
563should not use this option to update files that are in use. Also note that
564rsync will be unable to update a file in-place that is not writable by the
565receiving user.
566
567dit(bf(-d, --dirs)) Tell the sending side to include any directories that
568are encountered. Unlike bf(--recursive), a directory's contents are not copied
569unless the directory was specified on the command-line as either "." or a
570name with a trailing slash (e.g. "foo/"). Without this option or the
571bf(--recursive) option, rsync will skip all directories it encounters (and
572output a message to that effect for each one).
573
574dit(bf(-l, --links)) When symlinks are encountered, recreate the
575symlink on the destination.
576
577dit(bf(-L, --copy-links)) When symlinks are encountered, the file that
578they point to (the referent) is copied, rather than the symlink. In older
579versions of rsync, this option also had the side-effect of telling the
580receiving side to follow symlinks, such as symlinks to directories. In a
581modern rsync such as this one, you'll need to specify bf(--keep-dirlinks) (bf(-K))
582to get this extra behavior. The only exception is when sending files to
583an rsync that is too old to understand bf(-K) -- in that case, the bf(-L) option
584will still have the side-effect of bf(-K) on that older receiving rsync.
585
586dit(bf(--copy-unsafe-links)) This tells rsync to copy the referent of
587symbolic links that point outside the copied tree. Absolute symlinks
588are also treated like ordinary files, and so are any symlinks in the
589source path itself when bf(--relative) is used.
590
591dit(bf(--safe-links)) This tells rsync to ignore any symbolic links
592which point outside the copied tree. All absolute symlinks are
593also ignored. Using this option in conjunction with bf(--relative) may
594give unexpected results.
595
596dit(bf(-H, --hard-links)) This tells rsync to recreate hard links on
597the remote system to be the same as the local system. Without this
598option hard links are treated like regular files.
599
600Note that rsync can only detect hard links if both parts of the link
601are in the list of files being sent.
602
603This option can be quite slow, so only use it if you need it.
604
605dit(bf(-K, --keep-dirlinks)) On the receiving side, if a symlink is
606pointing to a directory, it will be treated as matching a directory
607from the sender.
608
609dit(bf(-W, --whole-file)) With this option the incremental rsync algorithm
610is not used and the whole file is sent as-is instead. The transfer may be
611faster if this option is used when the bandwidth between the source and
612destination machines is higher than the bandwidth to disk (especially when the
613"disk" is actually a networked filesystem). This is the default when both
614the source and destination are specified as local paths.
615
616dit(bf(--no-whole-file)) Turn off bf(--whole-file), for use when it is the
617default.
618
619dit(bf(-p, --perms)) This option causes rsync to set the destination
620permissions to be the same as the source permissions.
621
622Without this option, each new file gets its permissions set based on the
623source file's permissions and the umask at the receiving end, while all
624other files (including updated files) retain their existing permissions
625(which is the same behavior as other file-copy utilities, such as cp).
626
627dit(bf(-o, --owner)) This option causes rsync to set the owner of the
628destination file to be the same as the source file. On most systems,
629only the super-user can set file ownership. By default, the preservation
630is done by name, but may fall back to using the ID number in some
631circumstances. See the bf(--numeric-ids) option for a full discussion.
632
633dit(bf(-g, --group)) This option causes rsync to set the group of the
634destination file to be the same as the source file. If the receiving
635program is not running as the super-user, only groups that the
636receiver is a member of will be preserved. By default, the preservation
637is done by name, but may fall back to using the ID number in some
638circumstances. See the bf(--numeric-ids) option for a full discussion.
639
640dit(bf(-D, --devices)) This option causes rsync to transfer character and
641block device information to the remote system to recreate these
642devices. This option is only available to the super-user.
643
644dit(bf(-t, --times)) This tells rsync to transfer modification times along
645with the files and update them on the remote system. Note that if this
646option is not used, the optimization that excludes files that have not been
647modified cannot be effective; in other words, a missing bf(-t) or bf(-a) will
648cause the next transfer to behave as if it used bf(-I), causing all files to be
649updated (though the rsync algorithm will make the update fairly efficient
650if the files haven't actually changed, you're much better off using bf(-t)).
651
652dit(bf(-O, --omit-dir-times)) This tells rsync to omit directories when
653it is preserving modification times (see bf(--times)). If NFS is sharing
654the directories on the receiving side, it is a good idea to use bf(-O).
655
656dit(bf(-n, --dry-run)) This tells rsync to not do any file transfers,
657instead it will just report the actions it would have taken.
658
659dit(bf(-S, --sparse)) Try to handle sparse files efficiently so they take
660up less space on the destination.
661
662NOTE: Don't use this option when the destination is a Solaris "tmpfs"
663filesystem. It doesn't seem to handle seeks over null regions
664correctly and ends up corrupting the files.
665
666dit(bf(-x, --one-file-system)) This tells rsync not to cross filesystem
667boundaries when recursing. This is useful for transferring the
668contents of only one filesystem.
669
670dit(bf(--existing)) This tells rsync not to create any new files --
671only update files that already exist on the destination.
672
673dit(bf(--ignore-existing))
674This tells rsync not to update files that already exist on
675the destination.
676
677dit(bf(--remove-sent-files)) This tells rsync to remove from the sending
678side the files and/or symlinks that are newly created or whose content is
679updated on the receiving side. Directories and devices are not removed,
680nor are files/symlinks whose attributes are merely changed.
681
682dit(bf(--delete)) This tells rsync to delete extraneous files from the
683receiving side (ones that aren't on the sending side), but only for the
684directories that are being synchronized. You must have asked rsync to
685send the whole directory (e.g. "dir" or "dir/") without using a wildcard
686for the directory's contents (e.g. "dir/*") since the wildcard is expanded
687by the shell and rsync thus gets a request to transfer individual files, not
688the files' parent directory. Files that are excluded from transfer are
689also excluded from being deleted unless you use the bf(--delete-excluded)
690option or mark the rules as only matching on the sending side (see the
691include/exclude modifiers in the FILTER RULES section).
692
693This option has no effect unless directory recursion is enabled.
694
695This option can be dangerous if used incorrectly! It is a very good idea
696to run first using the bf(--dry-run) option (bf(-n)) to see what files would be
697deleted to make sure important files aren't listed.
698
699If the sending side detects any I/O errors, then the deletion of any
700files at the destination will be automatically disabled. This is to
701prevent temporary filesystem failures (such as NFS errors) on the
702sending side causing a massive deletion of files on the
703destination. You can override this with the bf(--ignore-errors) option.
704
705The bf(--delete) option may be combined with one of the --delete-WHEN options
706without conflict, as well as bf(--delete-excluded). However, if none of the
707--delete-WHEN options are specified, rsync will currently choose the
708bf(--delete-before) algorithm. A future version may change this to choose the
709bf(--delete-during) algorithm. See also bf(--delete-after).
710
711dit(bf(--delete-before)) Request that the file-deletions on the receiving
712side be done before the transfer starts. This is the default if bf(--delete)
713or bf(--delete-excluded) is specified without one of the --delete-WHEN options.
714See bf(--delete) (which is implied) for more details on file-deletion.
715
716Deleting before the transfer is helpful if the filesystem is tight for space
717and removing extraneous files would help to make the transfer possible.
718However, it does introduce a delay before the start of the transfer,
719and this delay might cause the transfer to timeout (if bf(--timeout) was
720specified).
721
722dit(bf(--delete-during, --del)) Request that the file-deletions on the
723receiving side be done incrementally as the transfer happens. This is
724a faster method than choosing the before- or after-transfer algorithm,
725but it is only supported beginning with rsync version 2.6.4.
726See bf(--delete) (which is implied) for more details on file-deletion.
727
728dit(bf(--delete-after)) Request that the file-deletions on the receiving
729side be done after the transfer has completed. This is useful if you
730are sending new per-directory merge files as a part of the transfer and
731you want their exclusions to take effect for the delete phase of the
732current transfer.
733See bf(--delete) (which is implied) for more details on file-deletion.
734
735dit(bf(--delete-excluded)) In addition to deleting the files on the
736receiving side that are not on the sending side, this tells rsync to also
737delete any files on the receiving side that are excluded (see bf(--exclude)).
738See the FILTER RULES section for a way to make individual exclusions behave
739this way on the receiver, and for a way to protect files from
740bf(--delete-excluded).
741See bf(--delete) (which is implied) for more details on file-deletion.
742
743dit(bf(--ignore-errors)) Tells bf(--delete) to go ahead and delete files
744even when there are I/O errors.
745
746dit(bf(--force)) This options tells rsync to delete directories even if
747they are not empty when they are to be replaced by non-directories. This
748is only relevant without bf(--delete) because deletions are now done depth-first.
749Requires the bf(--recursive) option (which is implied by bf(-a)) to have any effect.
750
751dit(bf(--max-delete=NUM)) This tells rsync not to delete more than NUM
752files or directories. This is useful when mirroring very large trees
753to prevent disasters.
754
755dit(bf(--max-size=SIZE)) This tells rsync to avoid transferring any
756file that is larger than the specified SIZE. The SIZE value can be
757suffixed with a letter to indicate a size multiplier (K, M, or G) and
758may be a fractional value (e.g. "bf(--max-size=1.5m)").
759
760dit(bf(-B, --block-size=BLOCKSIZE)) This forces the block size used in
761the rsync algorithm to a fixed value. It is normally selected based on
762the size of each file being updated. See the technical report for details.
763
764dit(bf(-e, --rsh=COMMAND)) This option allows you to choose an alternative
765remote shell program to use for communication between the local and
766remote copies of rsync. Typically, rsync is configured to use ssh by
767default, but you may prefer to use rsh on a local network.
768
769If this option is used with bf([user@]host::module/path), then the
770remote shell em(COMMAND) will be used to run an rsync server on the
771remote host, and all data will be transmitted through that remote
772shell connection, rather than through a direct socket connection to a
773running rsync server on the remote host. See the section "CONNECTING
774TO AN RSYNC SERVER OVER A REMOTE SHELL PROGRAM" above.
775
776Command-line arguments are permitted in COMMAND provided that COMMAND is
777presented to rsync as a single argument. For example:
778
779quote(tt( -e "ssh -p 2234"))
780
781(Note that ssh users can alternately customize site-specific connect
782options in their .ssh/config file.)
783
784You can also choose the remote shell program using the RSYNC_RSH
785environment variable, which accepts the same range of values as bf(-e).
786
787See also the bf(--blocking-io) option which is affected by this option.
788
789dit(bf(--rsync-path=PATH)) Use this to specify the path to the copy of
790rsync on the remote machine. Useful when it's not in your path. Note
791that this is the full path to the binary, not just the directory that
792the binary is in.
793
794dit(bf(-C, --cvs-exclude)) This is a useful shorthand for excluding a
795broad range of files that you often don't want to transfer between
796systems. It uses the same algorithm that CVS uses to determine if
797a file should be ignored.
798
799The exclude list is initialized to:
800
801quote(quote(tt(RCS SCCS CVS CVS.adm RCSLOG cvslog.* tags TAGS .make.state
802.nse_depinfo *~ #* .#* ,* _$* *$ *.old *.bak *.BAK *.orig *.rej
803.del-* *.a *.olb *.o *.obj *.so *.exe *.Z *.elc *.ln core .svn/)))
804
805then files listed in a $HOME/.cvsignore are added to the list and any
806files listed in the CVSIGNORE environment variable (all cvsignore names
807are delimited by whitespace).
808
809Finally, any file is ignored if it is in the same directory as a
810.cvsignore file and matches one of the patterns listed therein. Unlike
811rsync's filter/exclude files, these patterns are split on whitespace.
812See the bf(cvs(1)) manual for more information.
813
814If you're combining bf(-C) with your own bf(--filter) rules, you should
815note that these CVS excludes are appended at the end of your own rules,
816regardless of where the -C was placed on the command-line. This makes them
817a lower priority than any rules you specified explicitly. If you want to
818control where these CVS excludes get inserted into your filter rules, you
819should omit the bf(-C) as a command-line option and use a combination of
820bf(--filter=:C) and bf(--filter=-C) (either on your command-line or by
821putting the ":C" and "-C" rules into a filter file with your other rules).
822The first option turns on the per-directory scanning for the .cvsignore
823file. The second option does a one-time import of the CVS excludes
824mentioned above.
825
826dit(bf(-f, --filter=RULE)) This option allows you to add rules to selectively
827exclude certain files from the list of files to be transferred. This is
828most useful in combination with a recursive transfer.
829
830You may use as many bf(--filter) options on the command line as you like
831to build up the list of files to exclude.
832
833See the FILTER RULES section for detailed information on this option.
834
835dit(bf(-F)) The bf(-F) option is a shorthand for adding two bf(--filter) rules to
836your command. The first time it is used is a shorthand for this rule:
837
838quote(tt( --filter=': /.rsync-filter'))
839
840This tells rsync to look for per-directory .rsync-filter files that have
841been sprinkled through the hierarchy and use their rules to filter the
842files in the transfer. If bf(-F) is repeated, it is a shorthand for this
843rule:
844
845quote(tt( --filter='- .rsync-filter'))
846
847This filters out the .rsync-filter files themselves from the transfer.
848
849See the FILTER RULES section for detailed information on how these options
850work.
851
852dit(bf(--exclude=PATTERN)) This option is a simplified form of the
853bf(--filter) option that defaults to an exclude rule and does not allow
854the full rule-parsing syntax of normal filter rules.
855
856See the FILTER RULES section for detailed information on this option.
857
858dit(bf(--exclude-from=FILE)) This option is similar to the bf(--exclude)
859option, but instead it adds all exclude patterns listed in the file
860FILE to the exclude list. Blank lines in FILE and lines starting with
861';' or '#' are ignored.
862If em(FILE) is bf(-) the list will be read from standard input.
863
864dit(bf(--include=PATTERN)) This option is a simplified form of the
865bf(--filter) option that defaults to an include rule and does not allow
866the full rule-parsing syntax of normal filter rules.
867
868See the FILTER RULES section for detailed information on this option.
869
870dit(bf(--include-from=FILE)) This specifies a list of include patterns
871from a file.
872If em(FILE) is "-" the list will be read from standard input.
873
874dit(bf(--files-from=FILE)) Using this option allows you to specify the
875exact list of files to transfer (as read from the specified FILE or "-"
876for standard input). It also tweaks the default behavior of rsync to make
877transferring just the specified files and directories easier:
878
879quote(itemize(
880 it() The bf(--relative) (bf(-R)) option is implied, which preserves the path
881 information that is specified for each item in the file (use
882 bf(--no-relative) if you want to turn that off).
883 it() The bf(--dirs) (bf(-d)) option is implied, which will create directories
884 specified in the list on the destination rather than noisily skipping
885 them.
886 it() The bf(--archive) (bf(-a)) option's behavior does not imply bf(--recursive)
887 (bf(-r)), so specify it explicitly, if you want it.
888))
889
890The file names that are read from the FILE are all relative to the
891source dir -- any leading slashes are removed and no ".." references are
892allowed to go higher than the source dir. For example, take this
893command:
894
895quote(tt( rsync -a --files-from=/tmp/foo /usr remote:/backup))
896
897If /tmp/foo contains the string "bin" (or even "/bin"), the /usr/bin
898directory will be created as /backup/bin on the remote host (but the
899contents of the /usr/bin dir would not be sent unless you specified bf(-r)
900or the names were explicitly listed in /tmp/foo). Also keep in mind
901that the effect of the (enabled by default) bf(--relative) option is to
902duplicate only the path info that is read from the file -- it does not
903force the duplication of the source-spec path (/usr in this case).
904
905In addition, the bf(--files-from) file can be read from the remote host
906instead of the local host if you specify a "host:" in front of the file
907(the host must match one end of the transfer). As a short-cut, you can
908specify just a prefix of ":" to mean "use the remote end of the
909transfer". For example:
910
911quote(tt( rsync -a --files-from=:/path/file-list src:/ /tmp/copy))
912
913This would copy all the files specified in the /path/file-list file that
914was located on the remote "src" host.
915
916dit(bf(-0, --from0)) This tells rsync that the filenames it reads from a
917file are terminated by a null ('\0') character, not a NL, CR, or CR+LF.
918This affects bf(--exclude-from), bf(--include-from), bf(--files-from), and any
919merged files specified in a bf(--filter) rule.
920It does not affect bf(--cvs-exclude) (since all names read from a .cvsignore
921file are split on whitespace).
922
923dit(bf(-T, --temp-dir=DIR)) This option instructs rsync to use DIR as a
924scratch directory when creating temporary copies of the files
925transferred on the receiving side. The default behavior is to create
926the temporary files in the receiving directory.
927
928dit(bf(-y, --fuzzy)) This option tells rsync that it should look for a
929basis file for any destination file that is missing. The current algorithm
930looks in the same directory as the destination file for either a file that
931has an identical size and modified-time, or a similarly-named file. If
932found, rsync uses the fuzzy basis file to try to speed up the transfer.
933
934Note that the use of the bf(--delete) option might get rid of any potential
935fuzzy-match files, so either use bf(--delete-after) or specify some
936filename exclusions if you need to prevent this.
937
938dit(bf(--compare-dest=DIR)) This option instructs rsync to use em(DIR) on
939the destination machine as an additional hierarchy to compare destination
940files against doing transfers (if the files are missing in the destination
941directory). If a file is found in em(DIR) that is identical to the
942sender's file, the file will NOT be transferred to the destination
943directory. This is useful for creating a sparse backup of just files that
944have changed from an earlier backup.
945
946Beginning in version 2.6.4, multiple bf(--compare-dest) directories may be
947provided and rsync will search the list in the order specified until it
948finds an existing file. That first discovery is used as the basis file,
949and also determines if the transfer needs to happen.
950
951If em(DIR) is a relative path, it is relative to the destination directory.
952See also bf(--link-dest).
953
954dit(bf(--link-dest=DIR)) This option behaves like bf(--compare-dest), but
955unchanged files are hard linked from em(DIR) to the destination directory.
956The files must be identical in all preserved attributes (e.g. permissions,
957possibly ownership) in order for the files to be linked together.
958An example:
959
960quote(tt( rsync -av --link-dest=$PWD/prior_dir host:src_dir/ new_dir/))
961
962Beginning with version 2.6.4, if more than one bf(--link-dest) option is
963specified, rsync will try to find an exact match to link with (searching
964the list in the order specified), and if not found, a basis file from one
965of the em(DIR)s will be selected to try to speed up the transfer.
966
967If em(DIR) is a relative path, it is relative to the destination directory.
968See also bf(--compare-dest).
969
970Note that rsync versions prior to 2.6.1 had a bug that could prevent
971bf(--link-dest) from working properly for a non-root user when bf(-o) was specified
972(or implied by bf(-a)). You can work-around this bug by avoiding the bf(-o) option
973when sending to an old rsync.
974
975dit(bf(-z, --compress)) With this option, rsync compresses the file data
976as it is sent to the destination machine, which reduces the amount of data
977being transmitted -- something that is useful over a slow connection.
978
979Note this this option typically achieves better compression ratios that can
980be achieved by using a compressing remote shell or a compressing transport
981because it takes advantage of the implicit information in the matching data
982blocks that are not explicitly sent over the connection.
983
984dit(bf(--numeric-ids)) With this option rsync will transfer numeric group
985and user IDs rather than using user and group names and mapping them
986at both ends.
987
988By default rsync will use the username and groupname to determine
989what ownership to give files. The special uid 0 and the special group
9900 are never mapped via user/group names even if the bf(--numeric-ids)
991option is not specified.
992
993If a user or group has no name on the source system or it has no match
994on the destination system, then the numeric ID
995from the source system is used instead. See also the comments on the
996"use chroot" setting in the rsyncd.conf manpage for information on how
997the chroot setting affects rsync's ability to look up the names of the
998users and groups and what you can do about it.
999
1000dit(bf(--timeout=TIMEOUT)) This option allows you to set a maximum I/O
1001timeout in seconds. If no data is transferred for the specified time
1002then rsync will exit. The default is 0, which means no timeout.
1003
1004dit(bf(--port=PORT)) This specifies an alternate TCP port number to use
1005rather than the default of 873. This is only needed if you are using the
1006double-colon (::) syntax to connect with an rsync daemon (since the URL
1007syntax has a way to specify the port as a part of the URL). See also this
1008option in the bf(--daemon) mode section.
1009
1010dit(bf(--blocking-io)) This tells rsync to use blocking I/O when launching
1011a remote shell transport. If the remote shell is either rsh or remsh,
1012rsync defaults to using
1013blocking I/O, otherwise it defaults to using non-blocking I/O. (Note that
1014ssh prefers non-blocking I/O.)
1015
1016dit(bf(--no-blocking-io)) Turn off bf(--blocking-io), for use when it is the
1017default.
1018
1019dit(bf(-i, --itemize-changes)) Requests a simple itemized list of the
1020changes that are being made to each file, including attribute changes.
1021This is equivalent to specifying bf(--log-format='%i %n%L'). (See the
1022description of what the output of '%i' means in the rsyncd.conf manpage.)
1023Rsync also mentions the delete action when an item replaces an item of a
1024different type (e.g. a directory replaces a file of the same name).
1025
1026dit(bf(--log-format=FORMAT)) This allows you to specify exactly what the
1027rsync client logs to stdout on a per-file basis. This format can be used
1028without bf(--verbose) to enable just the outputting of the file-transfer
1029information, or it can be used to change how the names are output when
1030bf(--verbose) is enabled. Rsync will log the name of an item prior to its
1031transfer unless one of the transferred-byte-count values is requested, in
1032which case the logging is done at the end of the item's transfer. In this
1033late-transfer state, if bf(--progress) is also specified, rsync will output
1034just the name of the file prior to the progress information.
1035
1036The log format is specified using the same format conventions as the
1037"log format" option in rsyncd.conf, so see that manpage for details.
1038(Note that this option does not affect what a daemon logs to its logfile.)
1039
1040dit(bf(--stats)) This tells rsync to print a verbose set of statistics
1041on the file transfer, allowing you to tell how effective the rsync
1042algorithm is for your data.
1043
1044dit(bf(--partial)) By default, rsync will delete any partially
1045transferred file if the transfer is interrupted. In some circumstances
1046it is more desirable to keep partially transferred files. Using the
1047bf(--partial) option tells rsync to keep the partial file which should
1048make a subsequent transfer of the rest of the file much faster.
1049
1050dit(bf(--partial-dir=DIR)) A better way to keep partial files than the
1051bf(--partial) option is to specify a em(DIR) that will be used to hold the
1052partial data (instead of writing it out to the destination file).
1053On the next transfer, rsync will use a file found in this
1054dir as data to speed up the resumption of the transfer and then deletes it
1055after it has served its purpose.
1056Note that if bf(--whole-file) is specified (or implied), any partial-dir
1057file that is found for a file that is being updated will simply be removed
1058(since
1059rsync is sending files without using the incremental rsync algorithm).
1060
1061Rsync will create the em(DIR) if it is missing (just the last dir -- not
1062the whole path). This makes it easy to use a relative path (such as
1063"bf(--partial-dir=.rsync-partial)") to have rsync create the
1064partial-directory in the destination file's directory when needed, and then
1065remove it again when the partial file is deleted.
1066
1067If the partial-dir value is not an absolute path, rsync will also add a directory
1068bf(--exclude) of this value at the end of all your existing excludes. This
1069will prevent partial-dir files from being transferred and also prevent the
1070untimely deletion of partial-dir items on the receiving side. An example:
1071the above bf(--partial-dir) option would add an "bf(--exclude=.rsync-partial/)"
1072rule at the end of any other filter rules. Note that if you are
1073supplying your own filter rules, you may need to manually insert a
1074rule for this directory exclusion somewhere higher up in the list so that
1075it has a high enough priority to be effective (e.g., if your rules specify
1076a trailing bf(--exclude='*') rule, the auto-added rule would never be
1077reached).
1078
1079IMPORTANT: the bf(--partial-dir) should not be writable by other users or it
1080is a security risk. E.g. AVOID "/tmp".
1081
1082You can also set the partial-dir value the RSYNC_PARTIAL_DIR environment
1083variable. Setting this in the environment does not force bf(--partial) to be
1084enabled, but rather it effects where partial files go when bf(--partial) is
1085specified. For instance, instead of using bf(--partial-dir=.rsync-tmp)
1086along with bf(--progress), you could set RSYNC_PARTIAL_DIR=.rsync-tmp in your
1087environment and then just use the bf(-P) option to turn on the use of the
1088.rsync-tmp dir for partial transfers. The only time that the bf(--partial)
1089option does not look for this environment value is (1) when bf(--inplace) was
1090specified (since bf(--inplace) conflicts with bf(--partial-dir)), or (2) when
1091bf(--delay-updates) was specified (see below).
1092
1093For the purposes of the server-config's "refuse options" setting,
1094bf(--partial-dir) does em(not) imply bf(--partial). This is so that a
1095refusal of the bf(--partial) option can be used to disallow the overwriting
1096of destination files with a partial transfer, while still allowing the
1097safer idiom provided by bf(--partial-dir).
1098
1099dit(bf(--delay-updates)) This option puts the temporary file from each
1100updated file into a holding directory until the end of the
1101transfer, at which time all the files are renamed into place in rapid
1102succession. This attempts to make the updating of the files a little more
1103atomic. By default the files are placed into a directory named ".~tmp~" in
1104each file's destination directory, but you can override this by specifying
1105the bf(--partial-dir) option. (Note that RSYNC_PARTIAL_DIR has no effect
1106on this value, nor is bf(--partial-dir) considered to be implied for the
1107purposes of the server-config's "refuse options" setting.)
1108Conflicts with bf(--inplace).
1109
1110This option uses more memory on the receiving side (one bit per file
1111transferred) and also requires enough free disk space on the receiving
1112side to hold an additional copy of all the updated files. Note also that
1113you should not use an absolute path to bf(--partial-dir) unless there is no
1114chance of any of the files in the transfer having the same name (since all
1115the updated files will be put into a single directory if the path is
1116absolute).
1117
1118See also the "atomic-rsync" perl script in the "support" subdir for an
1119update algorithm that is even more atomic (it uses bf(--link-dest) and a
1120parallel hierarchy of files).
1121
1122dit(bf(--progress)) This option tells rsync to print information
1123showing the progress of the transfer. This gives a bored user
1124something to watch.
1125Implies bf(--verbose) if it wasn't already specified.
1126
1127When the file is transferring, the data looks like this:
1128
1129verb( 782448 63% 110.64kB/s 0:00:04)
1130
1131This tells you the current file size, the percentage of the transfer that
1132is complete, the current calculated file-completion rate (including both
1133data over the wire and data being matched locally), and the estimated time
1134remaining in this transfer.
1135
1136After a file is complete, the data looks like this:
1137
1138verb( 1238099 100% 146.38kB/s 0:00:08 (5, 57.1% of 396))
1139
1140This tells you the final file size, that it's 100% complete, the final
1141transfer rate for the file, the amount of elapsed time it took to transfer
1142the file, and the addition of a total-transfer summary in parentheses.
1143These additional numbers tell you how many files have been updated, and
1144what percent of the total number of files has been scanned.
1145
1146dit(bf(-P)) The bf(-P) option is equivalent to bf(--partial) bf(--progress). Its
1147purpose is to make it much easier to specify these two options for a long
1148transfer that may be interrupted.
1149
1150dit(bf(--password-file)) This option allows you to provide a password
1151in a file for accessing a remote rsync server. Note that this option
1152is only useful when accessing an rsync server using the built in
1153transport, not when using a remote shell as the transport. The file
1154must not be world readable. It should contain just the password as a
1155single line.
1156
1157dit(bf(--list-only)) This option will cause the source files to be listed
1158instead of transferred. This option is inferred if there is no destination
1159specified, so you don't usually need to use it explicitly. However, it can
1160come in handy for a power user that wants to avoid the "bf(-r --exclude='/*/*')"
1161options that rsync might use as a compatibility kluge when generating a
1162non-recursive listing.
1163
1164dit(bf(--bwlimit=KBPS)) This option allows you to specify a maximum
1165transfer rate in kilobytes per second. This option is most effective when
1166using rsync with large files (several megabytes and up). Due to the nature
1167of rsync transfers, blocks of data are sent, then if rsync determines the
1168transfer was too fast, it will wait before sending the next data block. The
1169result is an average transfer rate equaling the specified limit. A value
1170of zero specifies no limit.
1171
1172dit(bf(--write-batch=FILE)) Record a file that can later be applied to
1173another identical destination with bf(--read-batch). See the "BATCH MODE"
1174section for details.
1175
1176dit(bf(--read-batch=FILE)) Apply all of the changes stored in FILE, a
1177file previously generated by bf(--write-batch).
1178If em(FILE) is "-" the batch data will be read from standard input.
1179See the "BATCH MODE" section for details.
1180
1181dit(bf(-4, --ipv4) or bf(-6, --ipv6)) Tells rsync to prefer IPv4/IPv6
1182when creating sockets. This only affects sockets that rsync has direct
1183control over, such as the outgoing socket when directly contacting an
1184rsync daemon. See also these options in the bf(--daemon) mode section.
1185
1186dit(bf(--checksum-seed=NUM)) Set the MD4 checksum seed to the integer
1187NUM. This 4 byte checksum seed is included in each block and file
1188MD4 checksum calculation. By default the checksum seed is generated
1189by the server and defaults to the current time(). This option
1190is used to set a specific checksum seed, which is useful for
1191applications that want repeatable block and file checksums, or
1192in the case where the user wants a more random checksum seed.
1193Note that setting NUM to 0 causes rsync to use the default of time()
1194for checksum seed.
1195enddit()
1196
1197manpagesection(DAEMON OPTIONS)
1198
1199The options allowed when starting an rsync daemon are as follows:
1200
1201startdit()
1202dit(bf(--daemon)) This tells rsync that it is to run as a daemon. The
1203daemon may be accessed using the bf(host::module) or
1204bf(rsync://host/module/) syntax.
1205
1206If standard input is a socket then rsync will assume that it is being
1207run via inetd, otherwise it will detach from the current terminal and
1208become a background daemon. The daemon will read the config file
1209(rsyncd.conf) on each connect made by a client and respond to
1210requests accordingly. See the rsyncd.conf(5) man page for more
1211details.
1212
1213dit(bf(--address)) By default rsync will bind to the wildcard address
1214when run as a daemon with the bf(--daemon) option or when connecting to a
1215rsync server. The bf(--address) option allows you to specify a specific IP
1216address (or hostname) to bind to. This makes virtual hosting possible
1217in conjunction with the bf(--config) option. See also the "address" global
1218option in the rsyncd.conf manpage.
1219
1220dit(bf(--bwlimit=KBPS)) This option allows you to specify a maximum
1221transfer rate in kilobytes per second for the data the daemon sends.
1222The client can still specify a smaller bf(--bwlimit) value, but their
1223requested value will be rounded down if they try to exceed it. See the
1224client version of this option (above) for some extra details.
1225
1226dit(bf(--config=FILE)) This specifies an alternate config file than
1227the default. This is only relevant when bf(--daemon) is specified.
1228The default is /etc/rsyncd.conf unless the daemon is running over
1229a remote shell program and the remote user is not root; in that case
1230the default is rsyncd.conf in the current directory (typically $HOME).
1231
1232dit(bf(--no-detach)) When running as a daemon, this option instructs
1233rsync to not detach itself and become a background process. This
1234option is required when running as a service on Cygwin, and may also
1235be useful when rsync is supervised by a program such as
1236bf(daemontools) or AIX's bf(System Resource Controller).
1237bf(--no-detach) is also recommended when rsync is run under a
1238debugger. This option has no effect if rsync is run from inetd or
1239sshd.
1240
1241dit(bf(--port=PORT)) This specifies an alternate TCP port number for the
1242daemon to listen on rather than the default of 873. See also the "port"
1243global option in the rsyncd.conf manpage.
1244
1245dit(bf(-v, --verbose)) This option increases the amount of information the
1246daemon logs during its startup phase. After the client connects, the
1247daemon's verbosity level will be controlled by the options that the client
1248used and the "max verbosity" setting in the module's config section.
1249
1250dit(bf(-4, --ipv4) or bf(-6, --ipv6)) Tells rsync to prefer IPv4/IPv6
1251when creating the incoming sockets that the rsync daemon will use to
1252listen for connections. One of these options may be required in older
1253versions of Linux to work around an IPv6 bug in the kernel (if you see
1254an "address already in use" error when nothing else is using the port,
1255try specifying bf(--ipv6) or bf(--ipv4) when starting the daemon).
1256
1257dit(bf(-h, --help)) When specified after bf(--daemon), print a short help
1258page describing the options available for starting an rsync daemon.
1259enddit()
1260
1261manpagesection(FILTER RULES)
1262
1263The filter rules allow for flexible selection of which files to transfer
1264(include) and which files to skip (exclude). The rules either directly
1265specify include/exclude patterns or they specify a way to acquire more
1266include/exclude patterns (e.g. to read them from a file).
1267
1268As the list of files/directories to transfer is built, rsync checks each
1269name to be transferred against the list of include/exclude patterns in
1270turn, and the first matching pattern is acted on: if it is an exclude
1271pattern, then that file is skipped; if it is an include pattern then that
1272filename is not skipped; if no matching pattern is found, then the
1273filename is not skipped.
1274
1275Rsync builds an ordered list of filter rules as specified on the
1276command-line. Filter rules have the following syntax:
1277
1278quote(
1279tt(RULE [PATTERN_OR_FILENAME])nl()
1280tt(RULE,MODIFIERS [PATTERN_OR_FILENAME])nl()
1281)
1282
1283You have your choice of using either short or long RULE names, as described
1284below. If you use a short-named rule, the ',' separating the RULE from the
1285MODIFIERS is optional. The PATTERN or FILENAME that follows (when present)
1286must come after either a single space or an underscore (_).
1287Here are the available rule prefixes:
1288
1289quote(
1290bf(exclude, -) specifies an exclude pattern. nl()
1291bf(include, +) specifies an include pattern. nl()
1292bf(merge, .) specifies a merge-file to read for more rules. nl()
1293bf(dir-merge, :) specifies a per-directory merge-file. nl()
1294bf(hide, H) specifies a pattern for hiding files from the transfer. nl()
1295bf(show, S) files that match the pattern are not hidden. nl()
1296bf(protect, P) specifies a pattern for protecting files from deletion. nl()
1297bf(risk, R) files that match the pattern are not protected. nl()
1298bf(clear, !) clears the current include/exclude list (takes no arg) nl()
1299)
1300
1301When rules are being read from a file, empty lines are ignored, as are
1302comment lines that start with a "#".
1303
1304Note that the bf(--include)/bf(--exclude) command-line options do not allow the
1305full range of rule parsing as described above -- they only allow the
1306specification of include/exclude patterns plus a "!" token to clear the
1307list (and the normal comment parsing when rules are read from a file).
1308If a pattern
1309does not begin with "- " (dash, space) or "+ " (plus, space), then the
1310rule will be interpreted as if "+ " (for an include option) or "- " (for
1311an exclude option) were prefixed to the string. A bf(--filter) option, on
1312the other hand, must always contain either a short or long rule name at the
1313start of the rule.
1314
1315Note also that the bf(--filter), bf(--include), and bf(--exclude) options take one
1316rule/pattern each. To add multiple ones, you can repeat the options on
1317the command-line, use the merge-file syntax of the bf(--filter) option, or
1318the bf(--include-from)/bf(--exclude-from) options.
1319
1320manpagesection(INCLUDE/EXCLUDE PATTERN RULES)
1321
1322You can include and exclude files by specifying patterns using the "+",
1323"-", etc. filter rules (as introduced in the FILTER RULES section above).
1324The include/exclude rules each specify a pattern that is matched against
1325the names of the files that are going to be transferred. These patterns
1326can take several forms:
1327
1328itemize(
1329 it() if the pattern starts with a / then it is anchored to a
1330 particular spot in the hierarchy of files, otherwise it is matched
1331 against the end of the pathname. This is similar to a leading ^ in
1332 regular expressions.
1333 Thus "/foo" would match a file called "foo" at either the "root of the
1334 transfer" (for a global rule) or in the merge-file's directory (for a
1335 per-directory rule).
1336 An unqualified "foo" would match any file or directory named "foo"
1337 anywhere in the tree because the algorithm is applied recursively from
1338 the
1339 top down; it behaves as if each path component gets a turn at being the
1340 end of the file name. Even the unanchored "sub/foo" would match at
1341 any point in the hierarchy where a "foo" was found within a directory
1342 named "sub". See the section on ANCHORING INCLUDE/EXCLUDE PATTERNS for
1343 a full discussion of how to specify a pattern that matches at the root
1344 of the transfer.
1345 it() if the pattern ends with a / then it will only match a
1346 directory, not a file, link, or device.
1347 it() if the pattern contains a wildcard character from the set
1348 *?[ then expression matching is applied using the shell filename
1349 matching rules. Otherwise a simple string match is used.
1350 it() the double asterisk pattern "**" will match slashes while a
1351 single asterisk pattern "*" will stop at slashes.
1352 it() if the pattern contains a / (not counting a trailing /) or a "**"
1353 then it is matched against the full pathname, including any leading
1354 directories. If the pattern doesn't contain a / or a "**", then it is
1355 matched only against the final component of the filename.
1356 (Remember that the algorithm is applied recursively so "full filename"
1357 can actually be any portion of a path from the starting directory on
1358 down.)
1359)
1360
1361Note that, when using the bf(--recursive) (bf(-r)) option (which is implied by
1362bf(-a)), every subcomponent of every path is visited from the top down, so
1363include/exclude patterns get applied recursively to each subcomponent's
1364full name (e.g. to include "/foo/bar/baz" the subcomponents "/foo" and
1365"/foo/bar" must not be excluded).
1366The exclude patterns actually short-circuit the directory traversal stage
1367when rsync finds the files to send. If a pattern excludes a particular
1368parent directory, it can render a deeper include pattern ineffectual
1369because rsync did not descend through that excluded section of the
1370hierarchy. This is particularly important when using a trailing '*' rule.
1371For instance, this won't work:
1372
1373quote(
1374tt(+ /some/path/this-file-will-not-be-found)nl()
1375tt(+ /file-is-included)nl()
1376tt(- *)nl()
1377)
1378
1379This fails because the parent directory "some" is excluded by the '*'
1380rule, so rsync never visits any of the files in the "some" or "some/path"
1381directories. One solution is to ask for all directories in the hierarchy
1382to be included by using a single rule: "+ */" (put it somewhere before the
1383"- *" rule). Another solution is to add specific include rules for all
1384the parent dirs that need to be visited. For instance, this set of rules
1385works fine:
1386
1387quote(
1388tt(+ /some/)nl()
1389tt(+ /some/path/)nl()
1390tt(+ /some/path/this-file-is-found)nl()
1391tt(+ /file-also-included)nl()
1392tt(- *)nl()
1393)
1394
1395Here are some examples of exclude/include matching:
1396
1397itemize(
1398 it() "- *.o" would exclude all filenames matching *.o
1399 it() "- /foo" would exclude a file called foo in the transfer-root directory
1400 it() "- foo/" would exclude any directory called foo
1401 it() "- /foo/*/bar" would exclude any file called bar two
1402 levels below a directory called foo in the transfer-root directory
1403 it() "- /foo/**/bar" would exclude any file called bar two
1404 or more levels below a directory called foo in the transfer-root directory
1405 it() The combination of "+ */", "+ *.c", and "- *" would include all
1406 directories and C source files but nothing else.
1407 it() The combination of "+ foo/", "+ foo/bar.c", and "- *" would include
1408 only the foo directory and foo/bar.c (the foo directory must be
1409 explicitly included or it would be excluded by the "*")
1410)
1411
1412manpagesection(MERGE-FILE FILTER RULES)
1413
1414You can merge whole files into your filter rules by specifying either a
1415merge (.) or a dir-merge (:) filter rule (as introduced in the FILTER RULES
1416section above).
1417
1418There are two kinds of merged files -- single-instance ('.') and
1419per-directory (':'). A single-instance merge file is read one time, and
1420its rules are incorporated into the filter list in the place of the "."
1421rule. For per-directory merge files, rsync will scan every directory that
1422it traverses for the named file, merging its contents when the file exists
1423into the current list of inherited rules. These per-directory rule files
1424must be created on the sending side because it is the sending side that is
1425being scanned for the available files to transfer. These rule files may
1426also need to be transferred to the receiving side if you want them to
1427affect what files don't get deleted (see PER-DIRECTORY RULES AND DELETE
1428below).
1429
1430Some examples:
1431
1432quote(
1433tt(merge /etc/rsync/default.rules)nl()
1434tt(. /etc/rsync/default.rules)nl()
1435tt(dir-merge .per-dir-filter)nl()
1436tt(dir-merge,n- .non-inherited-per-dir-excludes)nl()
1437tt(:n- .non-inherited-per-dir-excludes)nl()
1438)
1439
1440The following modifiers are accepted after a merge or dir-merge rule:
1441
1442itemize(
1443 it() A bf(-) specifies that the file should consist of only exclude
1444 patterns, with no other rule-parsing except for in-file comments.
1445 it() A bf(+) specifies that the file should consist of only include
1446 patterns, with no other rule-parsing except for in-file comments.
1447 it() A bf(C) is a way to specify that the file should be read in a
1448 CVS-compatible manner. This turns on 'n', 'w', and '-', but also
1449 allows the list-clearing token (!) to be specified. If no filename is
1450 provided, ".cvsignore" is assumed.
1451 it() A bf(e) will exclude the merge-file name from the transfer; e.g.
1452 "dir-merge,e .rules" is like "dir-merge .rules" and "- .rules".
1453 it() An bf(n) specifies that the rules are not inherited by subdirectories.
1454 it() A bf(w) specifies that the rules are word-split on whitespace instead
1455 of the normal line-splitting. This also turns off comments. Note: the
1456 space that separates the prefix from the rule is treated specially, so
1457 "- foo + bar" is parsed as two rules (assuming that prefix-parsing wasn't
1458 also disabled).
1459 it() You may also specify any of the modifiers for the "+" or "-" rules
1460 (below) in order to have the rules that are read-in from the file
1461 default to having that modifier set. For instance, "merge,-/ .excl" would
1462 treat the contents of .excl as absolute-path excludes,
1463 while "dir-merge,s .filt" and ":sC" would each make all their
1464 per-directory rules apply only on the server side.
1465)
1466
1467The following modifiers are accepted after a "+" or "-":
1468
1469itemize(
1470 it() A "/" specifies that the include/exclude should be treated as an
1471 absolute path, relative to the root of the filesystem. For example,
1472 "-/ /etc/passwd" would exclude the passwd file any time the transfer
1473 was sending files from the "/etc" directory.
1474 it() A "!" specifies that the include/exclude should take effect if
1475 the pattern fails to match. For instance, "-! */" would exclude all
1476 non-directories.
1477 it() A bf(C) is used to indicate that all the global CVS-exclude rules
1478 should be inserted as excludes in place of the "-C". No arg should
1479 follow.
1480 it() An bf(s) is used to indicate that the rule applies to the sending
1481 side. When a rule affects the sending side, it prevents files from
1482 being transferred. The default is for a rule to affect both sides
1483 unless bf(--delete-excluded) was specified, in which case default rules
1484 become sender-side only. See also the hide (H) and show (S) rules,
1485 which are an alternate way to specify server-side includes/excludes.
1486 it() An bf(r) is used to indicate that the rule applies to the receiving
1487 side. When a rule affects the receiving side, it prevents files from
1488 being deleted. See the bf(s) modifier for more info. See also the
1489 protect (P) and risk (R) rules, which are an alternate way to
1490 specify receiver-side includes/excludes.
1491)
1492
1493Per-directory rules are inherited in all subdirectories of the directory
1494where the merge-file was found unless the 'n' modifier was used. Each
1495subdirectory's rules are prefixed to the inherited per-directory rules
1496from its parents, which gives the newest rules a higher priority than the
1497inherited rules. The entire set of dir-merge rules are grouped together in
1498the spot where the merge-file was specified, so it is possible to override
1499dir-merge rules via a rule that got specified earlier in the list of global
1500rules. When the list-clearing rule ("!") is read from a per-directory
1501file, it only clears the inherited rules for the current merge file.
1502
1503Another way to prevent a single rule from a dir-merge file from being inherited is to
1504anchor it with a leading slash. Anchored rules in a per-directory
1505merge-file are relative to the merge-file's directory, so a pattern "/foo"
1506would only match the file "foo" in the directory where the dir-merge filter
1507file was found.
1508
1509Here's an example filter file which you'd specify via bf(--filter=". file":)
1510
1511quote(
1512tt(merge /home/user/.global-filter)nl()
1513tt(- *.gz)nl()
1514tt(dir-merge .rules)nl()
1515tt(+ *.[ch])nl()
1516tt(- *.o)nl()
1517)
1518
1519This will merge the contents of the /home/user/.global-filter file at the
1520start of the list and also turns the ".rules" filename into a per-directory
1521filter file. All rules read-in prior to the start of the directory scan
1522follow the global anchoring rules (i.e. a leading slash matches at the root
1523of the transfer).
1524
1525If a per-directory merge-file is specified with a path that is a parent
1526directory of the first transfer directory, rsync will scan all the parent
1527dirs from that starting point to the transfer directory for the indicated
1528per-directory file. For instance, here is a common filter (see bf(-F)):
1529
1530quote(tt(--filter=': /.rsync-filter'))
1531
1532That rule tells rsync to scan for the file .rsync-filter in all
1533directories from the root down through the parent directory of the
1534transfer prior to the start of the normal directory scan of the file in
1535the directories that are sent as a part of the transfer. (Note: for an
1536rsync daemon, the root is always the same as the module's "path".)
1537
1538Some examples of this pre-scanning for per-directory files:
1539
1540quote(
1541tt(rsync -avF /src/path/ /dest/dir)nl()
1542tt(rsync -av --filter=': ../../.rsync-filter' /src/path/ /dest/dir)nl()
1543tt(rsync -av --filter=': .rsync-filter' /src/path/ /dest/dir)nl()
1544)
1545
1546The first two commands above will look for ".rsync-filter" in "/" and
1547"/src" before the normal scan begins looking for the file in "/src/path"
1548and its subdirectories. The last command avoids the parent-dir scan
1549and only looks for the ".rsync-filter" files in each directory that is
1550a part of the transfer.
1551
1552If you want to include the contents of a ".cvsignore" in your patterns,
1553you should use the rule ":C", which creates a dir-merge of the .cvsignore
1554file, but parsed in a CVS-compatible manner. You can
1555use this to affect where the bf(--cvs-exclude) (bf(-C)) option's inclusion of the
1556per-directory .cvsignore file gets placed into your rules by putting the
1557":C" wherever you like in your filter rules. Without this, rsync would
1558add the dir-merge rule for the .cvsignore file at the end of all your other
1559rules (giving it a lower priority than your command-line rules). For
1560example:
1561
1562quote(
1563tt(cat <<EOT | rsync -avC --filter='. -' a/ b)nl()
1564tt(+ foo.o)nl()
1565tt(:C)nl()
1566tt(- *.old)nl()
1567tt(EOT)nl()
1568tt(rsync -avC --include=foo.o -f :C --exclude='*.old' a/ b)nl()
1569)
1570
1571Both of the above rsync commands are identical. Each one will merge all
1572the per-directory .cvsignore rules in the middle of the list rather than
1573at the end. This allows their dir-specific rules to supersede the rules
1574that follow the :C instead of being subservient to all your rules. To
1575affect the other CVS exclude rules (i.e. the default list of exclusions,
1576the contents of $HOME/.cvsignore, and the value of $CVSIGNORE) you should
1577omit the bf(-C) command-line option and instead insert a "-C" rule into
1578your filter rules; e.g. "--filter=-C".
1579
1580manpagesection(LIST-CLEARING FILTER RULE)
1581
1582You can clear the current include/exclude list by using the "!" filter
1583rule (as introduced in the FILTER RULES section above). The "current"
1584list is either the global list of rules (if the rule is encountered while
1585parsing the filter options) or a set of per-directory rules (which are
1586inherited in their own sub-list, so a subdirectory can use this to clear
1587out the parent's rules).
1588
1589manpagesection(ANCHORING INCLUDE/EXCLUDE PATTERNS)
1590
1591As mentioned earlier, global include/exclude patterns are anchored at the
1592"root of the transfer" (as opposed to per-directory patterns, which are
1593anchored at the merge-file's directory). If you think of the transfer as
1594a subtree of names that are being sent from sender to receiver, the
1595transfer-root is where the tree starts to be duplicated in the destination
1596directory. This root governs where patterns that start with a / match.
1597
1598Because the matching is relative to the transfer-root, changing the
1599trailing slash on a source path or changing your use of the bf(--relative)
1600option affects the path you need to use in your matching (in addition to
1601changing how much of the file tree is duplicated on the destination
1602host). The following examples demonstrate this.
1603
1604Let's say that we want to match two source files, one with an absolute
1605path of "/home/me/foo/bar", and one with a path of "/home/you/bar/baz".
1606Here is how the various command choices differ for a 2-source transfer:
1607
1608quote(
1609 Example cmd: rsync -a /home/me /home/you /dest nl()
1610 +/- pattern: /me/foo/bar nl()
1611 +/- pattern: /you/bar/baz nl()
1612 Target file: /dest/me/foo/bar nl()
1613 Target file: /dest/you/bar/baz nl()
1614)
1615
1616quote(
1617 Example cmd: rsync -a /home/me/ /home/you/ /dest nl()
1618 +/- pattern: /foo/bar (note missing "me") nl()
1619 +/- pattern: /bar/baz (note missing "you") nl()
1620 Target file: /dest/foo/bar nl()
1621 Target file: /dest/bar/baz nl()
1622)
1623
1624quote(
1625 Example cmd: rsync -a --relative /home/me/ /home/you /dest nl()
1626 +/- pattern: /home/me/foo/bar (note full path) nl()
1627 +/- pattern: /home/you/bar/baz (ditto) nl()
1628 Target file: /dest/home/me/foo/bar nl()
1629 Target file: /dest/home/you/bar/baz nl()
1630)
1631
1632quote(
1633 Example cmd: cd /home; rsync -a --relative me/foo you/ /dest nl()
1634 +/- pattern: /me/foo/bar (starts at specified path) nl()
1635 +/- pattern: /you/bar/baz (ditto) nl()
1636 Target file: /dest/me/foo/bar nl()
1637 Target file: /dest/you/bar/baz nl()
1638)
1639
1640The easiest way to see what name you should filter is to just
1641look at the output when using bf(--verbose) and put a / in front of the name
1642(use the bf(--dry-run) option if you're not yet ready to copy any files).
1643
1644manpagesection(PER-DIRECTORY RULES AND DELETE)
1645
1646Without a delete option, per-directory rules are only relevant on the
1647sending side, so you can feel free to exclude the merge files themselves
1648without affecting the transfer. To make this easy, the 'e' modifier adds
1649this exclude for you, as seen in these two equivalent commands:
1650
1651quote(
1652tt(rsync -av --filter=': .excl' --exclude=.excl host:src/dir /dest)nl()
1653tt(rsync -av --filter=':e .excl' host:src/dir /dest)nl()
1654)
1655
1656However, if you want to do a delete on the receiving side AND you want some
1657files to be excluded from being deleted, you'll need to be sure that the
1658receiving side knows what files to exclude. The easiest way is to include
1659the per-directory merge files in the transfer and use bf(--delete-after),
1660because this ensures that the receiving side gets all the same exclude
1661rules as the sending side before it tries to delete anything:
1662
1663quote(tt(rsync -avF --delete-after host:src/dir /dest))
1664
1665However, if the merge files are not a part of the transfer, you'll need to
1666either specify some global exclude rules (i.e. specified on the command
1667line), or you'll need to maintain your own per-directory merge files on
1668the receiving side. An example of the first is this (assume that the
1669remote .rules files exclude themselves):
1670
1671verb(rsync -av --filter=': .rules' --filter='. /my/extra.rules'
1672 --delete host:src/dir /dest)
1673
1674In the above example the extra.rules file can affect both sides of the
1675transfer, but (on the sending side) the rules are subservient to the rules
1676merged from the .rules files because they were specified after the
1677per-directory merge rule.
1678
1679In one final example, the remote side is excluding the .rsync-filter
1680files from the transfer, but we want to use our own .rsync-filter files
1681to control what gets deleted on the receiving side. To do this we must
1682specifically exclude the per-directory merge files (so that they don't get
1683deleted) and then put rules into the local files to control what else
1684should not get deleted. Like one of these commands:
1685
1686verb( rsync -av --filter=':e /.rsync-filter' --delete \
1687 host:src/dir /dest
1688 rsync -avFF --delete host:src/dir /dest)
1689
1690manpagesection(BATCH MODE)
1691
1692Batch mode can be used to apply the same set of updates to many
1693identical systems. Suppose one has a tree which is replicated on a
1694number of hosts. Now suppose some changes have been made to this
1695source tree and those changes need to be propagated to the other
1696hosts. In order to do this using batch mode, rsync is run with the
1697write-batch option to apply the changes made to the source tree to one
1698of the destination trees. The write-batch option causes the rsync
1699client to store in a "batch file" all the information needed to repeat
1700this operation against other, identical destination trees.
1701
1702To apply the recorded changes to another destination tree, run rsync
1703with the read-batch option, specifying the name of the same batch
1704file, and the destination tree. Rsync updates the destination tree
1705using the information stored in the batch file.
1706
1707For convenience, one additional file is creating when the write-batch
1708option is used. This file's name is created by appending
1709".sh" to the batch filename. The .sh file contains
1710a command-line suitable for updating a destination tree using that
1711batch file. It can be executed using a Bourne(-like) shell, optionally
1712passing in an alternate destination tree pathname which is then used
1713instead of the original path. This is useful when the destination tree
1714path differs from the original destination tree path.
1715
1716Generating the batch file once saves having to perform the file
1717status, checksum, and data block generation more than once when
1718updating multiple destination trees. Multicast transport protocols can
1719be used to transfer the batch update files in parallel to many hosts
1720at once, instead of sending the same data to every host individually.
1721
1722Examples:
1723
1724quote(
1725tt($ rsync --write-batch=foo -a host:/source/dir/ /adest/dir/)nl()
1726tt($ scp foo* remote:)nl()
1727tt($ ssh remote ./foo.sh /bdest/dir/)nl()
1728)
1729
1730quote(
1731tt($ rsync --write-batch=foo -a /source/dir/ /adest/dir/)nl()
1732tt($ ssh remote rsync --read-batch=- -a /bdest/dir/ <foo)nl()
1733)
1734
1735In these examples, rsync is used to update /adest/dir/ from /source/dir/
1736and the information to repeat this operation is stored in "foo" and
1737"foo.sh". The host "remote" is then updated with the batched data going
1738into the directory /bdest/dir. The differences between the two examples
1739reveals some of the flexibility you have in how you deal with batches:
1740
1741itemize(
1742 it() The first example shows that the initial copy doesn't have to be
1743 local -- you can push or pull data to/from a remote host using either the
1744 remote-shell syntax or rsync daemon syntax, as desired.
1745 it() The first example uses the created "foo.sh" file to get the right
1746 rsync options when running the read-batch command on the remote host.
1747 it() The second example reads the batch data via standard input so that
1748 the batch file doesn't need to be copied to the remote machine first.
1749 This example avoids the foo.sh script because it needed to use a modified
1750 bf(--read-batch) option, but you could edit the script file if you wished to
1751 make use of it (just be sure that no other option is trying to use
1752 standard input, such as the "bf(--exclude-from=-)" option).
1753)
1754
1755Caveats:
1756
1757The read-batch option expects the destination tree that it is updating
1758to be identical to the destination tree that was used to create the
1759batch update fileset. When a difference between the destination trees
1760is encountered the update might be discarded with no error (if the file
1761appears to be up-to-date already) or the file-update may be attempted
1762and then, if the file fails to verify, the update discarded with an
1763error. This means that it should be safe to re-run a read-batch operation
1764if the command got interrupted. If you wish to force the batched-update to
1765always be attempted regardless of the file's size and date, use the bf(-I)
1766option (when reading the batch).
1767If an error occurs, the destination tree will probably be in a
1768partially updated state. In that case, rsync can
1769be used in its regular (non-batch) mode of operation to fix up the
1770destination tree.
1771
1772The rsync version used on all destinations must be at least as new as the
1773one used to generate the batch file. Rsync will die with an error if the
1774protocol version in the batch file is too new for the batch-reading rsync
1775to handle.
1776
1777The bf(--dry-run) (bf(-n)) option does not work in batch mode and yields a runtime
1778error.
1779
1780When reading a batch file, rsync will force the value of certain options
1781to match the data in the batch file if you didn't set them to the same
1782as the batch-writing command. Other options can (and should) be changed.
1783For instance bf(--write-batch) changes to bf(--read-batch),
1784bf(--files-from) is dropped, and the
1785bf(--filter)/bf(--include)/bf(--exclude) options are not needed unless
1786one of the bf(--delete) options is specified.
1787
1788The code that creates the BATCH.sh file transforms any filter/include/exclude
1789options into a single list that is appended as a "here" document to the
1790shell script file. An advanced user can use this to modify the exclude
1791list if a change in what gets deleted by bf(--delete) is desired. A normal
1792user can ignore this detail and just use the shell script as an easy way
1793to run the appropriate bf(--read-batch) command for the batched data.
1794
1795The original batch mode in rsync was based on "rsync+", but the latest
1796version uses a new implementation.
1797
1798manpagesection(SYMBOLIC LINKS)
1799
1800Three basic behaviors are possible when rsync encounters a symbolic
1801link in the source directory.
1802
1803By default, symbolic links are not transferred at all. A message
1804"skipping non-regular" file is emitted for any symlinks that exist.
1805
1806If bf(--links) is specified, then symlinks are recreated with the same
1807target on the destination. Note that bf(--archive) implies
1808bf(--links).
1809
1810If bf(--copy-links) is specified, then symlinks are "collapsed" by
1811copying their referent, rather than the symlink.
1812
1813rsync also distinguishes "safe" and "unsafe" symbolic links. An
1814example where this might be used is a web site mirror that wishes
1815ensure the rsync module they copy does not include symbolic links to
1816bf(/etc/passwd) in the public section of the site. Using
1817bf(--copy-unsafe-links) will cause any links to be copied as the file
1818they point to on the destination. Using bf(--safe-links) will cause
1819unsafe links to be omitted altogether.
1820
1821Symbolic links are considered unsafe if they are absolute symlinks
1822(start with bf(/)), empty, or if they contain enough bf("..")
1823components to ascend from the directory being copied.
1824
1825manpagediagnostics()
1826
1827rsync occasionally produces error messages that may seem a little
1828cryptic. The one that seems to cause the most confusion is "protocol
1829version mismatch -- is your shell clean?".
1830
1831This message is usually caused by your startup scripts or remote shell
1832facility producing unwanted garbage on the stream that rsync is using
1833for its transport. The way to diagnose this problem is to run your
1834remote shell like this:
1835
1836quote(tt(ssh remotehost /bin/true > out.dat))
1837
1838then look at out.dat. If everything is working correctly then out.dat
1839should be a zero length file. If you are getting the above error from
1840rsync then you will probably find that out.dat contains some text or
1841data. Look at the contents and try to work out what is producing
1842it. The most common cause is incorrectly configured shell startup
1843scripts (such as .cshrc or .profile) that contain output statements
1844for non-interactive logins.
1845
1846If you are having trouble debugging filter patterns, then
1847try specifying the bf(-vv) option. At this level of verbosity rsync will
1848show why each individual file is included or excluded.
1849
1850manpagesection(EXIT VALUES)
1851
1852startdit()
1853dit(bf(0)) Success
1854dit(bf(1)) Syntax or usage error
1855dit(bf(2)) Protocol incompatibility
1856dit(bf(3)) Errors selecting input/output files, dirs
1857dit(bf(4)) Requested action not supported: an attempt
1858was made to manipulate 64-bit files on a platform that cannot support
1859them; or an option was specified that is supported by the client and
1860not by the server.
1861dit(bf(5)) Error starting client-server protocol
1862dit(bf(10)) Error in socket I/O
1863dit(bf(11)) Error in file I/O
1864dit(bf(12)) Error in rsync protocol data stream
1865dit(bf(13)) Errors with program diagnostics
1866dit(bf(14)) Error in IPC code
1867dit(bf(20)) Received SIGUSR1 or SIGINT
1868dit(bf(21)) Some error returned by waitpid()
1869dit(bf(22)) Error allocating core memory buffers
1870dit(bf(23)) Partial transfer due to error
1871dit(bf(24)) Partial transfer due to vanished source files
1872dit(bf(30)) Timeout in data send/receive
1873enddit()
1874
1875manpagesection(ENVIRONMENT VARIABLES)
1876
1877startdit()
1878dit(bf(CVSIGNORE)) The CVSIGNORE environment variable supplements any
1879ignore patterns in .cvsignore files. See the bf(--cvs-exclude) option for
1880more details.
1881dit(bf(RSYNC_RSH)) The RSYNC_RSH environment variable allows you to
1882override the default shell used as the transport for rsync. Command line
1883options are permitted after the command name, just as in the bf(-e) option.
1884dit(bf(RSYNC_PROXY)) The RSYNC_PROXY environment variable allows you to
1885redirect your rsync client to use a web proxy when connecting to a
1886rsync daemon. You should set RSYNC_PROXY to a hostname:port pair.
1887dit(bf(RSYNC_PASSWORD)) Setting RSYNC_PASSWORD to the required
1888password allows you to run authenticated rsync connections to an rsync
1889daemon without user intervention. Note that this does not supply a
1890password to a shell transport such as ssh.
1891dit(bf(USER) or bf(LOGNAME)) The USER or LOGNAME environment variables
1892are used to determine the default username sent to an rsync server.
1893If neither is set, the username defaults to "nobody".
1894dit(bf(HOME)) The HOME environment variable is used to find the user's
1895default .cvsignore file.
1896enddit()
1897
1898manpagefiles()
1899
1900/etc/rsyncd.conf or rsyncd.conf
1901
1902manpageseealso()
1903
1904rsyncd.conf(5)
1905
1906manpagebugs()
1907
1908times are transferred as unix time_t values
1909
1910When transferring to FAT filesystems rsync may re-sync
1911unmodified files.
1912See the comments on the bf(--modify-window) option.
1913
1914file permissions, devices, etc. are transferred as native numerical
1915values
1916
1917see also the comments on the bf(--delete) option
1918
1919Please report bugs! See the website at
1920url(http://rsync.samba.org/)(http://rsync.samba.org/)
1921
1922manpagesection(CREDITS)
1923
1924rsync is distributed under the GNU public license. See the file
1925COPYING for details.
1926
1927A WEB site is available at
1928url(http://rsync.samba.org/)(http://rsync.samba.org/). The site
1929includes an FAQ-O-Matic which may cover questions unanswered by this
1930manual page.
1931
1932The primary ftp site for rsync is
1933url(ftp://rsync.samba.org/pub/rsync)(ftp://rsync.samba.org/pub/rsync).
1934
1935We would be delighted to hear from you if you like this program.
1936
1937This program uses the excellent zlib compression library written by
1938Jean-loup Gailly and Mark Adler.
1939
1940manpagesection(THANKS)
1941
1942Thanks to Richard Brent, Brendan Mackay, Bill Waite, Stephen Rothwell
1943and David Bell for helpful suggestions, patches and testing of rsync.
1944I've probably missed some people, my apologies if I have.
1945
1946Especial thanks also to: David Dykstra, Jos Backus, Sebastian Krahmer,
1947Martin Pool, Wayne Davison, J.W. Schultz.
1948
1949manpageauthor()
1950
1951rsync was originally written by Andrew Tridgell and Paul Mackerras.
1952Many people have later contributed to it.
1953
1954Mailing lists for support and development are available at
1955url(http://lists.samba.org)(lists.samba.org)