Annotation of embedaddon/rsync/rsync.1, revision 1.1.1.3
1.1.1.3 ! misho 1: .TH "rsync" "1" "21 Dec 2015" "" ""
1.1 misho 2: .SH "NAME"
3: rsync \- a fast, versatile, remote (and local) file\-copying tool
4: .SH "SYNOPSIS"
5:
6: .PP
7: .nf
8: Local: rsync [OPTION...] SRC... [DEST]
9:
10: Access via remote shell:
11: Pull: rsync [OPTION...] [USER@]HOST:SRC... [DEST]
12: Push: rsync [OPTION...] SRC... [USER@]HOST:DEST
13:
14: Access via rsync daemon:
15: Pull: rsync [OPTION...] [USER@]HOST::SRC... [DEST]
16: rsync [OPTION...] rsync://[USER@]HOST[:PORT]/SRC... [DEST]
17: Push: rsync [OPTION...] SRC... [USER@]HOST::DEST
18: rsync [OPTION...] SRC... rsync://[USER@]HOST[:PORT]/DEST
19: .fi
20:
21: .PP
22: Usages with just one SRC arg and no DEST arg will list the source files
23: instead of copying.
24: .PP
25: .SH "DESCRIPTION"
26:
27: .PP
28: Rsync is a fast and extraordinarily versatile file copying tool. It can
29: copy locally, to/from another host over any remote shell, or to/from a
30: remote rsync daemon. It offers a large number of options that control
31: every aspect of its behavior and permit very flexible specification of the
32: set of files to be copied. It is famous for its delta\-transfer algorithm,
33: which reduces the amount of data sent over the network by sending only the
34: differences between the source files and the existing files in the
35: destination. Rsync is widely used for backups and mirroring and as an
36: improved copy command for everyday use.
37: .PP
38: Rsync finds files that need to be transferred using a \(dq\&quick check\(dq\&
39: algorithm (by default) that looks for files that have changed in size or
40: in last\-modified time. Any changes in the other preserved attributes (as
41: requested by options) are made on the destination file directly when the
42: quick check indicates that the file\(cq\&s data does not need to be updated.
43: .PP
44: Some of the additional features of rsync are:
45: .PP
46: .IP o
47: support for copying links, devices, owners, groups, and permissions
48: .IP o
49: exclude and exclude\-from options similar to GNU tar
50: .IP o
51: a CVS exclude mode for ignoring the same files that CVS would ignore
52: .IP o
53: can use any transparent remote shell, including ssh or rsh
54: .IP o
55: does not require super\-user privileges
56: .IP o
57: pipelining of file transfers to minimize latency costs
58: .IP o
59: support for anonymous or authenticated rsync daemons (ideal for
60: mirroring)
61:
62: .PP
63: .SH "GENERAL"
64:
65: .PP
66: Rsync copies files either to or from a remote host, or locally on the
67: current host (it does not support copying files between two remote hosts).
68: .PP
69: There are two different ways for rsync to contact a remote system: using a
70: remote\-shell program as the transport (such as ssh or rsh) or contacting an
71: rsync daemon directly via TCP. The remote\-shell transport is used whenever
72: the source or destination path contains a single colon (:) separator after
73: a host specification. Contacting an rsync daemon directly happens when the
74: source or destination path contains a double colon (::) separator after a
75: host specification, OR when an rsync:// URL is specified (see also the
76: \(dq\&USING RSYNC\-DAEMON FEATURES VIA A REMOTE\-SHELL CONNECTION\(dq\& section for
77: an exception to this latter rule).
78: .PP
79: As a special case, if a single source arg is specified without a
80: destination, the files are listed in an output format similar to \(dq\&ls \-l\(dq\&.
81: .PP
82: As expected, if neither the source or destination path specify a remote
83: host, the copy occurs locally (see also the \fB\-\-list\-only\fP option).
84: .PP
85: Rsync refers to the local side as the \(dq\&client\(dq\& and the remote side as the
86: \(dq\&server\(dq\&. Don\(cq\&t confuse \(dq\&server\(dq\& with an rsync daemon \-\- a daemon is always a
87: server, but a server can be either a daemon or a remote\-shell spawned process.
88: .PP
89: .SH "SETUP"
90:
91: .PP
92: See the file README for installation instructions.
93: .PP
94: Once installed, you can use rsync to any machine that you can access via
95: a remote shell (as well as some that you can access using the rsync
96: daemon\-mode protocol). For remote transfers, a modern rsync uses ssh
97: for its communications, but it may have been configured to use a
98: different remote shell by default, such as rsh or remsh.
99: .PP
100: You can also specify any remote shell you like, either by using the \fB\-e\fP
101: command line option, or by setting the RSYNC_RSH environment variable.
102: .PP
103: Note that rsync must be installed on both the source and destination
104: machines.
105: .PP
106: .SH "USAGE"
107:
108: .PP
109: You use rsync in the same way you use rcp. You must specify a source
110: and a destination, one of which may be remote.
111: .PP
112: Perhaps the best way to explain the syntax is with some examples:
113: .PP
114: .RS
115: \f(CWrsync \-t *.c foo:src/\fP
116: .RE
117:
118: .PP
119: This would transfer all files matching the pattern *.c from the
120: current directory to the directory src on the machine foo. If any of
121: the files already exist on the remote system then the rsync
122: remote\-update protocol is used to update the file by sending only the
1.1.1.3 ! misho 123: differences in the data. Note that the expansion of wildcards on the
! 124: commandline (*.c) into a list of files is handled by the shell before
! 125: it runs rsync and not by rsync itself (exactly the same as all other
! 126: posix\-style programs).
1.1 misho 127: .PP
128: .RS
129: \f(CWrsync \-avz foo:src/bar /data/tmp\fP
130: .RE
131:
132: .PP
133: This would recursively transfer all files from the directory src/bar on the
134: machine foo into the /data/tmp/bar directory on the local machine. The
135: files are transferred in \(dq\&archive\(dq\& mode, which ensures that symbolic
136: links, devices, attributes, permissions, ownerships, etc. are preserved
137: in the transfer. Additionally, compression will be used to reduce the
138: size of data portions of the transfer.
139: .PP
140: .RS
141: \f(CWrsync \-avz foo:src/bar/ /data/tmp\fP
142: .RE
143:
144: .PP
145: A trailing slash on the source changes this behavior to avoid creating an
146: additional directory level at the destination. You can think of a trailing
147: / on a source as meaning \(dq\© the contents of this directory\(dq\& as opposed
148: to \(dq\© the directory by name\(dq\&, but in both cases the attributes of the
149: containing directory are transferred to the containing directory on the
150: destination. In other words, each of the following commands copies the
151: files in the same way, including their setting of the attributes of
152: /dest/foo:
153: .PP
154: .RS
155: \f(CWrsync \-av /src/foo /dest\fP
156: .br
157: \f(CWrsync \-av /src/foo/ /dest/foo\fP
158: .br
159: .RE
160:
161: .PP
162: Note also that host and module references don\(cq\&t require a trailing slash to
163: copy the contents of the default directory. For example, both of these
164: copy the remote directory\(cq\&s contents into \(dq\&/dest\(dq\&:
165: .PP
166: .RS
167: \f(CWrsync \-av host: /dest\fP
168: .br
169: \f(CWrsync \-av host::module /dest\fP
170: .br
171: .RE
172:
173: .PP
174: You can also use rsync in local\-only mode, where both the source and
175: destination don\(cq\&t have a \(cq\&:\(cq\& in the name. In this case it behaves like
176: an improved copy command.
177: .PP
178: Finally, you can list all the (listable) modules available from a
179: particular rsync daemon by leaving off the module name:
180: .PP
181: .RS
182: \f(CWrsync somehost.mydomain.com::\fP
183: .RE
184:
185: .PP
186: See the following section for more details.
187: .PP
188: .SH "ADVANCED USAGE"
189:
190: .PP
191: The syntax for requesting multiple files from a remote host is done by
192: specifying additional remote\-host args in the same style as the first,
193: or with the hostname omitted. For instance, all these work:
194: .PP
195: .RS
196: \f(CWrsync \-av host:file1 :file2 host:file{3,4} /dest/\fP
197: .br
198: \f(CWrsync \-av host::modname/file{1,2} host::modname/file3 /dest/\fP
199: .br
200: \f(CWrsync \-av host::modname/file1 ::modname/file{3,4}\fP
201: .RE
202:
203: .PP
204: Older versions of rsync required using quoted spaces in the SRC, like these
205: examples:
206: .PP
207: .RS
208: \f(CWrsync \-av host:'\&dir1/file1 dir2/file2'\& /dest\fP
209: .br
210: \f(CWrsync host::'\&modname/dir1/file1 modname/dir2/file2'\& /dest\fP
211: .RE
212:
213: .PP
214: This word\-splitting still works (by default) in the latest rsync, but is
215: not as easy to use as the first method.
216: .PP
217: If you need to transfer a filename that contains whitespace, you can either
218: specify the \fB\-\-protect\-args\fP (\fB\-s\fP) option, or you\(cq\&ll need to escape
219: the whitespace in a way that the remote shell will understand. For
220: instance:
221: .PP
222: .RS
223: \f(CWrsync \-av host:'\&file\e name\e with\e spaces'\& /dest\fP
224: .RE
225:
226: .PP
227: .SH "CONNECTING TO AN RSYNC DAEMON"
228:
229: .PP
230: It is also possible to use rsync without a remote shell as the transport.
231: In this case you will directly connect to a remote rsync daemon, typically
232: using TCP port 873. (This obviously requires the daemon to be running on
233: the remote system, so refer to the STARTING AN RSYNC DAEMON TO ACCEPT
234: CONNECTIONS section below for information on that.)
235: .PP
236: Using rsync in this way is the same as using it with a remote shell except
237: that:
238: .PP
239: .IP o
240: you either use a double colon :: instead of a single colon to
241: separate the hostname from the path, or you use an rsync:// URL.
242: .IP o
243: the first word of the \(dq\&path\(dq\& is actually a module name.
244: .IP o
245: the remote daemon may print a message of the day when you
246: connect.
247: .IP o
248: if you specify no path name on the remote daemon then the
249: list of accessible paths on the daemon will be shown.
250: .IP o
251: if you specify no local destination then a listing of the
252: specified files on the remote daemon is provided.
253: .IP o
254: you must not specify the \fB\-\-rsh\fP (\fB\-e\fP) option.
255:
256: .PP
257: An example that copies all the files in a remote module named \(dq\&src\(dq\&:
258: .PP
259: .nf
260: rsync \-av host::src /dest
261: .fi
262:
263: .PP
264: Some modules on the remote daemon may require authentication. If so,
265: you will receive a password prompt when you connect. You can avoid the
266: password prompt by setting the environment variable RSYNC_PASSWORD to
267: the password you want to use or using the \fB\-\-password\-file\fP option. This
268: may be useful when scripting rsync.
269: .PP
270: WARNING: On some systems environment variables are visible to all
271: users. On those systems using \fB\-\-password\-file\fP is recommended.
272: .PP
273: You may establish the connection via a web proxy by setting the
274: environment variable RSYNC_PROXY to a hostname:port pair pointing to
275: your web proxy. Note that your web proxy\(cq\&s configuration must support
276: proxy connections to port 873.
277: .PP
278: You may also establish a daemon connection using a program as a proxy by
279: setting the environment variable RSYNC_CONNECT_PROG to the commands you
280: wish to run in place of making a direct socket connection. The string may
281: contain the escape \(dq\&%H\(dq\& to represent the hostname specified in the rsync
282: command (so use \(dq\&%%\(dq\& if you need a single \(dq\&%\(dq\& in your string). For
283: example:
284: .PP
285: .nf
286: export RSYNC_CONNECT_PROG='\&ssh proxyhost nc %H 873'\&
287: rsync \-av targethost1::module/src/ /dest/
288: rsync \-av rsync:://targethost2/module/src/ /dest/
289: .fi
290:
291: .PP
292: The command specified above uses ssh to run nc (netcat) on a proxyhost,
293: which forwards all data to port 873 (the rsync daemon) on the targethost
294: (%H).
295: .PP
296: .SH "USING RSYNC\-DAEMON FEATURES VIA A REMOTE\-SHELL CONNECTION"
297:
298: .PP
299: It is sometimes useful to use various features of an rsync daemon (such as
300: named modules) without actually allowing any new socket connections into a
301: system (other than what is already required to allow remote\-shell access).
302: Rsync supports connecting to a host using a remote shell and then spawning
303: a single\-use \(dq\&daemon\(dq\& server that expects to read its config file in the
304: home dir of the remote user. This can be useful if you want to encrypt a
305: daemon\-style transfer\(cq\&s data, but since the daemon is started up fresh by
306: the remote user, you may not be able to use features such as chroot or
307: change the uid used by the daemon. (For another way to encrypt a daemon
308: transfer, consider using ssh to tunnel a local port to a remote machine and
309: configure a normal rsync daemon on that remote host to only allow
310: connections from \(dq\&localhost\(dq\&.)
311: .PP
312: From the user\(cq\&s perspective, a daemon transfer via a remote\-shell
313: connection uses nearly the same command\-line syntax as a normal
314: rsync\-daemon transfer, with the only exception being that you must
315: explicitly set the remote shell program on the command\-line with the
316: \fB\-\-rsh=COMMAND\fP option. (Setting the RSYNC_RSH in the environment
317: will not turn on this functionality.) For example:
318: .PP
319: .nf
320: rsync \-av \-\-rsh=ssh host::module /dest
321: .fi
322:
323: .PP
324: If you need to specify a different remote\-shell user, keep in mind that the
325: user@ prefix in front of the host is specifying the rsync\-user value (for a
326: module that requires user\-based authentication). This means that you must
327: give the \(cq\&\-l user\(cq\& option to ssh when specifying the remote\-shell, as in
328: this example that uses the short version of the \fB\-\-rsh\fP option:
329: .PP
330: .nf
331: rsync \-av \-e \(dq\&ssh \-l ssh\-user\(dq\& rsync\-user@host::module /dest
332: .fi
333:
334: .PP
335: The \(dq\&ssh\-user\(dq\& will be used at the ssh level; the \(dq\&rsync\-user\(dq\& will be
336: used to log\-in to the \(dq\&module\(dq\&.
337: .PP
338: .SH "STARTING AN RSYNC DAEMON TO ACCEPT CONNECTIONS"
339:
340: .PP
341: In order to connect to an rsync daemon, the remote system needs to have a
342: daemon already running (or it needs to have configured something like inetd
343: to spawn an rsync daemon for incoming connections on a particular port).
344: For full information on how to start a daemon that will handling incoming
345: socket connections, see the \fBrsyncd.conf\fP(5) man page \-\- that is the config
346: file for the daemon, and it contains the full details for how to run the
347: daemon (including stand\-alone and inetd configurations).
348: .PP
349: If you\(cq\&re using one of the remote\-shell transports for the transfer, there is
350: no need to manually start an rsync daemon.
351: .PP
352: .SH "SORTED TRANSFER ORDER"
353:
354: .PP
355: Rsync always sorts the specified filenames into its internal transfer list.
356: This handles the merging together of the contents of identically named
357: directories, makes it easy to remove duplicate filenames, and may confuse
358: someone when the files are transferred in a different order than what was
359: given on the command\-line.
360: .PP
361: If you need a particular file to be transferred prior to another, either
362: separate the files into different rsync calls, or consider using
363: \fB\-\-delay\-updates\fP (which doesn\(cq\&t affect the sorted transfer order, but
364: does make the final file\-updating phase happen much more rapidly).
365: .PP
366: .SH "EXAMPLES"
367:
368: .PP
369: Here are some examples of how I use rsync.
370: .PP
371: To backup my wife\(cq\&s home directory, which consists of large MS Word
372: files and mail folders, I use a cron job that runs
373: .PP
374: .RS
375: \f(CWrsync \-Cavz . arvidsjaur:backup\fP
376: .RE
377:
378: .PP
379: each night over a PPP connection to a duplicate directory on my machine
380: \(dq\&arvidsjaur\(dq\&.
381: .PP
382: To synchronize my samba source trees I use the following Makefile
383: targets:
384: .PP
385: .nf
386: get:
387: rsync \-avuzb \-\-exclude '\&*~'\& samba:samba/ .
388: put:
389: rsync \-Cavuzb . samba:samba/
390: sync: get put
391: .fi
392:
393: .PP
394: this allows me to sync with a CVS directory at the other end of the
395: connection. I then do CVS operations on the remote machine, which saves a
396: lot of time as the remote CVS protocol isn\(cq\&t very efficient.
397: .PP
398: I mirror a directory between my \(dq\&old\(dq\& and \(dq\&new\(dq\& ftp sites with the
399: command:
400: .PP
401: \f(CWrsync \-az \-e ssh \-\-delete ~ftp/pub/samba nimbus:\(dq\&~ftp/pub/tridge\(dq\&\fP
402: .PP
403: This is launched from cron every few hours.
404: .PP
405: .SH "OPTIONS SUMMARY"
406:
407: .PP
408: Here is a short summary of the options available in rsync. Please refer
409: to the detailed description below for a complete description.
410: .nf
411:
412: \-v, \-\-verbose increase verbosity
1.1.1.2 misho 413: \-\-info=FLAGS fine\-grained informational verbosity
414: \-\-debug=FLAGS fine\-grained debug verbosity
415: \-\-msgs2stderr special output handling for debugging
1.1 misho 416: \-q, \-\-quiet suppress non\-error messages
417: \-\-no\-motd suppress daemon\-mode MOTD (see caveat)
418: \-c, \-\-checksum skip based on checksum, not mod\-time & size
419: \-a, \-\-archive archive mode; equals \-rlptgoD (no \-H,\-A,\-X)
420: \-\-no\-OPTION turn off an implied OPTION (e.g. \-\-no\-D)
421: \-r, \-\-recursive recurse into directories
422: \-R, \-\-relative use relative path names
423: \-\-no\-implied\-dirs don'\&t send implied dirs with \-\-relative
424: \-b, \-\-backup make backups (see \-\-suffix & \-\-backup\-dir)
425: \-\-backup\-dir=DIR make backups into hierarchy based in DIR
426: \-\-suffix=SUFFIX backup suffix (default ~ w/o \-\-backup\-dir)
427: \-u, \-\-update skip files that are newer on the receiver
428: \-\-inplace update destination files in\-place
429: \-\-append append data onto shorter files
430: \-\-append\-verify \-\-append w/old data in file checksum
431: \-d, \-\-dirs transfer directories without recursing
432: \-l, \-\-links copy symlinks as symlinks
433: \-L, \-\-copy\-links transform symlink into referent file/dir
434: \-\-copy\-unsafe\-links only \(dq\&unsafe\(dq\& symlinks are transformed
435: \-\-safe\-links ignore symlinks that point outside the tree
1.1.1.2 misho 436: \-\-munge\-links munge symlinks to make them safer
1.1 misho 437: \-k, \-\-copy\-dirlinks transform symlink to dir into referent dir
438: \-K, \-\-keep\-dirlinks treat symlinked dir on receiver as dir
439: \-H, \-\-hard\-links preserve hard links
440: \-p, \-\-perms preserve permissions
441: \-E, \-\-executability preserve executability
442: \-\-chmod=CHMOD affect file and/or directory permissions
443: \-A, \-\-acls preserve ACLs (implies \-p)
444: \-X, \-\-xattrs preserve extended attributes
445: \-o, \-\-owner preserve owner (super\-user only)
446: \-g, \-\-group preserve group
447: \-\-devices preserve device files (super\-user only)
448: \-\-specials preserve special files
449: \-D same as \-\-devices \-\-specials
450: \-t, \-\-times preserve modification times
451: \-O, \-\-omit\-dir\-times omit directories from \-\-times
1.1.1.2 misho 452: \-J, \-\-omit\-link\-times omit symlinks from \-\-times
1.1 misho 453: \-\-super receiver attempts super\-user activities
454: \-\-fake\-super store/recover privileged attrs using xattrs
455: \-S, \-\-sparse handle sparse files efficiently
1.1.1.2 misho 456: \-\-preallocate allocate dest files before writing
1.1 misho 457: \-n, \-\-dry\-run perform a trial run with no changes made
458: \-W, \-\-whole\-file copy files whole (w/o delta\-xfer algorithm)
459: \-x, \-\-one\-file\-system don'\&t cross filesystem boundaries
460: \-B, \-\-block\-size=SIZE force a fixed checksum block\-size
461: \-e, \-\-rsh=COMMAND specify the remote shell to use
462: \-\-rsync\-path=PROGRAM specify the rsync to run on remote machine
463: \-\-existing skip creating new files on receiver
464: \-\-ignore\-existing skip updating files that exist on receiver
465: \-\-remove\-source\-files sender removes synchronized files (non\-dir)
466: \-\-del an alias for \-\-delete\-during
467: \-\-delete delete extraneous files from dest dirs
468: \-\-delete\-before receiver deletes before xfer, not during
469: \-\-delete\-during receiver deletes during the transfer
470: \-\-delete\-delay find deletions during, delete after
471: \-\-delete\-after receiver deletes after transfer, not during
472: \-\-delete\-excluded also delete excluded files from dest dirs
1.1.1.2 misho 473: \-\-ignore\-missing\-args ignore missing source args without error
474: \-\-delete\-missing\-args delete missing source args from destination
1.1 misho 475: \-\-ignore\-errors delete even if there are I/O errors
476: \-\-force force deletion of dirs even if not empty
477: \-\-max\-delete=NUM don'\&t delete more than NUM files
478: \-\-max\-size=SIZE don'\&t transfer any file larger than SIZE
479: \-\-min\-size=SIZE don'\&t transfer any file smaller than SIZE
480: \-\-partial keep partially transferred files
481: \-\-partial\-dir=DIR put a partially transferred file into DIR
482: \-\-delay\-updates put all updated files into place at end
483: \-m, \-\-prune\-empty\-dirs prune empty directory chains from file\-list
484: \-\-numeric\-ids don'\&t map uid/gid values by user/group name
1.1.1.2 misho 485: \-\-usermap=STRING custom username mapping
486: \-\-groupmap=STRING custom groupname mapping
487: \-\-chown=USER:GROUP simple username/groupname mapping
1.1 misho 488: \-\-timeout=SECONDS set I/O timeout in seconds
489: \-\-contimeout=SECONDS set daemon connection timeout in seconds
490: \-I, \-\-ignore\-times don'\&t skip files that match size and time
491: \-\-size\-only skip files that match in size
492: \-\-modify\-window=NUM compare mod\-times with reduced accuracy
493: \-T, \-\-temp\-dir=DIR create temporary files in directory DIR
494: \-y, \-\-fuzzy find similar file for basis if no dest file
495: \-\-compare\-dest=DIR also compare received files relative to DIR
496: \-\-copy\-dest=DIR ... and include copies of unchanged files
497: \-\-link\-dest=DIR hardlink to files in DIR when unchanged
498: \-z, \-\-compress compress file data during the transfer
499: \-\-compress\-level=NUM explicitly set compression level
500: \-\-skip\-compress=LIST skip compressing files with suffix in LIST
501: \-C, \-\-cvs\-exclude auto\-ignore files in the same way CVS does
502: \-f, \-\-filter=RULE add a file\-filtering RULE
503: \-F same as \-\-filter='\&dir\-merge /.rsync\-filter'\&
504: repeated: \-\-filter='\&\- .rsync\-filter'\&
505: \-\-exclude=PATTERN exclude files matching PATTERN
506: \-\-exclude\-from=FILE read exclude patterns from FILE
507: \-\-include=PATTERN don'\&t exclude files matching PATTERN
508: \-\-include\-from=FILE read include patterns from FILE
509: \-\-files\-from=FILE read list of source\-file names from FILE
510: \-0, \-\-from0 all *from/filter files are delimited by 0s
511: \-s, \-\-protect\-args no space\-splitting; wildcard chars only
512: \-\-address=ADDRESS bind address for outgoing socket to daemon
513: \-\-port=PORT specify double\-colon alternate port number
514: \-\-sockopts=OPTIONS specify custom TCP options
515: \-\-blocking\-io use blocking I/O for the remote shell
1.1.1.2 misho 516: \-\-outbuf=N|L|B set out buffering to None, Line, or Block
1.1 misho 517: \-\-stats give some file\-transfer stats
518: \-8, \-\-8\-bit\-output leave high\-bit chars unescaped in output
519: \-h, \-\-human\-readable output numbers in a human\-readable format
520: \-\-progress show progress during transfer
521: \-P same as \-\-partial \-\-progress
522: \-i, \-\-itemize\-changes output a change\-summary for all updates
1.1.1.2 misho 523: \-M, \-\-remote\-option=OPTION send OPTION to the remote side only
1.1 misho 524: \-\-out\-format=FORMAT output updates using the specified FORMAT
525: \-\-log\-file=FILE log what we'\&re doing to the specified FILE
526: \-\-log\-file\-format=FMT log updates using the specified FMT
527: \-\-password\-file=FILE read daemon\-access password from FILE
528: \-\-list\-only list the files instead of copying them
1.1.1.2 misho 529: \-\-bwlimit=RATE limit socket I/O bandwidth
1.1 misho 530: \-\-write\-batch=FILE write a batched update to FILE
531: \-\-only\-write\-batch=FILE like \-\-write\-batch but w/o updating dest
532: \-\-read\-batch=FILE read a batched update from FILE
533: \-\-protocol=NUM force an older protocol version to be used
534: \-\-iconv=CONVERT_SPEC request charset conversion of filenames
535: \-\-checksum\-seed=NUM set block/file checksum seed (advanced)
536: \-4, \-\-ipv4 prefer IPv4
537: \-6, \-\-ipv6 prefer IPv6
538: \-\-version print version number
539: (\-h) \-\-help show this help (see below for \-h comment)
540: .fi
541:
542: .PP
543: Rsync can also be run as a daemon, in which case the following options are
544: accepted:
545: .nf
546:
547: \-\-daemon run as an rsync daemon
548: \-\-address=ADDRESS bind to the specified address
1.1.1.2 misho 549: \-\-bwlimit=RATE limit socket I/O bandwidth
1.1 misho 550: \-\-config=FILE specify alternate rsyncd.conf file
1.1.1.2 misho 551: \-M, \-\-dparam=OVERRIDE override global daemon config parameter
1.1 misho 552: \-\-no\-detach do not detach from the parent
553: \-\-port=PORT listen on alternate port number
554: \-\-log\-file=FILE override the \(dq\&log file\(dq\& setting
555: \-\-log\-file\-format=FMT override the \(dq\&log format\(dq\& setting
556: \-\-sockopts=OPTIONS specify custom TCP options
557: \-v, \-\-verbose increase verbosity
558: \-4, \-\-ipv4 prefer IPv4
559: \-6, \-\-ipv6 prefer IPv6
560: \-h, \-\-help show this help (if used after \-\-daemon)
561: .fi
562:
563: .PP
564: .SH "OPTIONS"
565:
566: .PP
567: Rsync accepts both long (double\-dash + word) and short (single\-dash + letter)
568: options. The full list of the available options are described below. If an
569: option can be specified in more than one way, the choices are comma\-separated.
570: Some options only have a long variant, not a short. If the option takes a
571: parameter, the parameter is only listed after the long variant, even though it
572: must also be specified for the short. When specifying a parameter, you can
573: either use the form \-\-option=param or replace the \(cq\&=\(cq\& with whitespace. The
574: parameter may need to be quoted in some manner for it to survive the shell\(cq\&s
575: command\-line parsing. Keep in mind that a leading tilde (~) in a filename is
576: substituted by your shell, so \-\-option=~/foo will not change the tilde into
577: your home directory (remove the \(cq\&=\(cq\& for that).
578: .PP
579: .IP "\fB\-\-help\fP"
580: Print a short help page describing the options
581: available in rsync and exit. For backward\-compatibility with older
582: versions of rsync, the help will also be output if you use the \fB\-h\fP
583: option without any other args.
584: .IP
585: .IP "\fB\-\-version\fP"
586: print the rsync version number and exit.
587: .IP
588: .IP "\fB\-v, \-\-verbose\fP"
589: This option increases the amount of information you
590: are given during the transfer. By default, rsync works silently. A
591: single \fB\-v\fP will give you information about what files are being
592: transferred and a brief summary at the end. Two \fB\-v\fP options will give you
593: information on what files are being skipped and slightly more
594: information at the end. More than two \fB\-v\fP options should only be used if
595: you are debugging rsync.
596: .IP
1.1.1.2 misho 597: In a modern rsync, the \fB\-v\fP option is equivalent to the setting of groups
598: of \fB\-\-info\fP and \fB\-\-debug\fP options. You can choose to use these newer
599: options in addition to, or in place of using \fB\-\-verbose\fP, as any
600: fine\-grained settings override the implied settings of \fB\-v\fP. Both
601: \fB\-\-info\fP and \fB\-\-debug\fP have a way to ask for help that tells you
602: exactly what flags are set for each increase in verbosity.
603: .IP
1.1.1.3 ! misho 604: However, do keep in mind that a daemon\(cq\&s \(dq\&max verbosity\(dq\& setting will limit how
! 605: high of a level the various individual flags can be set on the daemon side.
! 606: For instance, if the max is 2, then any info and/or debug flag that is set to
! 607: a higher value than what would be set by \fB\-vv\fP will be downgraded to the
! 608: \fB\-vv\fP level in the daemon\(cq\&s logging.
! 609: .IP
1.1.1.2 misho 610: .IP "\fB\-\-info=FLAGS\fP"
611: This option lets you have fine\-grained control over the
612: information
613: output you want to see. An individual flag name may be followed by a level
614: number, with 0 meaning to silence that output, 1 being the default output
615: level, and higher numbers increasing the output of that flag (for those
616: that support higher levels). Use
617: \fB\-\-info=help\fP
618: to see all the available flag names, what they output, and what flag names
619: are added for each increase in the verbose level. Some examples:
620: .IP
621: .nf
622: rsync \-a \-\-info=progress2 src/ dest/
623: rsync \-avv \-\-info=stats2,misc1,flist0 src/ dest/
624: .fi
625:
626: .IP
627: Note that \fB\-\-info=name\fP\(cq\&s output is affected by the \fB\-\-out\-format\fP and
628: \fB\-\-itemize\-changes\fP (\fB\-i\fP) options. See those options for more
629: information on what is output and when.
630: .IP
631: This option was added to 3.1.0, so an older rsync on the server side might
632: reject your attempts at fine\-grained control (if one or more flags needed
633: to be send to the server and the server was too old to understand them).
1.1.1.3 ! misho 634: See also the \(dq\&max verbosity\(dq\& caveat above when dealing with a daemon.
1.1.1.2 misho 635: .IP
636: .IP "\fB\-\-debug=FLAGS\fP"
637: This option lets you have fine\-grained control over the debug
638: output you want to see. An individual flag name may be followed by a level
639: number, with 0 meaning to silence that output, 1 being the default output
640: level, and higher numbers increasing the output of that flag (for those
641: that support higher levels). Use
642: \fB\-\-debug=help\fP
643: to see all the available flag names, what they output, and what flag names
644: are added for each increase in the verbose level. Some examples:
645: .IP
646: .nf
647: rsync \-avvv \-\-debug=none src/ dest/
648: rsync \-avA \-\-del \-\-debug=del2,acl src/ dest/
649: .fi
650:
651: .IP
652: Note that some debug messages will only be output when \fB\-\-msgs2stderr\fP is
653: specified, especially those pertaining to I/O and buffer debugging.
654: .IP
655: This option was added to 3.1.0, so an older rsync on the server side might
656: reject your attempts at fine\-grained control (if one or more flags needed
657: to be send to the server and the server was too old to understand them).
1.1.1.3 ! misho 658: See also the \(dq\&max verbosity\(dq\& caveat above when dealing with a daemon.
1.1.1.2 misho 659: .IP
660: .IP "\fB\-\-msgs2stderr\fP"
661: This option changes rsync to send all its output
662: directly to stderr rather than to send messages to the client side via the
663: protocol (which normally outputs info messages via stdout). This is mainly
664: intended for debugging in order to avoid changing the data sent via the
665: protocol, since the extra protocol data can change what is being tested.
1.1.1.3 ! misho 666: The option does not affect the remote side of a transfer without using
! 667: \fB\-\-remote\-option\fP \-\- e.g. \fB\-M\-\-msgs2stderr\fP.
! 668: Also keep in mind that a daemon connection does not have a stderr channel to send
1.1.1.2 misho 669: messages back to the client side, so if you are doing any daemon\-transfer
670: debugging using this option, you should start up a daemon using \fB\-\-no\-detach\fP
671: so that you can see the stderr output on the daemon side.
672: .IP
673: This option has the side\-effect of making stderr output get line\-buffered so
674: that the merging of the output of 3 programs happens in a more readable manner.
1.1 misho 675: .IP
676: .IP "\fB\-q, \-\-quiet\fP"
677: This option decreases the amount of information you
678: are given during the transfer, notably suppressing information messages
679: from the remote server. This option is useful when invoking rsync from
680: cron.
681: .IP
682: .IP "\fB\-\-no\-motd\fP"
683: This option affects the information that is output
684: by the client at the start of a daemon transfer. This suppresses the
685: message\-of\-the\-day (MOTD) text, but it also affects the list of modules
686: that the daemon sends in response to the \(dq\&rsync host::\(dq\& request (due to
687: a limitation in the rsync protocol), so omit this option if you want to
688: request the list of modules from the daemon.
689: .IP
690: .IP "\fB\-I, \-\-ignore\-times\fP"
691: Normally rsync will skip any files that are
692: already the same size and have the same modification timestamp.
693: This option turns off this \(dq\&quick check\(dq\& behavior, causing all files to
694: be updated.
695: .IP
696: .IP "\fB\-\-size\-only\fP"
697: This modifies rsync\(cq\&s \(dq\&quick check\(dq\& algorithm for
698: finding files that need to be transferred, changing it from the default of
699: transferring files with either a changed size or a changed last\-modified
700: time to just looking for files that have changed in size. This is useful
701: when starting to use rsync after using another mirroring system which may
702: not preserve timestamps exactly.
703: .IP
704: .IP "\fB\-\-modify\-window\fP"
705: When comparing two timestamps, rsync treats the
706: timestamps as being equal if they differ by no more than the modify\-window
707: value. This is normally 0 (for an exact match), but you may find it useful
708: to set this to a larger value in some situations. In particular, when
709: transferring to or from an MS Windows FAT filesystem (which represents
710: times with a 2\-second resolution), \fB\-\-modify\-window=1\fP is useful
711: (allowing times to differ by up to 1 second).
712: .IP
713: .IP "\fB\-c, \-\-checksum\fP"
714: This changes the way rsync checks if the files have
715: been changed and are in need of a transfer. Without this option, rsync
716: uses a \(dq\&quick check\(dq\& that (by default) checks if each file\(cq\&s size and time
717: of last modification match between the sender and receiver. This option
718: changes this to compare a 128\-bit checksum for each file that has a
719: matching size. Generating the checksums means that both sides will expend
720: a lot of disk I/O reading all the data in the files in the transfer (and
721: this is prior to any reading that will be done to transfer changed files),
722: so this can slow things down significantly.
723: .IP
724: The sending side generates its checksums while it is doing the file\-system
725: scan that builds the list of the available files. The receiver generates
726: its checksums when it is scanning for changed files, and will checksum any
727: file that has the same size as the corresponding sender\(cq\&s file: files with
728: either a changed size or a changed checksum are selected for transfer.
729: .IP
730: Note that rsync always verifies that each \fItransferred\fP file was
731: correctly reconstructed on the receiving side by checking a whole\-file
732: checksum that is generated as the file is transferred, but that
733: automatic after\-the\-transfer verification has nothing to do with this
734: option\(cq\&s before\-the\-transfer \(dq\&Does this file need to be updated?\(dq\& check.
735: .IP
736: For protocol 30 and beyond (first supported in 3.0.0), the checksum used is
737: MD5. For older protocols, the checksum used is MD4.
738: .IP
739: .IP "\fB\-a, \-\-archive\fP"
740: This is equivalent to \fB\-rlptgoD\fP. It is a quick
741: way of saying you want recursion and want to preserve almost
742: everything (with \-H being a notable omission).
743: The only exception to the above equivalence is when \fB\-\-files\-from\fP is
744: specified, in which case \fB\-r\fP is not implied.
745: .IP
746: Note that \fB\-a\fP \fBdoes not preserve hardlinks\fP, because
747: finding multiply\-linked files is expensive. You must separately
748: specify \fB\-H\fP.
749: .IP
750: .IP "\-\-no\-OPTION"
751: You may turn off one or more implied options by prefixing
752: the option name with \(dq\&no\-\(dq\&. Not all options may be prefixed with a \(dq\&no\-\(dq\&:
753: only options that are implied by other options (e.g. \fB\-\-no\-D\fP,
754: \fB\-\-no\-perms\fP) or have different defaults in various circumstances
755: (e.g. \fB\-\-no\-whole\-file\fP, \fB\-\-no\-blocking\-io\fP, \fB\-\-no\-dirs\fP). You may
756: specify either the short or the long option name after the \(dq\&no\-\(dq\& prefix
757: (e.g. \fB\-\-no\-R\fP is the same as \fB\-\-no\-relative\fP).
758: .IP
759: For example: if you want to use \fB\-a\fP (\fB\-\-archive\fP) but don\(cq\&t want
760: \fB\-o\fP (\fB\-\-owner\fP), instead of converting \fB\-a\fP into \fB\-rlptgD\fP, you
761: could specify \fB\-a \-\-no\-o\fP (or \fB\-a \-\-no\-owner\fP).
762: .IP
763: The order of the options is important: if you specify \fB\-\-no\-r \-a\fP, the
764: \fB\-r\fP option would end up being turned on, the opposite of \fB\-a \-\-no\-r\fP.
765: Note also that the side\-effects of the \fB\-\-files\-from\fP option are NOT
766: positional, as it affects the default state of several options and slightly
767: changes the meaning of \fB\-a\fP (see the \fB\-\-files\-from\fP option for more
768: details).
769: .IP
770: .IP "\fB\-r, \-\-recursive\fP"
771: This tells rsync to copy directories
772: recursively. See also \fB\-\-dirs\fP (\fB\-d\fP).
773: .IP
774: Beginning with rsync 3.0.0, the recursive algorithm used is now an
775: incremental scan that uses much less memory than before and begins the
776: transfer after the scanning of the first few directories have been
777: completed. This incremental scan only affects our recursion algorithm, and
778: does not change a non\-recursive transfer. It is also only possible when
779: both ends of the transfer are at least version 3.0.0.
780: .IP
781: Some options require rsync to know the full file list, so these options
782: disable the incremental recursion mode. These include: \fB\-\-delete\-before\fP,
783: \fB\-\-delete\-after\fP, \fB\-\-prune\-empty\-dirs\fP, and \fB\-\-delay\-updates\fP.
784: Because of this, the default delete mode when you specify \fB\-\-delete\fP is now
785: \fB\-\-delete\-during\fP when both ends of the connection are at least 3.0.0
786: (use \fB\-\-del\fP or \fB\-\-delete\-during\fP to request this improved deletion mode
787: explicitly). See also the \fB\-\-delete\-delay\fP option that is a better choice
788: than using \fB\-\-delete\-after\fP.
789: .IP
790: Incremental recursion can be disabled using the \fB\-\-no\-inc\-recursive\fP
791: option or its shorter \fB\-\-no\-i\-r\fP alias.
792: .IP
793: .IP "\fB\-R, \-\-relative\fP"
794: Use relative paths. This means that the full path
795: names specified on the command line are sent to the server rather than
796: just the last parts of the filenames. This is particularly useful when
797: you want to send several different directories at the same time. For
798: example, if you used this command:
799: .IP
800: .RS
801: \f(CW rsync \-av /foo/bar/baz.c remote:/tmp/\fP
802: .RE
803:
804: .IP
805: \&... this would create a file named baz.c in /tmp/ on the remote
806: machine. If instead you used
807: .IP
808: .RS
809: \f(CW rsync \-avR /foo/bar/baz.c remote:/tmp/\fP
810: .RE
811:
812: .IP
813: then a file named /tmp/foo/bar/baz.c would be created on the remote
814: machine, preserving its full path. These extra path elements are called
815: \(dq\&implied directories\(dq\& (i.e. the \(dq\&foo\(dq\& and the \(dq\&foo/bar\(dq\& directories in the
816: above example).
817: .IP
818: Beginning with rsync 3.0.0, rsync always sends these implied directories as
819: real directories in the file list, even if a path element is really a
820: symlink on the sending side. This prevents some really unexpected
821: behaviors when copying the full path of a file that you didn\(cq\&t realize had
822: a symlink in its path. If you want to duplicate a server\-side symlink,
823: include both the symlink via its path, and referent directory via its real
824: path. If you\(cq\&re dealing with an older rsync on the sending side, you may
825: need to use the \fB\-\-no\-implied\-dirs\fP option.
826: .IP
827: It is also possible to limit the amount of path information that is sent as
828: implied directories for each path you specify. With a modern rsync on the
829: sending side (beginning with 2.6.7), you can insert a dot and a slash into
830: the source path, like this:
831: .IP
832: .RS
833: \f(CW rsync \-avR /foo/./bar/baz.c remote:/tmp/\fP
834: .RE
835:
836: .IP
837: That would create /tmp/bar/baz.c on the remote machine. (Note that the
838: dot must be followed by a slash, so \(dq\&/foo/.\(dq\& would not be abbreviated.)
839: For older rsync versions, you would need to use a chdir to limit the
840: source path. For example, when pushing files:
841: .IP
842: .RS
843: \f(CW (cd /foo; rsync \-avR bar/baz.c remote:/tmp/) \fP
844: .RE
845:
846: .IP
847: (Note that the parens put the two commands into a sub\-shell, so that the
848: \(dq\&cd\(dq\& command doesn\(cq\&t remain in effect for future commands.)
849: If you\(cq\&re pulling files from an older rsync, use this idiom (but only
850: for a non\-daemon transfer):
851: .IP
852: .RS
853: \f(CW rsync \-avR \-\-rsync\-path=\(dq\&cd /foo; rsync\(dq\& \e \fP
854: .br
855: \f(CW remote:bar/baz.c /tmp/\fP
856: .RE
857:
858: .IP
859: .IP "\fB\-\-no\-implied\-dirs\fP"
860: This option affects the default behavior of the
861: \fB\-\-relative\fP option. When it is specified, the attributes of the implied
862: directories from the source names are not included in the transfer. This
863: means that the corresponding path elements on the destination system are
864: left unchanged if they exist, and any missing implied directories are
865: created with default attributes. This even allows these implied path
866: elements to have big differences, such as being a symlink to a directory on
867: the receiving side.
868: .IP
869: For instance, if a command\-line arg or a files\-from entry told rsync to
870: transfer the file \(dq\&path/foo/file\(dq\&, the directories \(dq\&path\(dq\& and \(dq\&path/foo\(dq\&
871: are implied when \fB\-\-relative\fP is used. If \(dq\&path/foo\(dq\& is a symlink to
872: \(dq\&bar\(dq\& on the destination system, the receiving rsync would ordinarily
873: delete \(dq\&path/foo\(dq\&, recreate it as a directory, and receive the file into
874: the new directory. With \fB\-\-no\-implied\-dirs\fP, the receiving rsync updates
875: \(dq\&path/foo/file\(dq\& using the existing path elements, which means that the file
876: ends up being created in \(dq\&path/bar\(dq\&. Another way to accomplish this link
877: preservation is to use the \fB\-\-keep\-dirlinks\fP option (which will also
878: affect symlinks to directories in the rest of the transfer).
879: .IP
880: When pulling files from an rsync older than 3.0.0, you may need to use this
881: option if the sending side has a symlink in the path you request and you
882: wish the implied directories to be transferred as normal directories.
883: .IP
884: .IP "\fB\-b, \-\-backup\fP"
885: With this option, preexisting destination files are
886: renamed as each file is transferred or deleted. You can control where the
887: backup file goes and what (if any) suffix gets appended using the
888: \fB\-\-backup\-dir\fP and \fB\-\-suffix\fP options.
889: .IP
890: Note that if you don\(cq\&t specify \fB\-\-backup\-dir\fP, (1) the
891: \fB\-\-omit\-dir\-times\fP option will be implied, and (2) if \fB\-\-delete\fP is
892: also in effect (without \fB\-\-delete\-excluded\fP), rsync will add a \(dq\&protect\(dq\&
893: filter\-rule for the backup suffix to the end of all your existing excludes
894: (e.g. \fB\-f \(dq\&P *~\(dq\&\fP). This will prevent previously backed\-up files from being
895: deleted. Note that if you are supplying your own filter rules, you may
896: need to manually insert your own exclude/protect rule somewhere higher up
897: in the list so that it has a high enough priority to be effective (e.g., if
898: your rules specify a trailing inclusion/exclusion of \(cq\&*\(cq\&, the auto\-added
899: rule would never be reached).
900: .IP
901: .IP "\fB\-\-backup\-dir=DIR\fP"
902: In combination with the \fB\-\-backup\fP option, this
903: tells rsync to store all backups in the specified directory on the receiving
904: side. This can be used for incremental backups. You can additionally
905: specify a backup suffix using the \fB\-\-suffix\fP option
906: (otherwise the files backed up in the specified directory
907: will keep their original filenames).
908: .IP
909: Note that if you specify a relative path, the backup directory will be
910: relative to the destination directory, so you probably want to specify
911: either an absolute path or a path that starts with \(dq\&../\(dq\&. If an rsync
912: daemon is the receiver, the backup dir cannot go outside the module\(cq\&s path
913: hierarchy, so take extra care not to delete it or copy into it.
914: .IP
915: .IP "\fB\-\-suffix=SUFFIX\fP"
916: This option allows you to override the default
917: backup suffix used with the \fB\-\-backup\fP (\fB\-b\fP) option. The default suffix is a ~
918: if no \-\fB\-backup\-dir\fP was specified, otherwise it is an empty string.
919: .IP
920: .IP "\fB\-u, \-\-update\fP"
921: This forces rsync to skip any files which exist on
922: the destination and have a modified time that is newer than the source
923: file. (If an existing destination file has a modification time equal to the
924: source file\(cq\&s, it will be updated if the sizes are different.)
925: .IP
1.1.1.3 ! misho 926: Note that this does not affect the copying of dirs, symlinks, or other special
1.1 misho 927: files. Also, a difference of file format between the sender and receiver
928: is always considered to be important enough for an update, no matter what
929: date is on the objects. In other words, if the source has a directory
930: where the destination has a file, the transfer would occur regardless of
931: the timestamps.
932: .IP
933: This option is a transfer rule, not an exclude, so it doesn\(cq\&t affect the
934: data that goes into the file\-lists, and thus it doesn\(cq\&t affect deletions.
935: It just limits the files that the receiver requests to be transferred.
936: .IP
937: .IP "\fB\-\-inplace\fP"
938: This option changes how rsync transfers a file when
939: its data needs to be updated: instead of the default method of creating
940: a new copy of the file and moving it into place when it is complete, rsync
941: instead writes the updated data directly to the destination file.
942: .IP
943: This has several effects:
944: .IP
945: .RS
946: .IP o
947: Hard links are not broken. This means the new data will be visible
948: through other hard links to the destination file. Moreover, attempts to
949: copy differing source files onto a multiply\-linked destination file will
950: result in a \(dq\&tug of war\(dq\& with the destination data changing back and forth.
951: .IP o
952: In\-use binaries cannot be updated (either the OS will prevent this from
953: happening, or binaries that attempt to swap\-in their data will misbehave or
954: crash).
955: .IP o
956: The file\(cq\&s data will be in an inconsistent state during the transfer
957: and will be left that way if the transfer is interrupted or if an update
958: fails.
959: .IP o
960: A file that rsync cannot write to cannot be updated. While a super user
961: can update any file, a normal user needs to be granted write permission for
962: the open of the file for writing to be successful.
963: .IP o
964: The efficiency of rsync\(cq\&s delta\-transfer algorithm may be reduced if
965: some data in the destination file is overwritten before it can be copied to
966: a position later in the file. This does not apply if you use \fB\-\-backup\fP,
967: since rsync is smart enough to use the backup file as the basis file for the
968: transfer.
969: .RE
970:
971: .IP
972: WARNING: you should not use this option to update files that are being
973: accessed by others, so be careful when choosing to use this for a copy.
974: .IP
975: This option is useful for transferring large files with block\-based changes
976: or appended data, and also on systems that are disk bound, not network
977: bound. It can also help keep a copy\-on\-write filesystem snapshot from
978: diverging the entire contents of a file that only has minor changes.
979: .IP
980: The option implies \fB\-\-partial\fP (since an interrupted transfer does not delete
981: the file), but conflicts with \fB\-\-partial\-dir\fP and \fB\-\-delay\-updates\fP.
982: Prior to rsync 2.6.4 \fB\-\-inplace\fP was also incompatible with \fB\-\-compare\-dest\fP
983: and \fB\-\-link\-dest\fP.
984: .IP
985: .IP "\fB\-\-append\fP"
986: This causes rsync to update a file by appending data onto
987: the end of the file, which presumes that the data that already exists on
988: the receiving side is identical with the start of the file on the sending
989: side. If a file needs to be transferred and its size on the receiver is
990: the same or longer than the size on the sender, the file is skipped. This
991: does not interfere with the updating of a file\(cq\&s non\-content attributes
992: (e.g. permissions, ownership, etc.) when the file does not need to be
993: transferred, nor does it affect the updating of any non\-regular files.
994: Implies \fB\-\-inplace\fP,
995: but does not conflict with \fB\-\-sparse\fP (since it is always extending a
996: file\(cq\&s length).
997: .IP
1.1.1.3 ! misho 998: The use of \fB\-\-append\fP can be dangerous if you aren\(cq\&t 100% sure that the files
! 999: that are longer have only grown by the appending of data onto the end. You
! 1000: should thus use include/exclude/filter rules to ensure that such a transfer is
! 1001: only affecting files that you know to be growing via appended data.
! 1002: .IP
1.1 misho 1003: .IP "\fB\-\-append\-verify\fP"
1004: This works just like the \fB\-\-append\fP option, but
1005: the existing data on the receiving side is included in the full\-file
1006: checksum verification step, which will cause a file to be resent if the
1007: final verification step fails (rsync uses a normal, non\-appending
1008: \fB\-\-inplace\fP transfer for the resend).
1009: .IP
1010: Note: prior to rsync 3.0.0, the \fB\-\-append\fP option worked like
1011: \fB\-\-append\-verify\fP, so if you are interacting with an older rsync (or the
1012: transfer is using a protocol prior to 30), specifying either append option
1013: will initiate an \fB\-\-append\-verify\fP transfer.
1014: .IP
1015: .IP "\fB\-d, \-\-dirs\fP"
1016: Tell the sending side to include any directories that
1017: are encountered. Unlike \fB\-\-recursive\fP, a directory\(cq\&s contents are not copied
1018: unless the directory name specified is \(dq\&.\(dq\& or ends with a trailing slash
1019: (e.g. \(dq\&.\(dq\&, \(dq\&dir/.\(dq\&, \(dq\&dir/\(dq\&, etc.). Without this option or the
1020: \fB\-\-recursive\fP option, rsync will skip all directories it encounters (and
1021: output a message to that effect for each one). If you specify both
1022: \fB\-\-dirs\fP and \fB\-\-recursive\fP, \fB\-\-recursive\fP takes precedence.
1023: .IP
1024: The \fB\-\-dirs\fP option is implied by the \fB\-\-files\-from\fP option
1025: or the \fB\-\-list\-only\fP option (including an implied
1026: \fB\-\-list\-only\fP usage) if \fB\-\-recursive\fP wasn\(cq\&t specified (so that
1027: directories are seen in the listing). Specify \fB\-\-no\-dirs\fP (or \fB\-\-no\-d\fP)
1028: if you want to turn this off.
1029: .IP
1030: There is also a backward\-compatibility helper option, \fB\-\-old\-dirs\fP (or
1031: \fB\-\-old\-d\fP) that tells rsync to use a hack of \(dq\&\-r \-\-exclude=\(cq\&/*/*\(cq\&\(dq\& to get
1032: an older rsync to list a single directory without recursing.
1033: .IP
1034: .IP "\fB\-l, \-\-links\fP"
1035: When symlinks are encountered, recreate the
1036: symlink on the destination.
1037: .IP
1038: .IP "\fB\-L, \-\-copy\-links\fP"
1039: When symlinks are encountered, the item that
1040: they point to (the referent) is copied, rather than the symlink. In older
1041: versions of rsync, this option also had the side\-effect of telling the
1042: receiving side to follow symlinks, such as symlinks to directories. In a
1043: modern rsync such as this one, you\(cq\&ll need to specify \fB\-\-keep\-dirlinks\fP (\fB\-K\fP)
1044: to get this extra behavior. The only exception is when sending files to
1045: an rsync that is too old to understand \fB\-K\fP \-\- in that case, the \fB\-L\fP option
1046: will still have the side\-effect of \fB\-K\fP on that older receiving rsync.
1047: .IP
1048: .IP "\fB\-\-copy\-unsafe\-links\fP"
1049: This tells rsync to copy the referent of
1050: symbolic links that point outside the copied tree. Absolute symlinks
1051: are also treated like ordinary files, and so are any symlinks in the
1052: source path itself when \fB\-\-relative\fP is used. This option has no
1053: additional effect if \fB\-\-copy\-links\fP was also specified.
1054: .IP
1055: .IP "\fB\-\-safe\-links\fP"
1056: This tells rsync to ignore any symbolic links
1057: which point outside the copied tree. All absolute symlinks are
1058: also ignored. Using this option in conjunction with \fB\-\-relative\fP may
1059: give unexpected results.
1060: .IP
1.1.1.2 misho 1061: .IP "\fB\-\-munge\-links\fP"
1062: This option tells rsync to (1) modify all symlinks on
1063: the receiving side in a way that makes them unusable but recoverable (see
1064: below), or (2) to unmunge symlinks on the sending side that had been stored in
1065: a munged state. This is useful if you don\(cq\&t quite trust the source of the data
1066: to not try to slip in a symlink to a unexpected place.
1067: .IP
1068: The way rsync disables the use of symlinks is to prefix each one with the
1069: string \(dq\&/rsyncd\-munged/\(dq\&. This prevents the links from being used as long as
1070: that directory does not exist. When this option is enabled, rsync will refuse
1071: to run if that path is a directory or a symlink to a directory.
1072: .IP
1073: The option only affects the client side of the transfer, so if you need it to
1074: affect the server, specify it via \fB\-\-remote\-option\fP. (Note that in a local
1075: transfer, the client side is the sender.)
1076: .IP
1077: This option has no affect on a daemon, since the daemon configures whether it
1078: wants munged symlinks via its \(dq\&munge symlinks\(dq\& parameter. See also the
1079: \(dq\&munge\-symlinks\(dq\& perl script in the support directory of the source code.
1080: .IP
1.1 misho 1081: .IP "\fB\-k, \-\-copy\-dirlinks\fP"
1082: This option causes the sending side to treat
1083: a symlink to a directory as though it were a real directory. This is
1084: useful if you don\(cq\&t want symlinks to non\-directories to be affected, as
1085: they would be using \fB\-\-copy\-links\fP.
1086: .IP
1087: Without this option, if the sending side has replaced a directory with a
1088: symlink to a directory, the receiving side will delete anything that is in
1089: the way of the new symlink, including a directory hierarchy (as long as
1090: \fB\-\-force\fP or \fB\-\-delete\fP is in effect).
1091: .IP
1092: See also \fB\-\-keep\-dirlinks\fP for an analogous option for the receiving
1093: side.
1094: .IP
1095: \fB\-\-copy\-dirlinks\fP applies to all symlinks to directories in the source. If
1096: you want to follow only a few specified symlinks, a trick you can use is to
1097: pass them as additional source args with a trailing slash, using \fB\-\-relative\fP
1098: to make the paths match up right. For example:
1099: .IP
1100: .RS
1101: \f(CWrsync \-r \-\-relative src/./ src/./follow\-me/ dest/\fP
1102: .RE
1103:
1104: .IP
1105: This works because rsync calls \fBlstat\fP(2) on the source arg as given, and the
1106: trailing slash makes \fBlstat\fP(2) follow the symlink, giving rise to a directory
1107: in the file\-list which overrides the symlink found during the scan of \(dq\&src/./\(dq\&.
1108: .IP
1109: .IP "\fB\-K, \-\-keep\-dirlinks\fP"
1110: This option causes the receiving side to treat
1111: a symlink to a directory as though it were a real directory, but only if it
1112: matches a real directory from the sender. Without this option, the
1113: receiver\(cq\&s symlink would be deleted and replaced with a real directory.
1114: .IP
1115: For example, suppose you transfer a directory \(dq\&foo\(dq\& that contains a file
1116: \(dq\&file\(dq\&, but \(dq\&foo\(dq\& is a symlink to directory \(dq\&bar\(dq\& on the receiver. Without
1117: \fB\-\-keep\-dirlinks\fP, the receiver deletes symlink \(dq\&foo\(dq\&, recreates it as a
1118: directory, and receives the file into the new directory. With
1119: \fB\-\-keep\-dirlinks\fP, the receiver keeps the symlink and \(dq\&file\(dq\& ends up in
1120: \(dq\&bar\(dq\&.
1121: .IP
1122: One note of caution: if you use \fB\-\-keep\-dirlinks\fP, you must trust all
1123: the symlinks in the copy! If it is possible for an untrusted user to
1124: create their own symlink to any directory, the user could then (on a
1125: subsequent copy) replace the symlink with a real directory and affect the
1126: content of whatever directory the symlink references. For backup copies,
1127: you are better off using something like a bind mount instead of a symlink
1128: to modify your receiving hierarchy.
1129: .IP
1130: See also \fB\-\-copy\-dirlinks\fP for an analogous option for the sending side.
1131: .IP
1132: .IP "\fB\-H, \-\-hard\-links\fP"
1133: This tells rsync to look for hard\-linked files in
1134: the source and link together the corresponding files on the destination.
1135: Without this option, hard\-linked files in the source are treated
1136: as though they were separate files.
1137: .IP
1138: This option does NOT necessarily ensure that the pattern of hard links on the
1139: destination exactly matches that on the source. Cases in which the
1140: destination may end up with extra hard links include the following:
1141: .IP
1142: .RS
1143: .IP o
1144: If the destination contains extraneous hard\-links (more linking than
1145: what is present in the source file list), the copying algorithm will not
1146: break them explicitly. However, if one or more of the paths have content
1147: differences, the normal file\-update process will break those extra links
1148: (unless you are using the \fB\-\-inplace\fP option).
1149: .IP o
1150: If you specify a \fB\-\-link\-dest\fP directory that contains hard links,
1151: the linking of the destination files against the \fB\-\-link\-dest\fP files can
1152: cause some paths in the destination to become linked together due to the
1153: \fB\-\-link\-dest\fP associations.
1154: .RE
1155:
1156: .IP
1157: Note that rsync can only detect hard links between files that are inside
1158: the transfer set. If rsync updates a file that has extra hard\-link
1159: connections to files outside the transfer, that linkage will be broken. If
1160: you are tempted to use the \fB\-\-inplace\fP option to avoid this breakage, be
1161: very careful that you know how your files are being updated so that you are
1162: certain that no unintended changes happen due to lingering hard links (and
1163: see the \fB\-\-inplace\fP option for more caveats).
1164: .IP
1165: If incremental recursion is active (see \fB\-\-recursive\fP), rsync may transfer
1166: a missing hard\-linked file before it finds that another link for that contents
1167: exists elsewhere in the hierarchy. This does not affect the accuracy of
1168: the transfer (i.e. which files are hard\-linked together), just its efficiency
1169: (i.e. copying the data for a new, early copy of a hard\-linked file that could
1170: have been found later in the transfer in another member of the hard\-linked
1171: set of files). One way to avoid this inefficiency is to disable
1172: incremental recursion using the \fB\-\-no\-inc\-recursive\fP option.
1173: .IP
1174: .IP "\fB\-p, \-\-perms\fP"
1175: This option causes the receiving rsync to set the
1176: destination permissions to be the same as the source permissions. (See
1177: also the \fB\-\-chmod\fP option for a way to modify what rsync considers to
1178: be the source permissions.)
1179: .IP
1180: When this option is \fIoff\fP, permissions are set as follows:
1181: .IP
1182: .RS
1183: .IP o
1184: Existing files (including updated files) retain their existing
1185: permissions, though the \fB\-\-executability\fP option might change just
1186: the execute permission for the file.
1187: .IP o
1188: New files get their \(dq\&normal\(dq\& permission bits set to the source
1189: file\(cq\&s permissions masked with the receiving directory\(cq\&s default
1190: permissions (either the receiving process\(cq\&s umask, or the permissions
1191: specified via the destination directory\(cq\&s default ACL), and
1192: their special permission bits disabled except in the case where a new
1193: directory inherits a setgid bit from its parent directory.
1194: .RE
1195:
1196: .IP
1197: Thus, when \fB\-\-perms\fP and \fB\-\-executability\fP are both disabled,
1198: rsync\(cq\&s behavior is the same as that of other file\-copy utilities,
1199: such as \fBcp\fP(1) and \fBtar\fP(1).
1200: .IP
1201: In summary: to give destination files (both old and new) the source
1202: permissions, use \fB\-\-perms\fP. To give new files the destination\-default
1203: permissions (while leaving existing files unchanged), make sure that the
1204: \fB\-\-perms\fP option is off and use \fB\-\-chmod=ugo=rwX\fP (which ensures that
1205: all non\-masked bits get enabled). If you\(cq\&d care to make this latter
1206: behavior easier to type, you could define a popt alias for it, such as
1207: putting this line in the file ~/.popt (the following defines the \fB\-Z\fP option,
1208: and includes \-\-no\-g to use the default group of the destination dir):
1209: .IP
1210: .RS
1211: \f(CW rsync alias \-Z \-\-no\-p \-\-no\-g \-\-chmod=ugo=rwX\fP
1212: .RE
1213:
1214: .IP
1215: You could then use this new option in a command such as this one:
1216: .IP
1217: .RS
1218: \f(CW rsync \-avZ src/ dest/\fP
1219: .RE
1220:
1221: .IP
1222: (Caveat: make sure that \fB\-a\fP does not follow \fB\-Z\fP, or it will re\-enable
1223: the two \(dq\&\-\-no\-*\(dq\& options mentioned above.)
1224: .IP
1225: The preservation of the destination\(cq\&s setgid bit on newly\-created
1226: directories when \fB\-\-perms\fP is off was added in rsync 2.6.7. Older rsync
1227: versions erroneously preserved the three special permission bits for
1228: newly\-created files when \fB\-\-perms\fP was off, while overriding the
1229: destination\(cq\&s setgid bit setting on a newly\-created directory. Default ACL
1230: observance was added to the ACL patch for rsync 2.6.7, so older (or
1231: non\-ACL\-enabled) rsyncs use the umask even if default ACLs are present.
1232: (Keep in mind that it is the version of the receiving rsync that affects
1233: these behaviors.)
1234: .IP
1235: .IP "\fB\-E, \-\-executability\fP"
1236: This option causes rsync to preserve the
1237: executability (or non\-executability) of regular files when \fB\-\-perms\fP is
1238: not enabled. A regular file is considered to be executable if at least one
1239: \(cq\&x\(cq\& is turned on in its permissions. When an existing destination file\(cq\&s
1240: executability differs from that of the corresponding source file, rsync
1241: modifies the destination file\(cq\&s permissions as follows:
1242: .IP
1243: .RS
1244: .IP o
1245: To make a file non\-executable, rsync turns off all its \(cq\&x\(cq\&
1246: permissions.
1247: .IP o
1248: To make a file executable, rsync turns on each \(cq\&x\(cq\& permission that
1249: has a corresponding \(cq\&r\(cq\& permission enabled.
1250: .RE
1251:
1252: .IP
1253: If \fB\-\-perms\fP is enabled, this option is ignored.
1254: .IP
1255: .IP "\fB\-A, \-\-acls\fP"
1256: This option causes rsync to update the destination
1257: ACLs to be the same as the source ACLs.
1258: The option also implies \fB\-\-perms\fP.
1259: .IP
1260: The source and destination systems must have compatible ACL entries for this
1261: option to work properly. See the \fB\-\-fake\-super\fP option for a way to backup
1262: and restore ACLs that are not compatible.
1263: .IP
1264: .IP "\fB\-X, \-\-xattrs\fP"
1265: This option causes rsync to update the destination
1266: extended attributes to be the same as the source ones.
1267: .IP
1268: For systems that support extended\-attribute namespaces, a copy being done by a
1269: super\-user copies all namespaces except system.*. A normal user only copies
1270: the user.* namespace. To be able to backup and restore non\-user namespaces as
1271: a normal user, see the \fB\-\-fake\-super\fP option.
1272: .IP
1273: Note that this option does not copy rsyncs special xattr values (e.g. those
1274: used by \fB\-\-fake\-super\fP) unless you repeat the option (e.g. \-XX). This
1275: \(dq\© all xattrs\(dq\& mode cannot be used with \fB\-\-fake\-super\fP.
1276: .IP
1277: .IP "\fB\-\-chmod\fP"
1278: This option tells rsync to apply one or more
1279: comma\-separated \(dq\&chmod\(dq\& modes to the permission of the files in the
1280: transfer. The resulting value is treated as though it were the permissions
1281: that the sending side supplied for the file, which means that this option
1282: can seem to have no effect on existing files if \fB\-\-perms\fP is not enabled.
1283: .IP
1284: In addition to the normal parsing rules specified in the \fBchmod\fP(1)
1285: manpage, you can specify an item that should only apply to a directory by
1286: prefixing it with a \(cq\&D\(cq\&, or specify an item that should only apply to a
1287: file by prefixing it with a \(cq\&F\(cq\&. For example, the following will ensure
1288: that all directories get marked set\-gid, that no files are other\-writable,
1289: that both are user\-writable and group\-writable, and that both have
1290: consistent executability across all bits:
1291: .IP
1292: .RS
1293: \-\-chmod=Dg+s,ug+w,Fo\-w,+X
1294: .RE
1295:
1296: .IP
1.1.1.2 misho 1297: Using octal mode numbers is also allowed:
1298: .IP
1299: .RS
1300: \-\-chmod=D2775,F664
1301: .RE
1302:
1303: .IP
1.1 misho 1304: It is also legal to specify multiple \fB\-\-chmod\fP options, as each
1305: additional option is just appended to the list of changes to make.
1306: .IP
1307: See the \fB\-\-perms\fP and \fB\-\-executability\fP options for how the resulting
1308: permission value can be applied to the files in the transfer.
1309: .IP
1310: .IP "\fB\-o, \-\-owner\fP"
1311: This option causes rsync to set the owner of the
1312: destination file to be the same as the source file, but only if the
1313: receiving rsync is being run as the super\-user (see also the \fB\-\-super\fP
1314: and \fB\-\-fake\-super\fP options).
1315: Without this option, the owner of new and/or transferred files are set to
1316: the invoking user on the receiving side.
1317: .IP
1318: The preservation of ownership will associate matching names by default, but
1319: may fall back to using the ID number in some circumstances (see also the
1320: \fB\-\-numeric\-ids\fP option for a full discussion).
1321: .IP
1322: .IP "\fB\-g, \-\-group\fP"
1323: This option causes rsync to set the group of the
1324: destination file to be the same as the source file. If the receiving
1325: program is not running as the super\-user (or if \fB\-\-no\-super\fP was
1326: specified), only groups that the invoking user on the receiving side
1327: is a member of will be preserved.
1328: Without this option, the group is set to the default group of the invoking
1329: user on the receiving side.
1330: .IP
1331: The preservation of group information will associate matching names by
1332: default, but may fall back to using the ID number in some circumstances
1333: (see also the \fB\-\-numeric\-ids\fP option for a full discussion).
1334: .IP
1335: .IP "\fB\-\-devices\fP"
1336: This option causes rsync to transfer character and
1337: block device files to the remote system to recreate these devices.
1338: This option has no effect if the receiving rsync is not run as the
1339: super\-user (see also the \fB\-\-super\fP and \fB\-\-fake\-super\fP options).
1340: .IP
1341: .IP "\fB\-\-specials\fP"
1342: This option causes rsync to transfer special files
1343: such as named sockets and fifos.
1344: .IP
1345: .IP "\fB\-D\fP"
1346: The \fB\-D\fP option is equivalent to \fB\-\-devices\fP \fB\-\-specials\fP.
1347: .IP
1348: .IP "\fB\-t, \-\-times\fP"
1349: This tells rsync to transfer modification times along
1350: with the files and update them on the remote system. Note that if this
1351: option is not used, the optimization that excludes files that have not been
1352: modified cannot be effective; in other words, a missing \fB\-t\fP or \fB\-a\fP will
1353: cause the next transfer to behave as if it used \fB\-I\fP, causing all files to be
1354: updated (though rsync\(cq\&s delta\-transfer algorithm will make the update fairly efficient
1355: if the files haven\(cq\&t actually changed, you\(cq\&re much better off using \fB\-t\fP).
1356: .IP
1357: .IP "\fB\-O, \-\-omit\-dir\-times\fP"
1358: This tells rsync to omit directories when
1359: it is preserving modification times (see \fB\-\-times\fP). If NFS is sharing
1360: the directories on the receiving side, it is a good idea to use \fB\-O\fP.
1361: This option is inferred if you use \fB\-\-backup\fP without \fB\-\-backup\-dir\fP.
1362: .IP
1.1.1.3 ! misho 1363: This option also has the side\-effect of avoiding early creation of directories
! 1364: in incremental recursion copies. The default \fB\-\-inc\-recursive\fP copying
! 1365: normally does an early\-create pass of all the sub\-directories in a parent
! 1366: directory in order for it to be able to then set the modify time of the parent
! 1367: directory right away (without having to delay that until a bunch of recursive
! 1368: copying has finished). This early\-create idiom is not necessary if directory
! 1369: modify times are not being preserved, so it is skipped. Since early\-create
! 1370: directories don\(cq\&t have accurate mode, mtime, or ownership, the use of this
! 1371: option can help when someone wants to avoid these partially\-finished
! 1372: directories.
! 1373: .IP
1.1.1.2 misho 1374: .IP "\fB\-J, \-\-omit\-link\-times\fP"
1375: This tells rsync to omit symlinks when
1376: it is preserving modification times (see \fB\-\-times\fP).
1377: .IP
1.1 misho 1378: .IP "\fB\-\-super\fP"
1379: This tells the receiving side to attempt super\-user
1380: activities even if the receiving rsync wasn\(cq\&t run by the super\-user. These
1381: activities include: preserving users via the \fB\-\-owner\fP option, preserving
1382: all groups (not just the current user\(cq\&s groups) via the \fB\-\-groups\fP
1383: option, and copying devices via the \fB\-\-devices\fP option. This is useful
1384: for systems that allow such activities without being the super\-user, and
1385: also for ensuring that you will get errors if the receiving side isn\(cq\&t
1386: being run as the super\-user. To turn off super\-user activities, the
1387: super\-user can use \fB\-\-no\-super\fP.
1388: .IP
1389: .IP "\fB\-\-fake\-super\fP"
1390: When this option is enabled, rsync simulates
1391: super\-user activities by saving/restoring the privileged attributes via
1392: special extended attributes that are attached to each file (as needed). This
1393: includes the file\(cq\&s owner and group (if it is not the default), the file\(cq\&s
1394: device info (device & special files are created as empty text files), and
1395: any permission bits that we won\(cq\&t allow to be set on the real file (e.g.
1396: the real file gets u\-s,g\-s,o\-t for safety) or that would limit the owner\(cq\&s
1397: access (since the real super\-user can always access/change a file, the
1398: files we create can always be accessed/changed by the creating user).
1399: This option also handles ACLs (if \fB\-\-acls\fP was specified) and non\-user
1400: extended attributes (if \fB\-\-xattrs\fP was specified).
1401: .IP
1402: This is a good way to backup data without using a super\-user, and to store
1403: ACLs from incompatible systems.
1404: .IP
1405: The \fB\-\-fake\-super\fP option only affects the side where the option is used.
1.1.1.2 misho 1406: To affect the remote side of a remote\-shell connection, use the
1407: \fB\-\-remote\-option\fP (\fB\-M\fP) option:
1.1 misho 1408: .IP
1409: .RS
1.1.1.2 misho 1410: \f(CW rsync \-av \-M\-\-fake\-super /src/ host:/dest/\fP
1.1 misho 1411: .RE
1412:
1413: .IP
1.1.1.2 misho 1414: For a local copy, this option affects both the source and the destination.
1415: If you wish a local copy to enable this option just for the destination
1416: files, specify \fB\-M\-\-fake\-super\fP. If you wish a local copy to enable
1417: this option just for the source files, combine \fB\-\-fake\-super\fP with
1418: \fB\-M\-\-super\fP.
1.1 misho 1419: .IP
1420: This option is overridden by both \fB\-\-super\fP and \fB\-\-no\-super\fP.
1421: .IP
1422: See also the \(dq\&fake super\(dq\& setting in the daemon\(cq\&s rsyncd.conf file.
1423: .IP
1424: .IP "\fB\-S, \-\-sparse\fP"
1425: Try to handle sparse files efficiently so they take
1426: up less space on the destination. Conflicts with \fB\-\-inplace\fP because it\(cq\&s
1427: not possible to overwrite data in a sparse fashion.
1428: .IP
1.1.1.2 misho 1429: .IP "\fB\-\-preallocate\fP"
1430: This tells the receiver to allocate each destination
1431: file to its eventual size before writing data to the file. Rsync will only use
1432: the real filesystem\-level preallocation support provided by Linux\(cq\&s
1433: \fBfallocate\fP(2) system call or Cygwin\(cq\&s \fBposix_fallocate\fP(3), not the slow
1434: glibc implementation that writes a zero byte into each block.
1435: .IP
1436: Without this option, larger files may not be entirely contiguous on the
1437: filesystem, but with this option rsync will probably copy more slowly. If the
1438: destination is not an extent\-supporting filesystem (such as ext4, xfs, NTFS,
1439: etc.), this option may have no positive effect at all.
1440: .IP
1.1 misho 1441: .IP "\fB\-n, \-\-dry\-run\fP"
1442: This makes rsync perform a trial run that doesn\(cq\&t
1443: make any changes (and produces mostly the same output as a real run). It
1444: is most commonly used in combination with the \fB\-v, \-\-verbose\fP and/or
1445: \fB\-i, \-\-itemize\-changes\fP options to see what an rsync command is going
1446: to do before one actually runs it.
1447: .IP
1448: The output of \fB\-\-itemize\-changes\fP is supposed to be exactly the same on a
1449: dry run and a subsequent real run (barring intentional trickery and system
1450: call failures); if it isn\(cq\&t, that\(cq\&s a bug. Other output should be mostly
1451: unchanged, but may differ in some areas. Notably, a dry run does not
1452: send the actual data for file transfers, so \fB\-\-progress\fP has no effect,
1453: the \(dq\&bytes sent\(dq\&, \(dq\&bytes received\(dq\&, \(dq\&literal data\(dq\&, and \(dq\&matched data\(dq\&
1454: statistics are too small, and the \(dq\&speedup\(dq\& value is equivalent to a run
1455: where no file transfers were needed.
1456: .IP
1457: .IP "\fB\-W, \-\-whole\-file\fP"
1458: With this option rsync\(cq\&s delta\-transfer algorithm
1459: is not used and the whole file is sent as\-is instead. The transfer may be
1460: faster if this option is used when the bandwidth between the source and
1461: destination machines is higher than the bandwidth to disk (especially when the
1462: \(dq\&disk\(dq\& is actually a networked filesystem). This is the default when both
1463: the source and destination are specified as local paths, but only if no
1464: batch\-writing option is in effect.
1465: .IP
1466: .IP "\fB\-x, \-\-one\-file\-system\fP"
1467: This tells rsync to avoid crossing a
1468: filesystem boundary when recursing. This does not limit the user\(cq\&s ability
1469: to specify items to copy from multiple filesystems, just rsync\(cq\&s recursion
1470: through the hierarchy of each directory that the user specified, and also
1471: the analogous recursion on the receiving side during deletion. Also keep
1472: in mind that rsync treats a \(dq\&bind\(dq\& mount to the same device as being on the
1473: same filesystem.
1474: .IP
1475: If this option is repeated, rsync omits all mount\-point directories from
1476: the copy. Otherwise, it includes an empty directory at each mount\-point it
1477: encounters (using the attributes of the mounted directory because those of
1478: the underlying mount\-point directory are inaccessible).
1479: .IP
1480: If rsync has been told to collapse symlinks (via \fB\-\-copy\-links\fP or
1481: \fB\-\-copy\-unsafe\-links\fP), a symlink to a directory on another device is
1482: treated like a mount\-point. Symlinks to non\-directories are unaffected
1483: by this option.
1484: .IP
1485: .IP "\fB\-\-existing, \-\-ignore\-non\-existing\fP"
1486: This tells rsync to skip
1487: creating files (including directories) that do not exist
1488: yet on the destination. If this option is
1489: combined with the \fB\-\-ignore\-existing\fP option, no files will be updated
1490: (which can be useful if all you want to do is delete extraneous files).
1491: .IP
1492: This option is a transfer rule, not an exclude, so it doesn\(cq\&t affect the
1493: data that goes into the file\-lists, and thus it doesn\(cq\&t affect deletions.
1494: It just limits the files that the receiver requests to be transferred.
1495: .IP
1496: .IP "\fB\-\-ignore\-existing\fP"
1497: This tells rsync to skip updating files that
1498: already exist on the destination (this does \fInot\fP ignore existing
1499: directories, or nothing would get done). See also \fB\-\-existing\fP.
1500: .IP
1501: This option is a transfer rule, not an exclude, so it doesn\(cq\&t affect the
1502: data that goes into the file\-lists, and thus it doesn\(cq\&t affect deletions.
1503: It just limits the files that the receiver requests to be transferred.
1504: .IP
1505: This option can be useful for those doing backups using the \fB\-\-link\-dest\fP
1506: option when they need to continue a backup run that got interrupted. Since
1507: a \fB\-\-link\-dest\fP run is copied into a new directory hierarchy (when it is
1508: used properly), using \fB\-\-ignore existing\fP will ensure that the
1509: already\-handled files don\(cq\&t get tweaked (which avoids a change in
1510: permissions on the hard\-linked files). This does mean that this option
1511: is only looking at the existing files in the destination hierarchy itself.
1512: .IP
1513: .IP "\fB\-\-remove\-source\-files\fP"
1514: This tells rsync to remove from the sending
1515: side the files (meaning non\-directories) that are a part of the transfer
1516: and have been successfully duplicated on the receiving side.
1517: .IP
1518: Note that you should only use this option on source files that are quiescent.
1519: If you are using this to move files that show up in a particular directory over
1520: to another host, make sure that the finished files get renamed into the source
1521: directory, not directly written into it, so that rsync can\(cq\&t possibly transfer
1522: a file that is not yet fully written. If you can\(cq\&t first write the files into
1523: a different directory, you should use a naming idiom that lets rsync avoid
1524: transferring files that are not yet finished (e.g. name the file \(dq\&foo.new\(dq\& when
1525: it is written, rename it to \(dq\&foo\(dq\& when it is done, and then use the option
1526: \fB\-\-exclude='\&*.new'\&\fP for the rsync transfer).
1527: .IP
1.1.1.2 misho 1528: Starting with 3.1.0, rsync will skip the sender\-side removal (and output an
1529: error) if the file\(cq\&s size or modify time has not stayed unchanged.
1530: .IP
1.1 misho 1531: .IP "\fB\-\-delete\fP"
1532: This tells rsync to delete extraneous files from the
1533: receiving side (ones that aren\(cq\&t on the sending side), but only for the
1534: directories that are being synchronized. You must have asked rsync to
1535: send the whole directory (e.g. \(dq\&dir\(dq\& or \(dq\&dir/\(dq\&) without using a wildcard
1536: for the directory\(cq\&s contents (e.g. \(dq\&dir/*\(dq\&) since the wildcard is expanded
1537: by the shell and rsync thus gets a request to transfer individual files, not
1538: the files\(cq\& parent directory. Files that are excluded from the transfer are
1539: also excluded from being deleted unless you use the \fB\-\-delete\-excluded\fP
1540: option or mark the rules as only matching on the sending side (see the
1541: include/exclude modifiers in the FILTER RULES section).
1542: .IP
1543: Prior to rsync 2.6.7, this option would have no effect unless \fB\-\-recursive\fP
1544: was enabled. Beginning with 2.6.7, deletions will also occur when \fB\-\-dirs\fP
1545: (\fB\-d\fP) is enabled, but only for directories whose contents are being copied.
1546: .IP
1547: This option can be dangerous if used incorrectly! It is a very good idea to
1548: first try a run using the \fB\-\-dry\-run\fP option (\fB\-n\fP) to see what files are
1549: going to be deleted.
1550: .IP
1551: If the sending side detects any I/O errors, then the deletion of any
1552: files at the destination will be automatically disabled. This is to
1553: prevent temporary filesystem failures (such as NFS errors) on the
1554: sending side from causing a massive deletion of files on the
1555: destination. You can override this with the \fB\-\-ignore\-errors\fP option.
1556: .IP
1557: The \fB\-\-delete\fP option may be combined with one of the \-\-delete\-WHEN options
1558: without conflict, as well as \fB\-\-delete\-excluded\fP. However, if none of the
1559: \-\-delete\-WHEN options are specified, rsync will choose the
1560: \fB\-\-delete\-during\fP algorithm when talking to rsync 3.0.0 or newer, and
1561: the \fB\-\-delete\-before\fP algorithm when talking to an older rsync. See also
1562: \fB\-\-delete\-delay\fP and \fB\-\-delete\-after\fP.
1563: .IP
1564: .IP "\fB\-\-delete\-before\fP"
1565: Request that the file\-deletions on the receiving
1566: side be done before the transfer starts.
1567: See \fB\-\-delete\fP (which is implied) for more details on file\-deletion.
1568: .IP
1569: Deleting before the transfer is helpful if the filesystem is tight for space
1570: and removing extraneous files would help to make the transfer possible.
1571: However, it does introduce a delay before the start of the transfer,
1572: and this delay might cause the transfer to timeout (if \fB\-\-timeout\fP was
1573: specified). It also forces rsync to use the old, non\-incremental recursion
1574: algorithm that requires rsync to scan all the files in the transfer into
1575: memory at once (see \fB\-\-recursive\fP).
1576: .IP
1577: .IP "\fB\-\-delete\-during, \-\-del\fP"
1578: Request that the file\-deletions on the
1579: receiving side be done incrementally as the transfer happens. The
1580: per\-directory delete scan is done right before each directory is checked
1581: for updates, so it behaves like a more efficient \fB\-\-delete\-before\fP,
1582: including doing the deletions prior to any per\-directory filter files
1583: being updated. This option was first added in rsync version 2.6.4.
1584: See \fB\-\-delete\fP (which is implied) for more details on file\-deletion.
1585: .IP
1586: .IP "\fB\-\-delete\-delay\fP"
1587: Request that the file\-deletions on the receiving
1588: side be computed during the transfer (like \fB\-\-delete\-during\fP), and then
1589: removed after the transfer completes. This is useful when combined with
1590: \fB\-\-delay\-updates\fP and/or \fB\-\-fuzzy\fP, and is more efficient than using
1591: \fB\-\-delete\-after\fP (but can behave differently, since \fB\-\-delete\-after\fP
1592: computes the deletions in a separate pass after all updates are done).
1593: If the number of removed files overflows an internal buffer, a
1594: temporary file will be created on the receiving side to hold the names (it
1595: is removed while open, so you shouldn\(cq\&t see it during the transfer). If
1596: the creation of the temporary file fails, rsync will try to fall back to
1597: using \fB\-\-delete\-after\fP (which it cannot do if \fB\-\-recursive\fP is doing an
1598: incremental scan).
1599: See \fB\-\-delete\fP (which is implied) for more details on file\-deletion.
1600: .IP
1601: .IP "\fB\-\-delete\-after\fP"
1602: Request that the file\-deletions on the receiving
1603: side be done after the transfer has completed. This is useful if you
1604: are sending new per\-directory merge files as a part of the transfer and
1605: you want their exclusions to take effect for the delete phase of the
1606: current transfer. It also forces rsync to use the old, non\-incremental
1607: recursion algorithm that requires rsync to scan all the files in the
1608: transfer into memory at once (see \fB\-\-recursive\fP).
1609: See \fB\-\-delete\fP (which is implied) for more details on file\-deletion.
1610: .IP
1611: .IP "\fB\-\-delete\-excluded\fP"
1612: In addition to deleting the files on the
1613: receiving side that are not on the sending side, this tells rsync to also
1614: delete any files on the receiving side that are excluded (see \fB\-\-exclude\fP).
1615: See the FILTER RULES section for a way to make individual exclusions behave
1616: this way on the receiver, and for a way to protect files from
1617: \fB\-\-delete\-excluded\fP.
1618: See \fB\-\-delete\fP (which is implied) for more details on file\-deletion.
1619: .IP
1.1.1.2 misho 1620: .IP "\fB\-\-ignore\-missing\-args\fP"
1621: When rsync is first processing the explicitly
1622: requested source files (e.g. command\-line arguments or \fB\-\-files\-from\fP
1623: entries), it is normally an error if the file cannot be found. This option
1624: suppresses that error, and does not try to transfer the file. This does not
1625: affect subsequent vanished\-file errors if a file was initially found to be
1626: present and later is no longer there.
1627: .IP
1628: .IP "\fB\-\-delete\-missing\-args\fP"
1629: This option takes the behavior of (the implied)
1630: \fB\-\-ignore\-missing\-args\fP option a step farther: each missing arg will become
1631: a deletion request of the corresponding destination file on the receiving side
1632: (should it exist). If the destination file is a non\-empty directory, it will
1633: only be successfully deleted if \-\-force or \-\-delete are in effect. Other than
1634: that, this option is independent of any other type of delete processing.
1635: .IP
1636: The missing source files are represented by special file\-list entries which
1637: display as a \(dq\&*missing\(dq\& entry in the \fB\-\-list\-only\fP output.
1638: .IP
1.1 misho 1639: .IP "\fB\-\-ignore\-errors\fP"
1640: Tells \fB\-\-delete\fP to go ahead and delete files
1641: even when there are I/O errors.
1642: .IP
1643: .IP "\fB\-\-force\fP"
1644: This option tells rsync to delete a non\-empty directory
1645: when it is to be replaced by a non\-directory. This is only relevant if
1646: deletions are not active (see \fB\-\-delete\fP for details).
1647: .IP
1648: Note for older rsync versions: \fB\-\-force\fP used to still be required when
1649: using \fB\-\-delete\-after\fP, and it used to be non\-functional unless the
1650: \fB\-\-recursive\fP option was also enabled.
1651: .IP
1652: .IP "\fB\-\-max\-delete=NUM\fP"
1653: This tells rsync not to delete more than NUM
1.1.1.2 misho 1654: files or directories. If that limit is exceeded, all further deletions are
1655: skipped through the end of the transfer. At the end, rsync outputs a warning
1656: (including a count of the skipped deletions) and exits with an error code
1657: of 25 (unless some more important error condition also occurred).
1.1 misho 1658: .IP
1.1.1.2 misho 1659: Beginning with version 3.0.0, you may specify \fB\-\-max\-delete=0\fP to be warned
1.1 misho 1660: about any extraneous files in the destination without removing any of them.
1661: Older clients interpreted this as \(dq\&unlimited\(dq\&, so if you don\(cq\&t know what
1662: version the client is, you can use the less obvious \fB\-\-max\-delete=\-1\fP as
1663: a backward\-compatible way to specify that no deletions be allowed (though
1.1.1.2 misho 1664: really old versions didn\(cq\&t warn when the limit was exceeded).
1.1 misho 1665: .IP
1666: .IP "\fB\-\-max\-size=SIZE\fP"
1667: This tells rsync to avoid transferring any
1668: file that is larger than the specified SIZE. The SIZE value can be
1669: suffixed with a string to indicate a size multiplier, and
1670: may be a fractional value (e.g. \(dq\&\fB\-\-max\-size=1.5m\fP\(dq\&).
1671: .IP
1672: This option is a transfer rule, not an exclude, so it doesn\(cq\&t affect the
1673: data that goes into the file\-lists, and thus it doesn\(cq\&t affect deletions.
1674: It just limits the files that the receiver requests to be transferred.
1675: .IP
1676: The suffixes are as follows: \(dq\&K\(dq\& (or \(dq\&KiB\(dq\&) is a kibibyte (1024),
1677: \(dq\&M\(dq\& (or \(dq\&MiB\(dq\&) is a mebibyte (1024*1024), and \(dq\&G\(dq\& (or \(dq\&GiB\(dq\&) is a
1678: gibibyte (1024*1024*1024).
1679: If you want the multiplier to be 1000 instead of 1024, use \(dq\&KB\(dq\&,
1680: \(dq\&MB\(dq\&, or \(dq\&GB\(dq\&. (Note: lower\-case is also accepted for all values.)
1681: Finally, if the suffix ends in either \(dq\&+1\(dq\& or \(dq\&\-1\(dq\&, the value will
1682: be offset by one byte in the indicated direction.
1683: .IP
1684: Examples: \-\-max\-size=1.5mb\-1 is 1499999 bytes, and \-\-max\-size=2g+1 is
1685: 2147483649 bytes.
1686: .IP
1.1.1.2 misho 1687: Note that rsync versions prior to 3.1.0 did not allow \fB\-\-max\-size=0\fP.
1688: .IP
1.1 misho 1689: .IP "\fB\-\-min\-size=SIZE\fP"
1690: This tells rsync to avoid transferring any
1691: file that is smaller than the specified SIZE, which can help in not
1692: transferring small, junk files.
1693: See the \fB\-\-max\-size\fP option for a description of SIZE and other information.
1694: .IP
1.1.1.2 misho 1695: Note that rsync versions prior to 3.1.0 did not allow \fB\-\-min\-size=0\fP.
1696: .IP
1.1 misho 1697: .IP "\fB\-B, \-\-block\-size=BLOCKSIZE\fP"
1698: This forces the block size used in
1699: rsync\(cq\&s delta\-transfer algorithm to a fixed value. It is normally selected based on
1700: the size of each file being updated. See the technical report for details.
1701: .IP
1702: .IP "\fB\-e, \-\-rsh=COMMAND\fP"
1703: This option allows you to choose an alternative
1704: remote shell program to use for communication between the local and
1705: remote copies of rsync. Typically, rsync is configured to use ssh by
1706: default, but you may prefer to use rsh on a local network.
1707: .IP
1708: If this option is used with \fB[user@]host::module/path\fP, then the
1709: remote shell \fICOMMAND\fP will be used to run an rsync daemon on the
1710: remote host, and all data will be transmitted through that remote
1711: shell connection, rather than through a direct socket connection to a
1712: running rsync daemon on the remote host. See the section \(dq\&USING
1713: RSYNC\-DAEMON FEATURES VIA A REMOTE\-SHELL CONNECTION\(dq\& above.
1714: .IP
1715: Command\-line arguments are permitted in COMMAND provided that COMMAND is
1716: presented to rsync as a single argument. You must use spaces (not tabs
1717: or other whitespace) to separate the command and args from each other,
1718: and you can use single\- and/or double\-quotes to preserve spaces in an
1719: argument (but not backslashes). Note that doubling a single\-quote
1720: inside a single\-quoted string gives you a single\-quote; likewise for
1721: double\-quotes (though you need to pay attention to which quotes your
1722: shell is parsing and which quotes rsync is parsing). Some examples:
1723: .IP
1724: .RS
1725: \f(CW \-e '\&ssh \-p 2234'\&\fP
1726: .br
1727: \f(CW \-e '\&ssh \-o \(dq\&ProxyCommand nohup ssh firewall nc \-w1 %h %p\(dq\&'\&\fP
1728: .br
1729: .RE
1730:
1731: .IP
1732: (Note that ssh users can alternately customize site\-specific connect
1733: options in their .ssh/config file.)
1734: .IP
1735: You can also choose the remote shell program using the RSYNC_RSH
1736: environment variable, which accepts the same range of values as \fB\-e\fP.
1737: .IP
1738: See also the \fB\-\-blocking\-io\fP option which is affected by this option.
1739: .IP
1740: .IP "\fB\-\-rsync\-path=PROGRAM\fP"
1741: Use this to specify what program is to be run
1742: on the remote machine to start\-up rsync. Often used when rsync is not in
1743: the default remote\-shell\(cq\&s path (e.g. \-\-rsync\-path=/usr/local/bin/rsync).
1744: Note that PROGRAM is run with the help of a shell, so it can be any
1745: program, script, or command sequence you\(cq\&d care to run, so long as it does
1746: not corrupt the standard\-in & standard\-out that rsync is using to
1747: communicate.
1748: .IP
1749: One tricky example is to set a different default directory on the remote
1750: machine for use with the \fB\-\-relative\fP option. For instance:
1751: .IP
1752: .RS
1753: \f(CW rsync \-avR \-\-rsync\-path=\(dq\&cd /a/b && rsync\(dq\& host:c/d /e/\fP
1754: .RE
1755:
1756: .IP
1.1.1.2 misho 1757: .IP "\fB\-M, \-\-remote\-option=OPTION\fP"
1758: This option is used for more advanced
1759: situations where you want certain effects to be limited to one side of the
1760: transfer only. For instance, if you want to pass \fB\-\-log\-file=FILE\fP and
1761: \fB\-\-fake\-super\fP to the remote system, specify it like this:
1762: .IP
1763: .RS
1764: \f(CW rsync \-av \-M \-\-log\-file=foo \-M\-\-fake\-super src/ dest/\fP
1765: .RE
1766:
1767: .IP
1768: If you want to have an option affect only the local side of a transfer when
1769: it normally affects both sides, send its negation to the remote side. Like
1770: this:
1771: .IP
1772: .RS
1773: \f(CW rsync \-av \-x \-M\-\-no\-x src/ dest/\fP
1774: .RE
1775:
1776: .IP
1777: Be cautious using this, as it is possible to toggle an option that will cause
1778: rsync to have a different idea about what data to expect next over the socket,
1779: and that will make it fail in a cryptic fashion.
1780: .IP
1781: Note that it is best to use a separate \fB\-\-remote\-option\fP for each option you
1782: want to pass. This makes your useage compatible with the \fB\-\-protect\-args\fP
1783: option. If that option is off, any spaces in your remote options will be split
1784: by the remote shell unless you take steps to protect them.
1785: .IP
1786: When performing a local transfer, the \(dq\&local\(dq\& side is the sender and the
1787: \(dq\&remote\(dq\& side is the receiver.
1788: .IP
1789: Note some versions of the popt option\-parsing library have a bug in them that
1790: prevents you from using an adjacent arg with an equal in it next to a short
1791: option letter (e.g. \f(CW\-M\-\-log\-file=/tmp/foo\fP. If this bug affects your
1792: version of popt, you can use the version of popt that is included with rsync.
1793: .IP
1.1 misho 1794: .IP "\fB\-C, \-\-cvs\-exclude\fP"
1795: This is a useful shorthand for excluding a
1796: broad range of files that you often don\(cq\&t want to transfer between
1797: systems. It uses a similar algorithm to CVS to determine if
1798: a file should be ignored.
1799: .IP
1800: The exclude list is initialized to exclude the following items (these
1801: initial items are marked as perishable \-\- see the FILTER RULES section):
1802: .IP
1803: .RS
1804: .RS
1805: \f(CWRCS SCCS CVS CVS.adm RCSLOG cvslog.* tags TAGS .make.state
1806: \&.nse_depinfo *~ #* .#* ,* _$* *$ *.old *.bak *.BAK *.orig *.rej .del\-*
1807: *.a *.olb *.o *.obj *.so *.exe *.Z *.elc *.ln core .svn/ .git/ .hg/ .bzr/\fP
1808: .RE
1809: .RE
1810:
1811: .IP
1812: then, files listed in a $HOME/.cvsignore are added to the list and any
1813: files listed in the CVSIGNORE environment variable (all cvsignore names
1814: are delimited by whitespace).
1815: .IP
1816: Finally, any file is ignored if it is in the same directory as a
1817: \&.cvsignore file and matches one of the patterns listed therein. Unlike
1818: rsync\(cq\&s filter/exclude files, these patterns are split on whitespace.
1819: See the \fBcvs\fP(1) manual for more information.
1820: .IP
1821: If you\(cq\&re combining \fB\-C\fP with your own \fB\-\-filter\fP rules, you should
1822: note that these CVS excludes are appended at the end of your own rules,
1823: regardless of where the \fB\-C\fP was placed on the command\-line. This makes them
1824: a lower priority than any rules you specified explicitly. If you want to
1825: control where these CVS excludes get inserted into your filter rules, you
1826: should omit the \fB\-C\fP as a command\-line option and use a combination of
1827: \fB\-\-filter=:C\fP and \fB\-\-filter=\-C\fP (either on your command\-line or by
1828: putting the \(dq\&:C\(dq\& and \(dq\&\-C\(dq\& rules into a filter file with your other rules).
1829: The first option turns on the per\-directory scanning for the .cvsignore
1830: file. The second option does a one\-time import of the CVS excludes
1831: mentioned above.
1832: .IP
1833: .IP "\fB\-f, \-\-filter=RULE\fP"
1834: This option allows you to add rules to selectively
1835: exclude certain files from the list of files to be transferred. This is
1836: most useful in combination with a recursive transfer.
1837: .IP
1838: You may use as many \fB\-\-filter\fP options on the command line as you like
1839: to build up the list of files to exclude. If the filter contains whitespace,
1840: be sure to quote it so that the shell gives the rule to rsync as a single
1841: argument. The text below also mentions that you can use an underscore to
1842: replace the space that separates a rule from its arg.
1843: .IP
1844: See the FILTER RULES section for detailed information on this option.
1845: .IP
1846: .IP "\fB\-F\fP"
1847: The \fB\-F\fP option is a shorthand for adding two \fB\-\-filter\fP rules to
1848: your command. The first time it is used is a shorthand for this rule:
1849: .IP
1850: .RS
1851: \f(CW \-\-filter='\&dir\-merge /.rsync\-filter'\&\fP
1852: .RE
1853:
1854: .IP
1855: This tells rsync to look for per\-directory .rsync\-filter files that have
1856: been sprinkled through the hierarchy and use their rules to filter the
1857: files in the transfer. If \fB\-F\fP is repeated, it is a shorthand for this
1858: rule:
1859: .IP
1860: .RS
1861: \f(CW \-\-filter='\&exclude .rsync\-filter'\&\fP
1862: .RE
1863:
1864: .IP
1865: This filters out the .rsync\-filter files themselves from the transfer.
1866: .IP
1867: See the FILTER RULES section for detailed information on how these options
1868: work.
1869: .IP
1870: .IP "\fB\-\-exclude=PATTERN\fP"
1871: This option is a simplified form of the
1872: \fB\-\-filter\fP option that defaults to an exclude rule and does not allow
1873: the full rule\-parsing syntax of normal filter rules.
1874: .IP
1875: See the FILTER RULES section for detailed information on this option.
1876: .IP
1877: .IP "\fB\-\-exclude\-from=FILE\fP"
1878: This option is related to the \fB\-\-exclude\fP
1879: option, but it specifies a FILE that contains exclude patterns (one per line).
1880: Blank lines in the file and lines starting with \(cq\&;\(cq\& or \(cq\&#\(cq\& are ignored.
1881: If \fIFILE\fP is \fB\-\fP, the list will be read from standard input.
1882: .IP
1883: .IP "\fB\-\-include=PATTERN\fP"
1884: This option is a simplified form of the
1885: \fB\-\-filter\fP option that defaults to an include rule and does not allow
1886: the full rule\-parsing syntax of normal filter rules.
1887: .IP
1888: See the FILTER RULES section for detailed information on this option.
1889: .IP
1890: .IP "\fB\-\-include\-from=FILE\fP"
1891: This option is related to the \fB\-\-include\fP
1892: option, but it specifies a FILE that contains include patterns (one per line).
1893: Blank lines in the file and lines starting with \(cq\&;\(cq\& or \(cq\&#\(cq\& are ignored.
1894: If \fIFILE\fP is \fB\-\fP, the list will be read from standard input.
1895: .IP
1896: .IP "\fB\-\-files\-from=FILE\fP"
1897: Using this option allows you to specify the
1898: exact list of files to transfer (as read from the specified FILE or \fB\-\fP
1899: for standard input). It also tweaks the default behavior of rsync to make
1900: transferring just the specified files and directories easier:
1901: .IP
1902: .RS
1903: .IP o
1904: The \fB\-\-relative\fP (\fB\-R\fP) option is implied, which preserves the path
1905: information that is specified for each item in the file (use
1906: \fB\-\-no\-relative\fP or \fB\-\-no\-R\fP if you want to turn that off).
1907: .IP o
1908: The \fB\-\-dirs\fP (\fB\-d\fP) option is implied, which will create directories
1909: specified in the list on the destination rather than noisily skipping
1910: them (use \fB\-\-no\-dirs\fP or \fB\-\-no\-d\fP if you want to turn that off).
1911: .IP o
1912: The \fB\-\-archive\fP (\fB\-a\fP) option\(cq\&s behavior does not imply \fB\-\-recursive\fP
1913: (\fB\-r\fP), so specify it explicitly, if you want it.
1914: .IP o
1915: These side\-effects change the default state of rsync, so the position
1916: of the \fB\-\-files\-from\fP option on the command\-line has no bearing on how
1917: other options are parsed (e.g. \fB\-a\fP works the same before or after
1918: \fB\-\-files\-from\fP, as does \fB\-\-no\-R\fP and all other options).
1919: .RE
1920:
1921: .IP
1922: The filenames that are read from the FILE are all relative to the
1923: source dir \-\- any leading slashes are removed and no \(dq\&..\(dq\& references are
1924: allowed to go higher than the source dir. For example, take this
1925: command:
1926: .IP
1927: .RS
1928: \f(CW rsync \-a \-\-files\-from=/tmp/foo /usr remote:/backup\fP
1929: .RE
1930:
1931: .IP
1932: If /tmp/foo contains the string \(dq\&bin\(dq\& (or even \(dq\&/bin\(dq\&), the /usr/bin
1933: directory will be created as /backup/bin on the remote host. If it
1934: contains \(dq\&bin/\(dq\& (note the trailing slash), the immediate contents of
1935: the directory would also be sent (without needing to be explicitly
1936: mentioned in the file \-\- this began in version 2.6.4). In both cases,
1937: if the \fB\-r\fP option was enabled, that dir\(cq\&s entire hierarchy would
1938: also be transferred (keep in mind that \fB\-r\fP needs to be specified
1939: explicitly with \fB\-\-files\-from\fP, since it is not implied by \fB\-a\fP).
1940: Also note
1941: that the effect of the (enabled by default) \fB\-\-relative\fP option is to
1942: duplicate only the path info that is read from the file \-\- it does not
1943: force the duplication of the source\-spec path (/usr in this case).
1944: .IP
1945: In addition, the \fB\-\-files\-from\fP file can be read from the remote host
1946: instead of the local host if you specify a \(dq\&host:\(dq\& in front of the file
1947: (the host must match one end of the transfer). As a short\-cut, you can
1948: specify just a prefix of \(dq\&:\(dq\& to mean \(dq\&use the remote end of the
1949: transfer\(dq\&. For example:
1950: .IP
1951: .RS
1952: \f(CW rsync \-a \-\-files\-from=:/path/file\-list src:/ /tmp/copy\fP
1953: .RE
1954:
1955: .IP
1956: This would copy all the files specified in the /path/file\-list file that
1957: was located on the remote \(dq\&src\(dq\& host.
1958: .IP
1959: If the \fB\-\-iconv\fP and \fB\-\-protect\-args\fP options are specified and the
1960: \fB\-\-files\-from\fP filenames are being sent from one host to another, the
1961: filenames will be translated from the sending host\(cq\&s charset to the
1962: receiving host\(cq\&s charset.
1963: .IP
1964: NOTE: sorting the list of files in the \-\-files\-from input helps rsync to be
1965: more efficient, as it will avoid re\-visiting the path elements that are shared
1966: between adjacent entries. If the input is not sorted, some path elements
1967: (implied directories) may end up being scanned multiple times, and rsync will
1968: eventually unduplicate them after they get turned into file\-list elements.
1969: .IP
1970: .IP "\fB\-0, \-\-from0\fP"
1971: This tells rsync that the rules/filenames it reads from a
1972: file are terminated by a null (\(cq\&\e0\(cq\&) character, not a NL, CR, or CR+LF.
1973: This affects \fB\-\-exclude\-from\fP, \fB\-\-include\-from\fP, \fB\-\-files\-from\fP, and any
1974: merged files specified in a \fB\-\-filter\fP rule.
1975: It does not affect \fB\-\-cvs\-exclude\fP (since all names read from a .cvsignore
1976: file are split on whitespace).
1977: .IP
1978: .IP "\fB\-s, \-\-protect\-args\fP"
1979: This option sends all filenames and most options to
1980: the remote rsync without allowing the remote shell to interpret them. This
1981: means that spaces are not split in names, and any non\-wildcard special
1982: characters are not translated (such as ~, $, ;, &, etc.). Wildcards are
1983: expanded on the remote host by rsync (instead of the shell doing it).
1984: .IP
1985: If you use this option with \fB\-\-iconv\fP, the args related to the remote
1986: side will also be translated
1987: from the local to the remote character\-set. The translation happens before
1988: wild\-cards are expanded. See also the \fB\-\-files\-from\fP option.
1989: .IP
1.1.1.2 misho 1990: You may also control this option via the RSYNC_PROTECT_ARGS environment
1991: variable. If this variable has a non\-zero value, this option will be enabled
1992: by default, otherwise it will be disabled by default. Either state is
1993: overridden by a manually specified positive or negative version of this option
1994: (note that \fB\-\-no\-s\fP and \fB\-\-no\-protect\-args\fP are the negative versions).
1995: Since this option was first introduced in 3.0.0, you\(cq\&ll need to make sure it\(cq\&s
1996: disabled if you ever need to interact with a remote rsync that is older than
1997: that.
1998: .IP
1999: Rsync can also be configured (at build time) to have this option enabled by
2000: default (with is overridden by both the environment and the command\-line).
2001: This option will eventually become a new default setting at some
2002: as\-yet\-undetermined point in the future.
2003: .IP
1.1 misho 2004: .IP "\fB\-T, \-\-temp\-dir=DIR\fP"
2005: This option instructs rsync to use DIR as a
2006: scratch directory when creating temporary copies of the files transferred
2007: on the receiving side. The default behavior is to create each temporary
2008: file in the same directory as the associated destination file.
1.1.1.3 ! misho 2009: Beginning with rsync 3.1.1, the temp\-file names inside the specified DIR will
! 2010: not be prefixed with an extra dot (though they will still have a random suffix
! 2011: added).
1.1 misho 2012: .IP
2013: This option is most often used when the receiving disk partition does not
2014: have enough free space to hold a copy of the largest file in the transfer.
2015: In this case (i.e. when the scratch directory is on a different disk
2016: partition), rsync will not be able to rename each received temporary file
2017: over the top of the associated destination file, but instead must copy it
2018: into place. Rsync does this by copying the file over the top of the
2019: destination file, which means that the destination file will contain
2020: truncated data during this copy. If this were not done this way (even if
2021: the destination file were first removed, the data locally copied to a
2022: temporary file in the destination directory, and then renamed into place)
2023: it would be possible for the old file to continue taking up disk space (if
2024: someone had it open), and thus there might not be enough room to fit the
2025: new version on the disk at the same time.
2026: .IP
2027: If you are using this option for reasons other than a shortage of disk
2028: space, you may wish to combine it with the \fB\-\-delay\-updates\fP option,
2029: which will ensure that all copied files get put into subdirectories in the
2030: destination hierarchy, awaiting the end of the transfer. If you don\(cq\&t
2031: have enough room to duplicate all the arriving files on the destination
2032: partition, another way to tell rsync that you aren\(cq\&t overly concerned
2033: about disk space is to use the \fB\-\-partial\-dir\fP option with a relative
2034: path; because this tells rsync that it is OK to stash off a copy of a
2035: single file in a subdir in the destination hierarchy, rsync will use the
2036: partial\-dir as a staging area to bring over the copied file, and then
2037: rename it into place from there. (Specifying a \fB\-\-partial\-dir\fP with
2038: an absolute path does not have this side\-effect.)
2039: .IP
2040: .IP "\fB\-y, \-\-fuzzy\fP"
2041: This option tells rsync that it should look for a
2042: basis file for any destination file that is missing. The current algorithm
2043: looks in the same directory as the destination file for either a file that
2044: has an identical size and modified\-time, or a similarly\-named file. If
2045: found, rsync uses the fuzzy basis file to try to speed up the transfer.
2046: .IP
1.1.1.2 misho 2047: If the option is repeated, the fuzzy scan will also be done in any matching
2048: alternate destination directories that are specified via \fB\-\-compare\-dest\fP,
2049: \fB\-\-copy\-dest\fP, or \fB\-\-link\-dest\fP.
2050: .IP
1.1 misho 2051: Note that the use of the \fB\-\-delete\fP option might get rid of any potential
2052: fuzzy\-match files, so either use \fB\-\-delete\-after\fP or specify some
2053: filename exclusions if you need to prevent this.
2054: .IP
2055: .IP "\fB\-\-compare\-dest=DIR\fP"
2056: This option instructs rsync to use \fIDIR\fP on
2057: the destination machine as an additional hierarchy to compare destination
2058: files against doing transfers (if the files are missing in the destination
2059: directory). If a file is found in \fIDIR\fP that is identical to the
2060: sender\(cq\&s file, the file will NOT be transferred to the destination
2061: directory. This is useful for creating a sparse backup of just files that
2062: have changed from an earlier backup.
1.1.1.2 misho 2063: This option is typically used to copy into an empty (or newly created)
2064: directory.
1.1 misho 2065: .IP
2066: Beginning in version 2.6.4, multiple \fB\-\-compare\-dest\fP directories may be
2067: provided, which will cause rsync to search the list in the order specified
2068: for an exact match.
2069: If a match is found that differs only in attributes, a local copy is made
2070: and the attributes updated.
2071: If a match is not found, a basis file from one of the \fIDIR\fPs will be
2072: selected to try to speed up the transfer.
2073: .IP
2074: If \fIDIR\fP is a relative path, it is relative to the destination directory.
2075: See also \fB\-\-copy\-dest\fP and \fB\-\-link\-dest\fP.
2076: .IP
1.1.1.2 misho 2077: NOTE: beginning with version 3.1.0, rsync will remove a file from a non\-empty
2078: destination hierarchy if an exact match is found in one of the compare\-dest
2079: hierarchies (making the end result more closely match a fresh copy).
2080: .IP
1.1 misho 2081: .IP "\fB\-\-copy\-dest=DIR\fP"
2082: This option behaves like \fB\-\-compare\-dest\fP, but
2083: rsync will also copy unchanged files found in \fIDIR\fP to the destination
2084: directory using a local copy.
2085: This is useful for doing transfers to a new destination while leaving
2086: existing files intact, and then doing a flash\-cutover when all files have
2087: been successfully transferred.
2088: .IP
2089: Multiple \fB\-\-copy\-dest\fP directories may be provided, which will cause
2090: rsync to search the list in the order specified for an unchanged file.
2091: If a match is not found, a basis file from one of the \fIDIR\fPs will be
2092: selected to try to speed up the transfer.
2093: .IP
2094: If \fIDIR\fP is a relative path, it is relative to the destination directory.
2095: See also \fB\-\-compare\-dest\fP and \fB\-\-link\-dest\fP.
2096: .IP
2097: .IP "\fB\-\-link\-dest=DIR\fP"
2098: This option behaves like \fB\-\-copy\-dest\fP, but
2099: unchanged files are hard linked from \fIDIR\fP to the destination directory.
2100: The files must be identical in all preserved attributes (e.g. permissions,
2101: possibly ownership) in order for the files to be linked together.
2102: An example:
2103: .IP
2104: .RS
2105: \f(CW rsync \-av \-\-link\-dest=$PWD/prior_dir host:src_dir/ new_dir/\fP
2106: .RE
2107:
2108: .IP
2109: If file\(cq\&s aren\(cq\&t linking, double\-check their attributes. Also check if some
2110: attributes are getting forced outside of rsync\(cq\&s control, such a mount option
2111: that squishes root to a single user, or mounts a removable drive with generic
2112: ownership (such as OS X\(cq\&s \(dq\&Ignore ownership on this volume\(dq\& option).
2113: .IP
2114: Beginning in version 2.6.4, multiple \fB\-\-link\-dest\fP directories may be
2115: provided, which will cause rsync to search the list in the order specified
2116: for an exact match.
2117: If a match is found that differs only in attributes, a local copy is made
2118: and the attributes updated.
2119: If a match is not found, a basis file from one of the \fIDIR\fPs will be
2120: selected to try to speed up the transfer.
2121: .IP
2122: This option works best when copying into an empty destination hierarchy, as
1.1.1.2 misho 2123: existing files may get their attributes tweaked, and that can affect alternate
2124: destination files via hard\-links. Also, itemizing of changes can get a bit
2125: muddled. Note that prior to version 3.1.0, an alternate\-directory exact match
2126: would never be found (nor linked into the destination) when a destination file
2127: already exists.
1.1 misho 2128: .IP
2129: Note that if you combine this option with \fB\-\-ignore\-times\fP, rsync will not
2130: link any files together because it only links identical files together as a
2131: substitute for transferring the file, never as an additional check after the
2132: file is updated.
2133: .IP
2134: If \fIDIR\fP is a relative path, it is relative to the destination directory.
2135: See also \fB\-\-compare\-dest\fP and \fB\-\-copy\-dest\fP.
2136: .IP
2137: Note that rsync versions prior to 2.6.1 had a bug that could prevent
2138: \fB\-\-link\-dest\fP from working properly for a non\-super\-user when \fB\-o\fP was
2139: specified (or implied by \fB\-a\fP). You can work\-around this bug by avoiding
2140: the \fB\-o\fP option when sending to an old rsync.
2141: .IP
2142: .IP "\fB\-z, \-\-compress\fP"
2143: With this option, rsync compresses the file data
2144: as it is sent to the destination machine, which reduces the amount of data
2145: being transmitted \-\- something that is useful over a slow connection.
2146: .IP
2147: Note that this option typically achieves better compression ratios than can
2148: be achieved by using a compressing remote shell or a compressing transport
2149: because it takes advantage of the implicit information in the matching data
1.1.1.3 ! misho 2150: blocks that are not explicitly sent over the connection. This matching\-data
! 2151: compression comes at a cost of CPU, though, and can be disabled by repeating
! 2152: the \fB\-z\fP option, but only if both sides are at least version 3.1.1.
! 2153: .IP
! 2154: Note that if your version of rsync was compiled with an external zlib (instead
! 2155: of the zlib that comes packaged with rsync) then it will not support the
! 2156: old\-style compression, only the new\-style (repeated\-option) compression. In
! 2157: the future this new\-style compression will likely become the default.
! 2158: .IP
! 2159: The client rsync requests new\-style compression on the server via the
! 2160: \fB\-\-new\-compress\fP option, so if you see that option rejected it means that
! 2161: the server is not new enough to support \fB\-zz\fP. Rsync also accepts the
! 2162: \fB\-\-old\-compress\fP option for a future time when new\-style compression
! 2163: becomes the default.
1.1 misho 2164: .IP
2165: See the \fB\-\-skip\-compress\fP option for the default list of file suffixes
2166: that will not be compressed.
2167: .IP
2168: .IP "\fB\-\-compress\-level=NUM\fP"
2169: Explicitly set the compression level to use
2170: (see \fB\-\-compress\fP) instead of letting it default. If NUM is non\-zero,
2171: the \fB\-\-compress\fP option is implied.
2172: .IP
2173: .IP "\fB\-\-skip\-compress=LIST\fP"
2174: Override the list of file suffixes that will
2175: not be compressed. The \fBLIST\fP should be one or more file suffixes
2176: (without the dot) separated by slashes (/).
2177: .IP
2178: You may specify an empty string to indicate that no file should be skipped.
2179: .IP
2180: Simple character\-class matching is supported: each must consist of a list
2181: of letters inside the square brackets (e.g. no special classes, such as
2182: \(dq\&[:alpha:]\(dq\&, are supported, and \(cq\&\-\(cq\& has no special meaning).
2183: .IP
2184: The characters asterisk (*) and question\-mark (?) have no special meaning.
2185: .IP
2186: Here\(cq\&s an example that specifies 6 suffixes to skip (since 1 of the 5 rules
2187: matches 2 suffixes):
2188: .IP
2189: .nf
2190: \-\-skip\-compress=gz/jpg/mp[34]/7z/bz2
2191: .fi
2192:
2193: .IP
2194: The default list of suffixes that will not be compressed is this (in this
2195: version of rsync):
2196: .IP
2197: \fB7z\fP
1.1.1.2 misho 2198: \fBace\fP
1.1 misho 2199: \fBavi\fP
2200: \fBbz2\fP
2201: \fBdeb\fP
1.1.1.2 misho 2202: \fBgpg\fP
1.1 misho 2203: \fBgz\fP
2204: \fBiso\fP
2205: \fBjpeg\fP
2206: \fBjpg\fP
1.1.1.2 misho 2207: \fBlz\fP
2208: \fBlzma\fP
2209: \fBlzo\fP
1.1 misho 2210: \fBmov\fP
2211: \fBmp3\fP
2212: \fBmp4\fP
2213: \fBogg\fP
1.1.1.2 misho 2214: \fBpng\fP
2215: \fBrar\fP
1.1 misho 2216: \fBrpm\fP
1.1.1.2 misho 2217: \fBrzip\fP
1.1 misho 2218: \fBtbz\fP
2219: \fBtgz\fP
1.1.1.2 misho 2220: \fBtlz\fP
2221: \fBtxz\fP
2222: \fBxz\fP
1.1 misho 2223: \fBz\fP
2224: \fBzip\fP
2225: .IP
2226: This list will be replaced by your \fB\-\-skip\-compress\fP list in all but one
2227: situation: a copy from a daemon rsync will add your skipped suffixes to
2228: its list of non\-compressing files (and its list may be configured to a
2229: different default).
2230: .IP
2231: .IP "\fB\-\-numeric\-ids\fP"
2232: With this option rsync will transfer numeric group
2233: and user IDs rather than using user and group names and mapping them
2234: at both ends.
2235: .IP
2236: By default rsync will use the username and groupname to determine
2237: what ownership to give files. The special uid 0 and the special group
2238: 0 are never mapped via user/group names even if the \fB\-\-numeric\-ids\fP
2239: option is not specified.
2240: .IP
2241: If a user or group has no name on the source system or it has no match
2242: on the destination system, then the numeric ID
2243: from the source system is used instead. See also the comments on the
2244: \(dq\&use chroot\(dq\& setting in the rsyncd.conf manpage for information on how
2245: the chroot setting affects rsync\(cq\&s ability to look up the names of the
2246: users and groups and what you can do about it.
2247: .IP
1.1.1.2 misho 2248: .IP "\fB\-\-usermap=STRING, \-\-groupmap=STRING\fP"
2249: These options allow you to
2250: specify users and groups that should be mapped to other values by the
2251: receiving side. The \fBSTRING\fP is one or more \fBFROM\fP:\fBTO\fP pairs of
2252: values separated by commas. Any matching \fBFROM\fP value from the sender is
2253: replaced with a \fBTO\fP value from the receiver. You may specify usernames
2254: or user IDs for the \fBFROM\fP and \fBTO\fP values, and the \fBFROM\fP value may
2255: also be a wild\-card string, which will be matched against the sender\(cq\&s
2256: names (wild\-cards do NOT match against ID numbers, though see below for
2257: why a \(cq\&*\(cq\& matches everything). You may instead specify a range of ID
2258: numbers via an inclusive range: LOW\-HIGH. For example:
2259: .IP
2260: .nf
2261: \-\-usermap=0\-99:nobody,wayne:admin,*:normal \-\-groupmap=usr:1,1:usr
2262: .fi
2263:
2264: .IP
2265: The first match in the list is the one that is used. You should specify
2266: all your user mappings using a single \fB\-\-usermap\fP option, and/or all
2267: your group mappings using a single \fB\-\-groupmap\fP option.
2268: .IP
2269: Note that the sender\(cq\&s name for the 0 user and group are not transmitted
2270: to the receiver, so you should either match these values using a 0, or use
2271: the names in effect on the receiving side (typically \(dq\&root\(dq\&). All other
2272: \fBFROM\fP names match those in use on the sending side. All \fBTO\fP names
2273: match those in use on the receiving side.
2274: .IP
2275: Any IDs that do not have a name on the sending side are treated as having an
2276: empty name for the purpose of matching. This allows them to be matched via
2277: a \(dq\&*\(dq\& or using an empty name. For instance:
2278: .IP
2279: .nf
2280: \-\-usermap=:nobody \-\-groupmap=*:nobody
2281: .fi
2282:
2283: .IP
2284: When the \fB\-\-numeric\-ids\fP option is used, the sender does not send any
2285: names, so all the IDs are treated as having an empty name. This means that
2286: you will need to specify numeric \fBFROM\fP values if you want to map these
2287: nameless IDs to different values.
2288: .IP
2289: For the \fB\-\-usermap\fP option to have any effect, the \fB\-o\fP (\fB\-\-owner\fP)
2290: option must be used (or implied), and the receiver will need to be running
2291: as a super\-user (see also the \fB\-\-fake\-super\fP option). For the \fB\-\-groupmap\fP
2292: option to have any effect, the \fB\-g\fP (\fB\-\-groups\fP) option must be used
2293: (or implied), and the receiver will need to have permissions to set that
2294: group.
2295: .IP
2296: .IP "\fB\-\-chown=USER:GROUP\fP"
2297: This option forces all files to be owned by USER
2298: with group GROUP. This is a simpler interface than using \fB\-\-usermap\fP and
2299: \fB\-\-groupmap\fP directly, but it is implemented using those options internally,
2300: so you cannot mix them. If either the USER or GROUP is empty, no mapping for
2301: the omitted user/group will occur. If GROUP is empty, the trailing colon may
2302: be omitted, but if USER is empty, a leading colon must be supplied.
2303: .IP
2304: If you specify \(dq\&\-\-chown=foo:bar, this is exactly the same as specifying
2305: \(dq\&\-\-usermap=*:foo \-\-groupmap=*:bar\(dq\&, only easier.
2306: .IP
1.1 misho 2307: .IP "\fB\-\-timeout=TIMEOUT\fP"
2308: This option allows you to set a maximum I/O
2309: timeout in seconds. If no data is transferred for the specified time
2310: then rsync will exit. The default is 0, which means no timeout.
2311: .IP
2312: .IP "\fB\-\-contimeout\fP"
2313: This option allows you to set the amount of time
2314: that rsync will wait for its connection to an rsync daemon to succeed.
2315: If the timeout is reached, rsync exits with an error.
2316: .IP
2317: .IP "\fB\-\-address\fP"
2318: By default rsync will bind to the wildcard address when
2319: connecting to an rsync daemon. The \fB\-\-address\fP option allows you to
2320: specify a specific IP address (or hostname) to bind to. See also this
2321: option in the \fB\-\-daemon\fP mode section.
2322: .IP
2323: .IP "\fB\-\-port=PORT\fP"
2324: This specifies an alternate TCP port number to use
2325: rather than the default of 873. This is only needed if you are using the
2326: double\-colon (::) syntax to connect with an rsync daemon (since the URL
2327: syntax has a way to specify the port as a part of the URL). See also this
2328: option in the \fB\-\-daemon\fP mode section.
2329: .IP
2330: .IP "\fB\-\-sockopts\fP"
2331: This option can provide endless fun for people
2332: who like to tune their systems to the utmost degree. You can set all
2333: sorts of socket options which may make transfers faster (or
2334: slower!). Read the man page for the
2335: \f(CWsetsockopt()\fP
2336: system call for
2337: details on some of the options you may be able to set. By default no
2338: special socket options are set. This only affects direct socket
2339: connections to a remote rsync daemon. This option also exists in the
2340: \fB\-\-daemon\fP mode section.
2341: .IP
2342: .IP "\fB\-\-blocking\-io\fP"
2343: This tells rsync to use blocking I/O when launching
2344: a remote shell transport. If the remote shell is either rsh or remsh,
2345: rsync defaults to using
2346: blocking I/O, otherwise it defaults to using non\-blocking I/O. (Note that
2347: ssh prefers non\-blocking I/O.)
2348: .IP
1.1.1.2 misho 2349: .IP "\fB\-\-outbuf=MODE\fP"
2350: This sets the output buffering mode. The mode can be
2351: None (aka Unbuffered), Line, or Block (aka Full). You may specify as little
2352: as a single letter for the mode, and use upper or lower case.
2353: .IP
2354: The main use of this option is to change Full buffering to Line buffering
2355: when rsync\(cq\&s output is going to a file or pipe.
2356: .IP
1.1 misho 2357: .IP "\fB\-i, \-\-itemize\-changes\fP"
2358: Requests a simple itemized list of the
2359: changes that are being made to each file, including attribute changes.
2360: This is exactly the same as specifying \fB\-\-out\-format='\&%i %n%L'\&\fP.
2361: If you repeat the option, unchanged files will also be output, but only
2362: if the receiving rsync is at least version 2.6.7 (you can use \fB\-vv\fP
2363: with older versions of rsync, but that also turns on the output of other
2364: verbose messages).
2365: .IP
2366: The \(dq\&%i\(dq\& escape has a cryptic output that is 11 letters long. The general
2367: format is like the string \fBYXcstpoguax\fP, where \fBY\fP is replaced by the
2368: type of update being done, \fBX\fP is replaced by the file\-type, and the
2369: other letters represent attributes that may be output if they are being
2370: modified.
2371: .IP
2372: The update types that replace the \fBY\fP are as follows:
2373: .IP
2374: .RS
2375: .IP o
2376: A \fB<\fP means that a file is being transferred to the remote host
2377: (sent).
2378: .IP o
2379: A \fB>\fP means that a file is being transferred to the local host
2380: (received).
2381: .IP o
2382: A \fBc\fP means that a local change/creation is occurring for the item
2383: (such as the creation of a directory or the changing of a symlink, etc.).
2384: .IP o
2385: A \fBh\fP means that the item is a hard link to another item (requires
2386: \fB\-\-hard\-links\fP).
2387: .IP o
2388: A \fB.\fP means that the item is not being updated (though it might
2389: have attributes that are being modified).
2390: .IP o
2391: A \fB*\fP means that the rest of the itemized\-output area contains
2392: a message (e.g. \(dq\&deleting\(dq\&).
2393: .RE
2394:
2395: .IP
2396: The file\-types that replace the \fBX\fP are: \fBf\fP for a file, a \fBd\fP for a
2397: directory, an \fBL\fP for a symlink, a \fBD\fP for a device, and a \fBS\fP for a
2398: special file (e.g. named sockets and fifos).
2399: .IP
2400: The other letters in the string above are the actual letters that
2401: will be output if the associated attribute for the item is being updated or
2402: a \(dq\&.\(dq\& for no change. Three exceptions to this are: (1) a newly created
2403: item replaces each letter with a \(dq\&+\(dq\&, (2) an identical item replaces the
2404: dots with spaces, and (3) an unknown attribute replaces each letter with
2405: a \(dq\&?\(dq\& (this can happen when talking to an older rsync).
2406: .IP
2407: The attribute that is associated with each letter is as follows:
2408: .IP
2409: .RS
2410: .IP o
2411: A \fBc\fP means either that a regular file has a different checksum
2412: (requires \fB\-\-checksum\fP) or that a symlink, device, or special file has
2413: a changed value.
2414: Note that if you are sending files to an rsync prior to 3.0.1, this
2415: change flag will be present only for checksum\-differing regular files.
2416: .IP o
2417: A \fBs\fP means the size of a regular file is different and will be updated
2418: by the file transfer.
2419: .IP o
2420: A \fBt\fP means the modification time is different and is being updated
2421: to the sender\(cq\&s value (requires \fB\-\-times\fP). An alternate value of \fBT\fP
2422: means that the modification time will be set to the transfer time, which happens
2423: when a file/symlink/device is updated without \fB\-\-times\fP and when a
2424: symlink is changed and the receiver can\(cq\&t set its time.
2425: (Note: when using an rsync 3.0.0 client, you might see the \fBs\fP flag combined
2426: with \fBt\fP instead of the proper \fBT\fP flag for this time\-setting failure.)
2427: .IP o
2428: A \fBp\fP means the permissions are different and are being updated to
2429: the sender\(cq\&s value (requires \fB\-\-perms\fP).
2430: .IP o
2431: An \fBo\fP means the owner is different and is being updated to the
2432: sender\(cq\&s value (requires \fB\-\-owner\fP and super\-user privileges).
2433: .IP o
2434: A \fBg\fP means the group is different and is being updated to the
2435: sender\(cq\&s value (requires \fB\-\-group\fP and the authority to set the group).
2436: .IP o
2437: The \fBu\fP slot is reserved for future use.
2438: .IP o
2439: The \fBa\fP means that the ACL information changed.
2440: .IP o
2441: The \fBx\fP means that the extended attribute information changed.
2442: .RE
2443:
2444: .IP
2445: One other output is possible: when deleting files, the \(dq\&%i\(dq\& will output
2446: the string \(dq\&*deleting\(dq\& for each item that is being removed (assuming that
2447: you are talking to a recent enough rsync that it logs deletions instead of
2448: outputting them as a verbose message).
2449: .IP
2450: .IP "\fB\-\-out\-format=FORMAT\fP"
2451: This allows you to specify exactly what the
2452: rsync client outputs to the user on a per\-update basis. The format is a
2453: text string containing embedded single\-character escape sequences prefixed
2454: with a percent (%) character. A default format of \(dq\&%n%L\(dq\& is assumed if
1.1.1.2 misho 2455: either \fB\-\-info=name\fP or \fB\-v\fP is specified (this tells you just the name
1.1 misho 2456: of the file and, if the item is a link, where it points). For a full list
2457: of the possible escape characters, see the \(dq\&log format\(dq\& setting in the
2458: rsyncd.conf manpage.
2459: .IP
1.1.1.2 misho 2460: Specifying the \fB\-\-out\-format\fP option implies the \fB\-\-info=name\fP option,
2461: which will mention each file, dir, etc. that gets updated in a significant
1.1 misho 2462: way (a transferred file, a recreated symlink/device, or a touched
2463: directory). In addition, if the itemize\-changes escape (%i) is included in
2464: the string (e.g. if the \fB\-\-itemize\-changes\fP option was used), the logging
2465: of names increases to mention any item that is changed in any way (as long
2466: as the receiving side is at least 2.6.4). See the \fB\-\-itemize\-changes\fP
2467: option for a description of the output of \(dq\&%i\(dq\&.
2468: .IP
2469: Rsync will output the out\-format string prior to a file\(cq\&s transfer unless
2470: one of the transfer\-statistic escapes is requested, in which case the
2471: logging is done at the end of the file\(cq\&s transfer. When this late logging
2472: is in effect and \fB\-\-progress\fP is also specified, rsync will also output
2473: the name of the file being transferred prior to its progress information
2474: (followed, of course, by the out\-format output).
2475: .IP
2476: .IP "\fB\-\-log\-file=FILE\fP"
2477: This option causes rsync to log what it is doing
2478: to a file. This is similar to the logging that a daemon does, but can be
2479: requested for the client side and/or the server side of a non\-daemon
2480: transfer. If specified as a client option, transfer logging will be
2481: enabled with a default format of \(dq\&%i %n%L\(dq\&. See the \fB\-\-log\-file\-format\fP
2482: option if you wish to override this.
2483: .IP
2484: Here\(cq\&s a example command that requests the remote side to log what is
2485: happening:
2486: .IP
2487: .nf
1.1.1.2 misho 2488: rsync \-av \-\-remote\-option=\-\-log\-file=/tmp/rlog src/ dest/
1.1 misho 2489: .fi
2490:
2491: .IP
2492: This is very useful if you need to debug why a connection is closing
2493: unexpectedly.
2494: .IP
2495: .IP "\fB\-\-log\-file\-format=FORMAT\fP"
2496: This allows you to specify exactly what
2497: per\-update logging is put into the file specified by the \fB\-\-log\-file\fP option
2498: (which must also be specified for this option to have any effect). If you
2499: specify an empty string, updated files will not be mentioned in the log file.
2500: For a list of the possible escape characters, see the \(dq\&log format\(dq\& setting
2501: in the rsyncd.conf manpage.
2502: .IP
2503: The default FORMAT used if \fB\-\-log\-file\fP is specified and this option is not
2504: is \(cq\&%i %n%L\(cq\&.
2505: .IP
2506: .IP "\fB\-\-stats\fP"
2507: This tells rsync to print a verbose set of statistics
2508: on the file transfer, allowing you to tell how effective rsync\(cq\&s delta\-transfer
1.1.1.2 misho 2509: algorithm is for your data. This option is equivalent to \fB\-\-info=stats2\fP
2510: if combined with 0 or 1 \fB\-v\fP options, or \fB\-\-info=stats3\fP if combined
2511: with 2 or more \fB\-v\fP options.
1.1 misho 2512: .IP
2513: The current statistics are as follows:
2514: .RS
2515: .IP o
2516: \fBNumber of files\fP is the count of all \(dq\&files\(dq\& (in the generic
1.1.1.2 misho 2517: sense), which includes directories, symlinks, etc. The total count will
2518: be followed by a list of counts by filetype (if the total is non\-zero).
2519: For example: \(dq\&(reg: 5, dir: 3, link: 2, dev: 1, special: 1)\(dq\& lists the
2520: totals for regular files, directories, symlinks, devices, and special
2521: files. If any of value is 0, it is completely omitted from the list.
2522: .IP o
2523: \fBNumber of created files\fP is the count of how many \(dq\&files\(dq\& (generic
2524: sense) were created (as opposed to updated). The total count will be
2525: followed by a list of counts by filetype (if the total is non\-zero).
2526: .IP o
2527: \fBNumber of deleted files\fP is the count of how many \(dq\&files\(dq\& (generic
2528: sense) were created (as opposed to updated). The total count will be
2529: followed by a list of counts by filetype (if the total is non\-zero).
2530: Note that this line is only output if deletions are in effect, and only
2531: if protocol 31 is being used (the default for rsync 3.1.x).
2532: .IP o
2533: \fBNumber of regular files transferred\fP is the count of normal files
2534: that were updated via rsync\(cq\&s delta\-transfer algorithm, which does not
2535: include dirs, symlinks, etc. Note that rsync 3.1.0 added the word
2536: \(dq\®ular\(dq\& into this heading.
1.1 misho 2537: .IP o
2538: \fBTotal file size\fP is the total sum of all file sizes in the transfer.
2539: This does not count any size for directories or special files, but does
2540: include the size of symlinks.
2541: .IP o
2542: \fBTotal transferred file size\fP is the total sum of all files sizes
2543: for just the transferred files.
2544: .IP o
2545: \fBLiteral data\fP is how much unmatched file\-update data we had to
2546: send to the receiver for it to recreate the updated files.
2547: .IP o
2548: \fBMatched data\fP is how much data the receiver got locally when
2549: recreating the updated files.
2550: .IP o
2551: \fBFile list size\fP is how big the file\-list data was when the sender
2552: sent it to the receiver. This is smaller than the in\-memory size for the
2553: file list due to some compressing of duplicated data when rsync sends the
2554: list.
2555: .IP o
2556: \fBFile list generation time\fP is the number of seconds that the
2557: sender spent creating the file list. This requires a modern rsync on the
2558: sending side for this to be present.
2559: .IP o
2560: \fBFile list transfer time\fP is the number of seconds that the sender
2561: spent sending the file list to the receiver.
2562: .IP o
2563: \fBTotal bytes sent\fP is the count of all the bytes that rsync sent
2564: from the client side to the server side.
2565: .IP o
2566: \fBTotal bytes received\fP is the count of all non\-message bytes that
2567: rsync received by the client side from the server side. \(dq\&Non\-message\(dq\&
2568: bytes means that we don\(cq\&t count the bytes for a verbose message that the
2569: server sent to us, which makes the stats more consistent.
2570: .RE
2571:
2572: .IP
2573: .IP "\fB\-8, \-\-8\-bit\-output\fP"
2574: This tells rsync to leave all high\-bit characters
2575: unescaped in the output instead of trying to test them to see if they\(cq\&re
2576: valid in the current locale and escaping the invalid ones. All control
2577: characters (but never tabs) are always escaped, regardless of this option\(cq\&s
2578: setting.
2579: .IP
2580: The escape idiom that started in 2.6.7 is to output a literal backslash (\e)
2581: and a hash (#), followed by exactly 3 octal digits. For example, a newline
2582: would output as \(dq\&\e#012\(dq\&. A literal backslash that is in a filename is not
2583: escaped unless it is followed by a hash and 3 digits (0\-9).
2584: .IP
2585: .IP "\fB\-h, \-\-human\-readable\fP"
2586: Output numbers in a more human\-readable format.
1.1.1.2 misho 2587: There are 3 possible levels: (1) output numbers with a separator between each
2588: set of 3 digits (either a comma or a period, depending on if the decimal point
2589: is represented by a period or a comma); (2) output numbers in units of 1000
2590: (with a character suffix for larger units \-\- see below); (3) output numbers in
2591: units of 1024.
2592: .IP
2593: The default is human\-readable level 1. Each \fB\-h\fP option increases the level
2594: by one. You can take the level down to 0 (to output numbers as pure digits) by
2595: specifing the \fB\-\-no\-human\-readable\fP (\fB\-\-no\-h\fP) option.
2596: .IP
2597: The unit letters that are appended in levels 2 and 3 are: K (kilo), M (mega),
2598: G (giga), or T (tera). For example, a 1234567\-byte file would output as 1.23M
2599: in level\-2 (assuming that a period is your local decimal point).
2600: .IP
2601: Backward compatibility note: versions of rsync prior to 3.1.0 do not support
2602: human\-readable level 1, and they default to level 0. Thus, specifying one or
2603: two \fB\-h\fP options will behave in a comparable manner in old and new versions
2604: as long as you didn\(cq\&t specify a \fB\-\-no\-h\fP option prior to one or more \fB\-h\fP
2605: options. See the \fB\-\-list\-only\fP option for one difference.
1.1 misho 2606: .IP
2607: .IP "\fB\-\-partial\fP"
2608: By default, rsync will delete any partially
2609: transferred file if the transfer is interrupted. In some circumstances
2610: it is more desirable to keep partially transferred files. Using the
2611: \fB\-\-partial\fP option tells rsync to keep the partial file which should
2612: make a subsequent transfer of the rest of the file much faster.
2613: .IP
2614: .IP "\fB\-\-partial\-dir=DIR\fP"
2615: A better way to keep partial files than the
2616: \fB\-\-partial\fP option is to specify a \fIDIR\fP that will be used to hold the
2617: partial data (instead of writing it out to the destination file).
2618: On the next transfer, rsync will use a file found in this
2619: dir as data to speed up the resumption of the transfer and then delete it
2620: after it has served its purpose.
2621: .IP
2622: Note that if \fB\-\-whole\-file\fP is specified (or implied), any partial\-dir
2623: file that is found for a file that is being updated will simply be removed
2624: (since
2625: rsync is sending files without using rsync\(cq\&s delta\-transfer algorithm).
2626: .IP
2627: Rsync will create the \fIDIR\fP if it is missing (just the last dir \-\- not
2628: the whole path). This makes it easy to use a relative path (such as
2629: \(dq\&\fB\-\-partial\-dir=.rsync\-partial\fP\(dq\&) to have rsync create the
2630: partial\-directory in the destination file\(cq\&s directory when needed, and then
2631: remove it again when the partial file is deleted.
2632: .IP
2633: If the partial\-dir value is not an absolute path, rsync will add an exclude
2634: rule at the end of all your existing excludes. This will prevent the
2635: sending of any partial\-dir files that may exist on the sending side, and
2636: will also prevent the untimely deletion of partial\-dir items on the
2637: receiving side. An example: the above \fB\-\-partial\-dir\fP option would add
2638: the equivalent of \(dq\&\fB\-f '\&\-p .rsync\-partial/'\&\fP\(dq\& at the end of any other
2639: filter rules.
2640: .IP
2641: If you are supplying your own exclude rules, you may need to add your own
2642: exclude/hide/protect rule for the partial\-dir because (1) the auto\-added
2643: rule may be ineffective at the end of your other rules, or (2) you may wish
2644: to override rsync\(cq\&s exclude choice. For instance, if you want to make
2645: rsync clean\-up any left\-over partial\-dirs that may be lying around, you
2646: should specify \fB\-\-delete\-after\fP and add a \(dq\&risk\(dq\& filter rule, e.g.
2647: \fB\-f '\&R .rsync\-partial/'\&\fP. (Avoid using \fB\-\-delete\-before\fP or
2648: \fB\-\-delete\-during\fP unless you don\(cq\&t need rsync to use any of the
2649: left\-over partial\-dir data during the current run.)
2650: .IP
2651: IMPORTANT: the \fB\-\-partial\-dir\fP should not be writable by other users or it
2652: is a security risk. E.g. AVOID \(dq\&/tmp\(dq\&.
2653: .IP
2654: You can also set the partial\-dir value the RSYNC_PARTIAL_DIR environment
2655: variable. Setting this in the environment does not force \fB\-\-partial\fP to be
2656: enabled, but rather it affects where partial files go when \fB\-\-partial\fP is
2657: specified. For instance, instead of using \fB\-\-partial\-dir=.rsync\-tmp\fP
2658: along with \fB\-\-progress\fP, you could set RSYNC_PARTIAL_DIR=.rsync\-tmp in your
2659: environment and then just use the \fB\-P\fP option to turn on the use of the
2660: \&.rsync\-tmp dir for partial transfers. The only times that the \fB\-\-partial\fP
2661: option does not look for this environment value are (1) when \fB\-\-inplace\fP was
2662: specified (since \fB\-\-inplace\fP conflicts with \fB\-\-partial\-dir\fP), and (2) when
2663: \fB\-\-delay\-updates\fP was specified (see below).
2664: .IP
2665: For the purposes of the daemon\-config\(cq\&s \(dq\&refuse options\(dq\& setting,
2666: \fB\-\-partial\-dir\fP does \fInot\fP imply \fB\-\-partial\fP. This is so that a
2667: refusal of the \fB\-\-partial\fP option can be used to disallow the overwriting
2668: of destination files with a partial transfer, while still allowing the
2669: safer idiom provided by \fB\-\-partial\-dir\fP.
2670: .IP
2671: .IP "\fB\-\-delay\-updates\fP"
2672: This option puts the temporary file from each
2673: updated file into a holding directory until the end of the
2674: transfer, at which time all the files are renamed into place in rapid
2675: succession. This attempts to make the updating of the files a little more
2676: atomic. By default the files are placed into a directory named \(dq\&.~tmp~\(dq\& in
2677: each file\(cq\&s destination directory, but if you\(cq\&ve specified the
2678: \fB\-\-partial\-dir\fP option, that directory will be used instead. See the
2679: comments in the \fB\-\-partial\-dir\fP section for a discussion of how this
2680: \(dq\&.~tmp~\(dq\& dir will be excluded from the transfer, and what you can do if
2681: you want rsync to cleanup old \(dq\&.~tmp~\(dq\& dirs that might be lying around.
2682: Conflicts with \fB\-\-inplace\fP and \fB\-\-append\fP.
2683: .IP
2684: This option uses more memory on the receiving side (one bit per file
2685: transferred) and also requires enough free disk space on the receiving
2686: side to hold an additional copy of all the updated files. Note also that
2687: you should not use an absolute path to \fB\-\-partial\-dir\fP unless (1)
2688: there is no
2689: chance of any of the files in the transfer having the same name (since all
2690: the updated files will be put into a single directory if the path is
2691: absolute)
2692: and (2) there are no mount points in the hierarchy (since the
2693: delayed updates will fail if they can\(cq\&t be renamed into place).
2694: .IP
2695: See also the \(dq\&atomic\-rsync\(dq\& perl script in the \(dq\&support\(dq\& subdir for an
2696: update algorithm that is even more atomic (it uses \fB\-\-link\-dest\fP and a
2697: parallel hierarchy of files).
2698: .IP
2699: .IP "\fB\-m, \-\-prune\-empty\-dirs\fP"
2700: This option tells the receiving rsync to get
2701: rid of empty directories from the file\-list, including nested directories
2702: that have no non\-directory children. This is useful for avoiding the
2703: creation of a bunch of useless directories when the sending rsync is
2704: recursively scanning a hierarchy of files using include/exclude/filter
2705: rules.
2706: .IP
2707: Note that the use of transfer rules, such as the \fB\-\-min\-size\fP option, does
2708: not affect what goes into the file list, and thus does not leave directories
2709: empty, even if none of the files in a directory match the transfer rule.
2710: .IP
2711: Because the file\-list is actually being pruned, this option also affects
2712: what directories get deleted when a delete is active. However, keep in
2713: mind that excluded files and directories can prevent existing items from
2714: being deleted due to an exclude both hiding source files and protecting
2715: destination files. See the perishable filter\-rule option for how to avoid
2716: this.
2717: .IP
2718: You can prevent the pruning of certain empty directories from the file\-list
2719: by using a global \(dq\&protect\(dq\& filter. For instance, this option would ensure
2720: that the directory \(dq\&emptydir\(dq\& was kept in the file\-list:
2721: .IP
2722: .RS
2723: \-\-filter \(cq\&protect emptydir/\(cq\&
2724: .RE
2725:
2726: .IP
2727: Here\(cq\&s an example that copies all .pdf files in a hierarchy, only creating
2728: the necessary destination directories to hold the .pdf files, and ensures
2729: that any superfluous files and directories in the destination are removed
2730: (note the hide filter of non\-directories being used instead of an exclude):
2731: .IP
2732: .RS
2733: rsync \-avm \-\-del \-\-include=\(cq\&*.pdf\(cq\& \-f \(cq\&hide,! */\(cq\& src/ dest
2734: .RE
2735:
2736: .IP
2737: If you didn\(cq\&t want to remove superfluous destination files, the more
2738: time\-honored options of \(dq\&\fB\-\-include='\&*/'\& \-\-exclude='\&*'\&\fP\(dq\& would work fine
2739: in place of the hide\-filter (if that is more natural to you).
2740: .IP
2741: .IP "\fB\-\-progress\fP"
2742: This option tells rsync to print information
2743: showing the progress of the transfer. This gives a bored user
2744: something to watch.
1.1.1.2 misho 2745: With a modern rsync this is the same as specifying
2746: \fB\-\-info=flist2,name,progress\fP, but any user\-supplied settings for those
2747: info flags takes precedence (e.g. \(dq\&\-\-info=flist0 \-\-progress\(dq\&).
1.1 misho 2748: .IP
2749: While rsync is transferring a regular file, it updates a progress line that
2750: looks like this:
2751: .IP
2752: .nf
2753: 782448 63% 110.64kB/s 0:00:04
2754: .fi
2755:
2756: .IP
2757: In this example, the receiver has reconstructed 782448 bytes or 63% of the
2758: sender\(cq\&s file, which is being reconstructed at a rate of 110.64 kilobytes
2759: per second, and the transfer will finish in 4 seconds if the current rate
2760: is maintained until the end.
2761: .IP
2762: These statistics can be misleading if rsync\(cq\&s delta\-transfer algorithm is
2763: in use. For example, if the sender\(cq\&s file consists of the basis file
2764: followed by additional data, the reported rate will probably drop
2765: dramatically when the receiver gets to the literal data, and the transfer
2766: will probably take much longer to finish than the receiver estimated as it
2767: was finishing the matched part of the file.
2768: .IP
2769: When the file transfer finishes, rsync replaces the progress line with a
2770: summary line that looks like this:
2771: .IP
2772: .nf
1.1.1.2 misho 2773: 1,238,099 100% 146.38kB/s 0:00:08 (xfr#5, to\-chk=169/396)
1.1 misho 2774: .fi
2775:
2776: .IP
1.1.1.2 misho 2777: In this example, the file was 1,238,099 bytes long in total, the average rate
1.1 misho 2778: of transfer for the whole file was 146.38 kilobytes per second over the 8
2779: seconds that it took to complete, it was the 5th transfer of a regular file
2780: during the current rsync session, and there are 169 more files for the
2781: receiver to check (to see if they are up\-to\-date or not) remaining out of
2782: the 396 total files in the file\-list.
2783: .IP
1.1.1.2 misho 2784: In an incremental recursion scan, rsync won\(cq\&t know the total number of files
2785: in the file\-list until it reaches the ends of the scan, but since it starts to
2786: transfer files during the scan, it will display a line with the text \(dq\&ir\-chk\(dq\&
2787: (for incremental recursion check) instead of \(dq\&to\-chk\(dq\& until the point that it
2788: knows the full size of the list, at which point it will switch to using
2789: \(dq\&to\-chk\(dq\&. Thus, seeing \(dq\&ir\-chk\(dq\& lets you know that the total count of files
2790: in the file list is still going to increase (and each time it does, the count
2791: of files left to check will increase by the number of the files added to the
2792: list).
2793: .IP
1.1 misho 2794: .IP "\fB\-P\fP"
2795: The \fB\-P\fP option is equivalent to \fB\-\-partial\fP \fB\-\-progress\fP. Its
2796: purpose is to make it much easier to specify these two options for a long
2797: transfer that may be interrupted.
2798: .IP
1.1.1.2 misho 2799: There is also a \fB\-\-info=progress2\fP option that outputs statistics based
2800: on the whole transfer, rather than individual files. Use this flag without
1.1.1.3 ! misho 2801: outputting a filename (e.g. avoid \fB\-v\fP or specify \fB\-\-info=name0\fP) if you
1.1.1.2 misho 2802: want to see how the transfer is doing without scrolling the screen with a
2803: lot of names. (You don\(cq\&t need to specify the \fB\-\-progress\fP option in
2804: order to use \fB\-\-info=progress2\fP.)
2805: .IP
2806: .IP "\fB\-\-password\-file=FILE\fP"
2807: This option allows you to provide a password for
2808: accessing an rsync daemon via a file or via standard input if \fBFILE\fP is
2809: \fB\-\fP. The file should contain just the password on the first line (all other
2810: lines are ignored). Rsync will exit with an error if \fBFILE\fP is world
2811: readable or if a root\-run rsync command finds a non\-root\-owned file.
1.1 misho 2812: .IP
2813: This option does not supply a password to a remote shell transport such as
2814: ssh; to learn how to do that, consult the remote shell\(cq\&s documentation.
2815: When accessing an rsync daemon using a remote shell as the transport, this
2816: option only comes into effect after the remote shell finishes its
2817: authentication (i.e. if you have also specified a password in the daemon\(cq\&s
2818: config file).
2819: .IP
2820: .IP "\fB\-\-list\-only\fP"
2821: This option will cause the source files to be listed
2822: instead of transferred. This option is inferred if there is a single source
2823: arg and no destination specified, so its main uses are: (1) to turn a copy
2824: command that includes a
2825: destination arg into a file\-listing command, or (2) to be able to specify
2826: more than one source arg (note: be sure to include the destination).
2827: Caution: keep in mind that a source arg with a wild\-card is expanded by the
2828: shell into multiple args, so it is never safe to try to list such an arg
2829: without using this option. For example:
2830: .IP
2831: .nf
2832: rsync \-av \-\-list\-only foo* dest/
2833: .fi
2834:
2835: .IP
1.1.1.2 misho 2836: Starting with rsync 3.1.0, the sizes output by \fB\-\-list\-only\fP are affected
2837: by the \fB\-\-human\-readable\fP option. By default they will contain digit
2838: separators, but higher levels of readability will output the sizes with
2839: unit suffixes. Note also that the column width for the size output has
2840: increased from 11 to 14 characters for all human\-readable levels. Use
2841: \fB\-\-no\-h\fP if you want just digits in the sizes, and the old column width
2842: of 11 characters.
2843: .IP
1.1 misho 2844: Compatibility note: when requesting a remote listing of files from an rsync
2845: that is version 2.6.3 or older, you may encounter an error if you ask for a
2846: non\-recursive listing. This is because a file listing implies the \fB\-\-dirs\fP
2847: option w/o \fB\-\-recursive\fP, and older rsyncs don\(cq\&t have that option. To
2848: avoid this problem, either specify the \fB\-\-no\-dirs\fP option (if you don\(cq\&t
2849: need to expand a directory\(cq\&s content), or turn on recursion and exclude
2850: the content of subdirectories: \fB\-r \-\-exclude='\&/*/*'\&\fP.
2851: .IP
1.1.1.2 misho 2852: .IP "\fB\-\-bwlimit=RATE\fP"
2853: This option allows you to specify the maximum transfer
2854: rate for the data sent over the socket, specified in units per second. The
2855: RATE value can be suffixed with a string to indicate a size multiplier, and may
2856: be a fractional value (e.g. \(dq\&\fB\-\-bwlimit=1.5m\fP\(dq\&). If no suffix is specified,
2857: the value will be assumed to be in units of 1024 bytes (as if \(dq\&K\(dq\& or \(dq\&KiB\(dq\& had
2858: been appended). See the \fB\-\-max\-size\fP option for a description of all the
2859: available suffixes. A value of zero specifies no limit.
2860: .IP
2861: For backward\-compatibility reasons, the rate limit will be rounded to the
2862: nearest KiB unit, so no rate smaller than 1024 bytes per second is possible.
2863: .IP
2864: Rsync writes data over the socket in blocks, and this option both limits the
2865: size of the blocks that rsync writes, and tries to keep the average transfer
2866: rate at the requested limit. Some \(dq\&burstiness\(dq\& may be seen where rsync writes
2867: out a block of data and then sleeps to bring the average rate into compliance.
2868: .IP
2869: Due to the internal buffering of data, the \fB\-\-progress\fP option may not be an
2870: accurate reflection on how fast the data is being sent. This is because some
2871: files can show up as being rapidly sent when the data is quickly buffered,
2872: while other can show up as very slow when the flushing of the output buffer
2873: occurs. This may be fixed in a future version.
1.1 misho 2874: .IP
2875: .IP "\fB\-\-write\-batch=FILE\fP"
2876: Record a file that can later be applied to
2877: another identical destination with \fB\-\-read\-batch\fP. See the \(dq\&BATCH MODE\(dq\&
2878: section for details, and also the \fB\-\-only\-write\-batch\fP option.
2879: .IP
2880: .IP "\fB\-\-only\-write\-batch=FILE\fP"
2881: Works like \fB\-\-write\-batch\fP, except that
2882: no updates are made on the destination system when creating the batch.
2883: This lets you transport the changes to the destination system via some
2884: other means and then apply the changes via \fB\-\-read\-batch\fP.
2885: .IP
2886: Note that you can feel free to write the batch directly to some portable
2887: media: if this media fills to capacity before the end of the transfer, you
2888: can just apply that partial transfer to the destination and repeat the
2889: whole process to get the rest of the changes (as long as you don\(cq\&t mind a
2890: partially updated destination system while the multi\-update cycle is
2891: happening).
2892: .IP
2893: Also note that you only save bandwidth when pushing changes to a remote
2894: system because this allows the batched data to be diverted from the sender
2895: into the batch file without having to flow over the wire to the receiver
2896: (when pulling, the sender is remote, and thus can\(cq\&t write the batch).
2897: .IP
2898: .IP "\fB\-\-read\-batch=FILE\fP"
2899: Apply all of the changes stored in FILE, a
2900: file previously generated by \fB\-\-write\-batch\fP.
2901: If \fIFILE\fP is \fB\-\fP, the batch data will be read from standard input.
2902: See the \(dq\&BATCH MODE\(dq\& section for details.
2903: .IP
2904: .IP "\fB\-\-protocol=NUM\fP"
2905: Force an older protocol version to be used. This
2906: is useful for creating a batch file that is compatible with an older
2907: version of rsync. For instance, if rsync 2.6.4 is being used with the
2908: \fB\-\-write\-batch\fP option, but rsync 2.6.3 is what will be used to run the
2909: \fB\-\-read\-batch\fP option, you should use \(dq\&\-\-protocol=28\(dq\& when creating the
2910: batch file to force the older protocol version to be used in the batch
2911: file (assuming you can\(cq\&t upgrade the rsync on the reading system).
2912: .IP
2913: .IP "\fB\-\-iconv=CONVERT_SPEC\fP"
2914: Rsync can convert filenames between character
2915: sets using this option. Using a CONVERT_SPEC of \(dq\&.\(dq\& tells rsync to look up
2916: the default character\-set via the locale setting. Alternately, you can
2917: fully specify what conversion to do by giving a local and a remote charset
2918: separated by a comma in the order \fB\-\-iconv=LOCAL,REMOTE\fP, e.g.
2919: \fB\-\-iconv=utf8,iso88591\fP. This order ensures that the option
2920: will stay the same whether you\(cq\&re pushing or pulling files.
2921: Finally, you can specify either \fB\-\-no\-iconv\fP or a CONVERT_SPEC of \(dq\&\-\(dq\&
2922: to turn off any conversion.
2923: The default setting of this option is site\-specific, and can also be
2924: affected via the RSYNC_ICONV environment variable.
2925: .IP
2926: For a list of what charset names your local iconv library supports, you can
2927: run \(dq\&iconv \-\-list\(dq\&.
2928: .IP
2929: If you specify the \fB\-\-protect\-args\fP option (\fB\-s\fP), rsync will translate
2930: the filenames you specify on the command\-line that are being sent to the
2931: remote host. See also the \fB\-\-files\-from\fP option.
2932: .IP
2933: Note that rsync does not do any conversion of names in filter files
2934: (including include/exclude files). It is up to you to ensure that you\(cq\&re
2935: specifying matching rules that can match on both sides of the transfer.
2936: For instance, you can specify extra include/exclude rules if there are
2937: filename differences on the two sides that need to be accounted for.
2938: .IP
2939: When you pass an \fB\-\-iconv\fP option to an rsync daemon that allows it, the
2940: daemon uses the charset specified in its \(dq\&charset\(dq\& configuration parameter
2941: regardless of the remote charset you actually pass. Thus, you may feel free to
2942: specify just the local charset for a daemon transfer (e.g. \fB\-\-iconv=utf8\fP).
2943: .IP
2944: .IP "\fB\-4, \-\-ipv4\fP or \fB\-6, \-\-ipv6\fP"
2945: Tells rsync to prefer IPv4/IPv6
2946: when creating sockets. This only affects sockets that rsync has direct
2947: control over, such as the outgoing socket when directly contacting an
2948: rsync daemon. See also these options in the \fB\-\-daemon\fP mode section.
2949: .IP
2950: If rsync was complied without support for IPv6, the \fB\-\-ipv6\fP option
2951: will have no effect. The \fB\-\-version\fP output will tell you if this
2952: is the case.
2953: .IP
2954: .IP "\fB\-\-checksum\-seed=NUM\fP"
1.1.1.2 misho 2955: Set the checksum seed to the integer NUM. This 4
2956: byte checksum seed is included in each block and MD4 file checksum calculation
2957: (the more modern MD5 file checksums don\(cq\&t use a seed). By default the checksum
2958: seed is generated by the server and defaults to the current
1.1 misho 2959: \f(CWtime()\fP
1.1.1.2 misho 2960: \&. This
2961: option is used to set a specific checksum seed, which is useful for
2962: applications that want repeatable block checksums, or in the case where the
2963: user wants a more random checksum seed. Setting NUM to 0 causes rsync to use
2964: the default of
1.1 misho 2965: \f(CWtime()\fP
2966: for checksum seed.
1.1.1.2 misho 2967: .IP
1.1 misho 2968: .SH "DAEMON OPTIONS"
2969:
2970: .PP
2971: The options allowed when starting an rsync daemon are as follows:
2972: .PP
2973: .IP "\fB\-\-daemon\fP"
2974: This tells rsync that it is to run as a daemon. The
2975: daemon you start running may be accessed using an rsync client using
2976: the \fBhost::module\fP or \fBrsync://host/module/\fP syntax.
2977: .IP
2978: If standard input is a socket then rsync will assume that it is being
2979: run via inetd, otherwise it will detach from the current terminal and
2980: become a background daemon. The daemon will read the config file
2981: (rsyncd.conf) on each connect made by a client and respond to
2982: requests accordingly. See the \fBrsyncd.conf\fP(5) man page for more
2983: details.
2984: .IP
2985: .IP "\fB\-\-address\fP"
2986: By default rsync will bind to the wildcard address when
2987: run as a daemon with the \fB\-\-daemon\fP option. The \fB\-\-address\fP option
2988: allows you to specify a specific IP address (or hostname) to bind to. This
2989: makes virtual hosting possible in conjunction with the \fB\-\-config\fP option.
2990: See also the \(dq\&address\(dq\& global option in the rsyncd.conf manpage.
2991: .IP
1.1.1.2 misho 2992: .IP "\fB\-\-bwlimit=RATE\fP"
2993: This option allows you to specify the maximum transfer
2994: rate for the data the daemon sends over the socket. The client can still
2995: specify a smaller \fB\-\-bwlimit\fP value, but no larger value will be allowed.
2996: See the client version of this option (above) for some extra details.
1.1 misho 2997: .IP
2998: .IP "\fB\-\-config=FILE\fP"
2999: This specifies an alternate config file than
3000: the default. This is only relevant when \fB\-\-daemon\fP is specified.
3001: The default is /etc/rsyncd.conf unless the daemon is running over
3002: a remote shell program and the remote user is not the super\-user; in that case
3003: the default is rsyncd.conf in the current directory (typically $HOME).
3004: .IP
1.1.1.2 misho 3005: .IP "\fB\-M, \-\-dparam=OVERRIDE\fP"
3006: This option can be used to set a daemon\-config
3007: parameter when starting up rsync in daemon mode. It is equivalent to adding
3008: the parameter at the end of the global settings prior to the first module\(cq\&s
3009: definition. The parameter names can be specified without spaces, if you so
3010: desire. For instance:
3011: .IP
3012: .nf
3013: rsync \-\-daemon \-M pidfile=/path/rsync.pid
3014: .fi
3015:
3016: .IP
1.1 misho 3017: .IP "\fB\-\-no\-detach\fP"
3018: When running as a daemon, this option instructs
3019: rsync to not detach itself and become a background process. This
3020: option is required when running as a service on Cygwin, and may also
3021: be useful when rsync is supervised by a program such as
3022: \fBdaemontools\fP or AIX\(cq\&s \fBSystem Resource Controller\fP.
3023: \fB\-\-no\-detach\fP is also recommended when rsync is run under a
3024: debugger. This option has no effect if rsync is run from inetd or
3025: sshd.
3026: .IP
3027: .IP "\fB\-\-port=PORT\fP"
3028: This specifies an alternate TCP port number for the
3029: daemon to listen on rather than the default of 873. See also the \(dq\&port\(dq\&
3030: global option in the rsyncd.conf manpage.
3031: .IP
3032: .IP "\fB\-\-log\-file=FILE\fP"
3033: This option tells the rsync daemon to use the
3034: given log\-file name instead of using the \(dq\&log file\(dq\& setting in the config
3035: file.
3036: .IP
3037: .IP "\fB\-\-log\-file\-format=FORMAT\fP"
3038: This option tells the rsync daemon to use the
3039: given FORMAT string instead of using the \(dq\&log format\(dq\& setting in the config
3040: file. It also enables \(dq\&transfer logging\(dq\& unless the string is empty, in which
3041: case transfer logging is turned off.
3042: .IP
3043: .IP "\fB\-\-sockopts\fP"
3044: This overrides the \fBsocket options\fP setting in the
3045: rsyncd.conf file and has the same syntax.
3046: .IP
3047: .IP "\fB\-v, \-\-verbose\fP"
3048: This option increases the amount of information the
3049: daemon logs during its startup phase. After the client connects, the
3050: daemon\(cq\&s verbosity level will be controlled by the options that the client
3051: used and the \(dq\&max verbosity\(dq\& setting in the module\(cq\&s config section.
3052: .IP
3053: .IP "\fB\-4, \-\-ipv4\fP or \fB\-6, \-\-ipv6\fP"
3054: Tells rsync to prefer IPv4/IPv6
3055: when creating the incoming sockets that the rsync daemon will use to
3056: listen for connections. One of these options may be required in older
3057: versions of Linux to work around an IPv6 bug in the kernel (if you see
3058: an \(dq\&address already in use\(dq\& error when nothing else is using the port,
3059: try specifying \fB\-\-ipv6\fP or \fB\-\-ipv4\fP when starting the daemon).
3060: .IP
3061: If rsync was complied without support for IPv6, the \fB\-\-ipv6\fP option
3062: will have no effect. The \fB\-\-version\fP output will tell you if this
3063: is the case.
3064: .IP
3065: .IP "\fB\-h, \-\-help\fP"
3066: When specified after \fB\-\-daemon\fP, print a short help
3067: page describing the options available for starting an rsync daemon.
3068:
3069: .PP
3070: .SH "FILTER RULES"
3071:
3072: .PP
3073: The filter rules allow for flexible selection of which files to transfer
3074: (include) and which files to skip (exclude). The rules either directly
3075: specify include/exclude patterns or they specify a way to acquire more
3076: include/exclude patterns (e.g. to read them from a file).
3077: .PP
3078: As the list of files/directories to transfer is built, rsync checks each
3079: name to be transferred against the list of include/exclude patterns in
3080: turn, and the first matching pattern is acted on: if it is an exclude
3081: pattern, then that file is skipped; if it is an include pattern then that
3082: filename is not skipped; if no matching pattern is found, then the
3083: filename is not skipped.
3084: .PP
3085: Rsync builds an ordered list of filter rules as specified on the
3086: command\-line. Filter rules have the following syntax:
3087: .PP
3088: .RS
3089: \f(CWRULE [PATTERN_OR_FILENAME]\fP
3090: .br
3091: \f(CWRULE,MODIFIERS [PATTERN_OR_FILENAME]\fP
3092: .br
3093: .RE
3094:
3095: .PP
3096: You have your choice of using either short or long RULE names, as described
3097: below. If you use a short\-named rule, the \(cq\&,\(cq\& separating the RULE from the
3098: MODIFIERS is optional. The PATTERN or FILENAME that follows (when present)
3099: must come after either a single space or an underscore (_).
3100: Here are the available rule prefixes:
3101: .PP
3102: .RS
3103: \fBexclude, \-\fP specifies an exclude pattern.
3104: .br
3105: \fBinclude, +\fP specifies an include pattern.
3106: .br
3107: \fBmerge, .\fP specifies a merge\-file to read for more rules.
3108: .br
3109: \fBdir\-merge, :\fP specifies a per\-directory merge\-file.
3110: .br
3111: \fBhide, H\fP specifies a pattern for hiding files from the transfer.
3112: .br
3113: \fBshow, S\fP files that match the pattern are not hidden.
3114: .br
3115: \fBprotect, P\fP specifies a pattern for protecting files from deletion.
3116: .br
3117: \fBrisk, R\fP files that match the pattern are not protected.
3118: .br
3119: \fBclear, !\fP clears the current include/exclude list (takes no arg)
3120: .br
3121: .RE
3122:
3123: .PP
3124: When rules are being read from a file, empty lines are ignored, as are
3125: comment lines that start with a \(dq\&#\(dq\&.
3126: .PP
3127: Note that the \fB\-\-include\fP/\fB\-\-exclude\fP command\-line options do not allow the
3128: full range of rule parsing as described above \-\- they only allow the
3129: specification of include/exclude patterns plus a \(dq\&!\(dq\& token to clear the
3130: list (and the normal comment parsing when rules are read from a file).
3131: If a pattern
3132: does not begin with \(dq\&\- \(dq\& (dash, space) or \(dq\&+ \(dq\& (plus, space), then the
3133: rule will be interpreted as if \(dq\&+ \(dq\& (for an include option) or \(dq\&\- \(dq\& (for
3134: an exclude option) were prefixed to the string. A \fB\-\-filter\fP option, on
3135: the other hand, must always contain either a short or long rule name at the
3136: start of the rule.
3137: .PP
3138: Note also that the \fB\-\-filter\fP, \fB\-\-include\fP, and \fB\-\-exclude\fP options take one
3139: rule/pattern each. To add multiple ones, you can repeat the options on
3140: the command\-line, use the merge\-file syntax of the \fB\-\-filter\fP option, or
3141: the \fB\-\-include\-from\fP/\fB\-\-exclude\-from\fP options.
3142: .PP
3143: .SH "INCLUDE/EXCLUDE PATTERN RULES"
3144:
3145: .PP
3146: You can include and exclude files by specifying patterns using the \(dq\&+\(dq\&,
3147: \(dq\&\-\(dq\&, etc. filter rules (as introduced in the FILTER RULES section above).
3148: The include/exclude rules each specify a pattern that is matched against
3149: the names of the files that are going to be transferred. These patterns
3150: can take several forms:
3151: .PP
3152: .IP o
3153: if the pattern starts with a / then it is anchored to a
3154: particular spot in the hierarchy of files, otherwise it is matched
3155: against the end of the pathname. This is similar to a leading ^ in
3156: regular expressions.
3157: Thus \(dq\&/foo\(dq\& would match a name of \(dq\&foo\(dq\& at either the \(dq\&root of the
3158: transfer\(dq\& (for a global rule) or in the merge\-file\(cq\&s directory (for a
3159: per\-directory rule).
3160: An unqualified \(dq\&foo\(dq\& would match a name of \(dq\&foo\(dq\& anywhere in the
3161: tree because the algorithm is applied recursively from the
3162: top down; it behaves as if each path component gets a turn at being the
3163: end of the filename. Even the unanchored \(dq\&sub/foo\(dq\& would match at
3164: any point in the hierarchy where a \(dq\&foo\(dq\& was found within a directory
3165: named \(dq\&sub\(dq\&. See the section on ANCHORING INCLUDE/EXCLUDE PATTERNS for
3166: a full discussion of how to specify a pattern that matches at the root
3167: of the transfer.
3168: .IP o
3169: if the pattern ends with a / then it will only match a
3170: directory, not a regular file, symlink, or device.
3171: .IP o
3172: rsync chooses between doing a simple string match and wildcard
3173: matching by checking if the pattern contains one of these three wildcard
3174: characters: \(cq\&*\(cq\&, \(cq\&?\(cq\&, and \(cq\&[\(cq\& .
3175: .IP o
3176: a \(cq\&*\(cq\& matches any path component, but it stops at slashes.
3177: .IP o
3178: use \(cq\&**\(cq\& to match anything, including slashes.
3179: .IP o
3180: a \(cq\&?\(cq\& matches any character except a slash (/).
3181: .IP o
3182: a \(cq\&[\(cq\& introduces a character class, such as [a\-z] or [[:alpha:]].
3183: .IP o
3184: in a wildcard pattern, a backslash can be used to escape a wildcard
3185: character, but it is matched literally when no wildcards are present.
1.1.1.3 ! misho 3186: This means that there is an extra level of backslash removal when a
! 3187: pattern contains wildcard characters compared to a pattern that has none.
! 3188: e.g. if you add a wildcard to \(dq\&foo\ebar\(dq\& (which matches the backslash) you
! 3189: would need to use \(dq\&foo\e\ebar*\(dq\& to avoid the \(dq\&\eb\(dq\& becoming just \(dq\&b\(dq\&.
1.1 misho 3190: .IP o
3191: if the pattern contains a / (not counting a trailing /) or a \(dq\&**\(dq\&,
3192: then it is matched against the full pathname, including any leading
3193: directories. If the pattern doesn\(cq\&t contain a / or a \(dq\&**\(dq\&, then it is
3194: matched only against the final component of the filename.
3195: (Remember that the algorithm is applied recursively so \(dq\&full filename\(dq\&
3196: can actually be any portion of a path from the starting directory on
3197: down.)
3198: .IP o
3199: a trailing \(dq\&dir_name/***\(dq\& will match both the directory (as if
3200: \(dq\&dir_name/\(dq\& had been specified) and everything in the directory
3201: (as if \(dq\&dir_name/**\(dq\& had been specified). This behavior was added in
3202: version 2.6.7.
3203:
3204: .PP
3205: Note that, when using the \fB\-\-recursive\fP (\fB\-r\fP) option (which is implied by
3206: \fB\-a\fP), every subcomponent of every path is visited from the top down, so
3207: include/exclude patterns get applied recursively to each subcomponent\(cq\&s
3208: full name (e.g. to include \(dq\&/foo/bar/baz\(dq\& the subcomponents \(dq\&/foo\(dq\& and
3209: \(dq\&/foo/bar\(dq\& must not be excluded).
3210: The exclude patterns actually short\-circuit the directory traversal stage
3211: when rsync finds the files to send. If a pattern excludes a particular
3212: parent directory, it can render a deeper include pattern ineffectual
3213: because rsync did not descend through that excluded section of the
3214: hierarchy. This is particularly important when using a trailing \(cq\&*\(cq\& rule.
3215: For instance, this won\(cq\&t work:
3216: .PP
3217: .RS
3218: \f(CW+ /some/path/this\-file\-will\-not\-be\-found\fP
3219: .br
3220: \f(CW+ /file\-is\-included\fP
3221: .br
3222: \f(CW\- *\fP
3223: .br
3224: .RE
3225:
3226: .PP
3227: This fails because the parent directory \(dq\&some\(dq\& is excluded by the \(cq\&*\(cq\&
3228: rule, so rsync never visits any of the files in the \(dq\&some\(dq\& or \(dq\&some/path\(dq\&
3229: directories. One solution is to ask for all directories in the hierarchy
3230: to be included by using a single rule: \(dq\&+ */\(dq\& (put it somewhere before the
3231: \(dq\&\- *\(dq\& rule), and perhaps use the \fB\-\-prune\-empty\-dirs\fP option. Another
3232: solution is to add specific include rules for all
3233: the parent dirs that need to be visited. For instance, this set of rules
3234: works fine:
3235: .PP
3236: .RS
3237: \f(CW+ /some/\fP
3238: .br
3239: \f(CW+ /some/path/\fP
3240: .br
3241: \f(CW+ /some/path/this\-file\-is\-found\fP
3242: .br
3243: \f(CW+ /file\-also\-included\fP
3244: .br
3245: \f(CW\- *\fP
3246: .br
3247: .RE
3248:
3249: .PP
3250: Here are some examples of exclude/include matching:
3251: .PP
3252: .IP o
3253: \(dq\&\- *.o\(dq\& would exclude all names matching *.o
3254: .IP o
3255: \(dq\&\- /foo\(dq\& would exclude a file (or directory) named foo in the
3256: transfer\-root directory
3257: .IP o
3258: \(dq\&\- foo/\(dq\& would exclude any directory named foo
3259: .IP o
3260: \(dq\&\- /foo/*/bar\(dq\& would exclude any file named bar which is at two
3261: levels below a directory named foo in the transfer\-root directory
3262: .IP o
3263: \(dq\&\- /foo/**/bar\(dq\& would exclude any file named bar two
3264: or more levels below a directory named foo in the transfer\-root directory
3265: .IP o
3266: The combination of \(dq\&+ */\(dq\&, \(dq\&+ *.c\(dq\&, and \(dq\&\- *\(dq\& would include all
3267: directories and C source files but nothing else (see also the
3268: \fB\-\-prune\-empty\-dirs\fP option)
3269: .IP o
3270: The combination of \(dq\&+ foo/\(dq\&, \(dq\&+ foo/bar.c\(dq\&, and \(dq\&\- *\(dq\& would include
3271: only the foo directory and foo/bar.c (the foo directory must be
3272: explicitly included or it would be excluded by the \(dq\&*\(dq\&)
3273:
3274: .PP
3275: The following modifiers are accepted after a \(dq\&+\(dq\& or \(dq\&\-\(dq\&:
3276: .PP
3277: .IP o
3278: A \fB/\fP specifies that the include/exclude rule should be matched
3279: against the absolute pathname of the current item. For example,
3280: \(dq\&\-/ /etc/passwd\(dq\& would exclude the passwd file any time the transfer
3281: was sending files from the \(dq\&/etc\(dq\& directory, and \(dq\&\-/ subdir/foo\(dq\&
3282: would always exclude \(dq\&foo\(dq\& when it is in a dir named \(dq\&subdir\(dq\&, even
3283: if \(dq\&foo\(dq\& is at the root of the current transfer.
3284: .IP o
3285: A \fB!\fP specifies that the include/exclude should take effect if
3286: the pattern fails to match. For instance, \(dq\&\-! */\(dq\& would exclude all
3287: non\-directories.
3288: .IP o
3289: A \fBC\fP is used to indicate that all the global CVS\-exclude rules
3290: should be inserted as excludes in place of the \(dq\&\-C\(dq\&. No arg should
3291: follow.
3292: .IP o
3293: An \fBs\fP is used to indicate that the rule applies to the sending
3294: side. When a rule affects the sending side, it prevents files from
3295: being transferred. The default is for a rule to affect both sides
3296: unless \fB\-\-delete\-excluded\fP was specified, in which case default rules
3297: become sender\-side only. See also the hide (H) and show (S) rules,
3298: which are an alternate way to specify sending\-side includes/excludes.
3299: .IP o
3300: An \fBr\fP is used to indicate that the rule applies to the receiving
3301: side. When a rule affects the receiving side, it prevents files from
3302: being deleted. See the \fBs\fP modifier for more info. See also the
3303: protect (P) and risk (R) rules, which are an alternate way to
3304: specify receiver\-side includes/excludes.
3305: .IP o
3306: A \fBp\fP indicates that a rule is perishable, meaning that it is
3307: ignored in directories that are being deleted. For instance, the \fB\-C\fP
3308: option\(cq\&s default rules that exclude things like \(dq\&CVS\(dq\& and \(dq\&*.o\(dq\& are
3309: marked as perishable, and will not prevent a directory that was removed
3310: on the source from being deleted on the destination.
3311:
3312: .PP
3313: .SH "MERGE\-FILE FILTER RULES"
3314:
3315: .PP
3316: You can merge whole files into your filter rules by specifying either a
3317: merge (.) or a dir\-merge (:) filter rule (as introduced in the FILTER RULES
3318: section above).
3319: .PP
3320: There are two kinds of merged files \-\- single\-instance (\(cq\&.\(cq\&) and
3321: per\-directory (\(cq\&:\(cq\&). A single\-instance merge file is read one time, and
3322: its rules are incorporated into the filter list in the place of the \(dq\&.\(dq\&
3323: rule. For per\-directory merge files, rsync will scan every directory that
3324: it traverses for the named file, merging its contents when the file exists
3325: into the current list of inherited rules. These per\-directory rule files
3326: must be created on the sending side because it is the sending side that is
3327: being scanned for the available files to transfer. These rule files may
3328: also need to be transferred to the receiving side if you want them to
3329: affect what files don\(cq\&t get deleted (see PER\-DIRECTORY RULES AND DELETE
3330: below).
3331: .PP
3332: Some examples:
3333: .PP
3334: .RS
3335: \f(CWmerge /etc/rsync/default.rules\fP
3336: .br
3337: \f(CW. /etc/rsync/default.rules\fP
3338: .br
3339: \f(CWdir\-merge .per\-dir\-filter\fP
3340: .br
3341: \f(CWdir\-merge,n\- .non\-inherited\-per\-dir\-excludes\fP
3342: .br
3343: \f(CW:n\- .non\-inherited\-per\-dir\-excludes\fP
3344: .br
3345: .RE
3346:
3347: .PP
3348: The following modifiers are accepted after a merge or dir\-merge rule:
3349: .PP
3350: .IP o
3351: A \fB\-\fP specifies that the file should consist of only exclude
3352: patterns, with no other rule\-parsing except for in\-file comments.
3353: .IP o
3354: A \fB+\fP specifies that the file should consist of only include
3355: patterns, with no other rule\-parsing except for in\-file comments.
3356: .IP o
3357: A \fBC\fP is a way to specify that the file should be read in a
3358: CVS\-compatible manner. This turns on \(cq\&n\(cq\&, \(cq\&w\(cq\&, and \(cq\&\-\(cq\&, but also
3359: allows the list\-clearing token (!) to be specified. If no filename is
3360: provided, \(dq\&.cvsignore\(dq\& is assumed.
3361: .IP o
3362: A \fBe\fP will exclude the merge\-file name from the transfer; e.g.
3363: \(dq\&dir\-merge,e .rules\(dq\& is like \(dq\&dir\-merge .rules\(dq\& and \(dq\&\- .rules\(dq\&.
3364: .IP o
3365: An \fBn\fP specifies that the rules are not inherited by subdirectories.
3366: .IP o
3367: A \fBw\fP specifies that the rules are word\-split on whitespace instead
3368: of the normal line\-splitting. This also turns off comments. Note: the
3369: space that separates the prefix from the rule is treated specially, so
3370: \(dq\&\- foo + bar\(dq\& is parsed as two rules (assuming that prefix\-parsing wasn\(cq\&t
3371: also disabled).
3372: .IP o
3373: You may also specify any of the modifiers for the \(dq\&+\(dq\& or \(dq\&\-\(dq\& rules
3374: (above) in order to have the rules that are read in from the file
3375: default to having that modifier set (except for the \fB!\fP modifier, which
3376: would not be useful). For instance, \(dq\&merge,\-/ .excl\(dq\& would
3377: treat the contents of .excl as absolute\-path excludes,
3378: while \(dq\&dir\-merge,s .filt\(dq\& and \(dq\&:sC\(dq\& would each make all their
3379: per\-directory rules apply only on the sending side. If the merge rule
3380: specifies sides to affect (via the \fBs\fP or \fBr\fP modifier or both),
3381: then the rules in the file must not specify sides (via a modifier or
3382: a rule prefix such as \fBhide\fP).
3383:
3384: .PP
3385: Per\-directory rules are inherited in all subdirectories of the directory
3386: where the merge\-file was found unless the \(cq\&n\(cq\& modifier was used. Each
3387: subdirectory\(cq\&s rules are prefixed to the inherited per\-directory rules
3388: from its parents, which gives the newest rules a higher priority than the
3389: inherited rules. The entire set of dir\-merge rules are grouped together in
3390: the spot where the merge\-file was specified, so it is possible to override
3391: dir\-merge rules via a rule that got specified earlier in the list of global
3392: rules. When the list\-clearing rule (\(dq\&!\(dq\&) is read from a per\-directory
3393: file, it only clears the inherited rules for the current merge file.
3394: .PP
3395: Another way to prevent a single rule from a dir\-merge file from being inherited is to
3396: anchor it with a leading slash. Anchored rules in a per\-directory
3397: merge\-file are relative to the merge\-file\(cq\&s directory, so a pattern \(dq\&/foo\(dq\&
3398: would only match the file \(dq\&foo\(dq\& in the directory where the dir\-merge filter
3399: file was found.
3400: .PP
3401: Here\(cq\&s an example filter file which you\(cq\&d specify via \fB\-\-filter=\(dq\&. file\(dq\&:\fP
3402: .PP
3403: .RS
3404: \f(CWmerge /home/user/.global\-filter\fP
3405: .br
3406: \f(CW\- *.gz\fP
3407: .br
3408: \f(CWdir\-merge .rules\fP
3409: .br
3410: \f(CW+ *.[ch]\fP
3411: .br
3412: \f(CW\- *.o\fP
3413: .br
3414: .RE
3415:
3416: .PP
3417: This will merge the contents of the /home/user/.global\-filter file at the
3418: start of the list and also turns the \(dq\&.rules\(dq\& filename into a per\-directory
3419: filter file. All rules read in prior to the start of the directory scan
3420: follow the global anchoring rules (i.e. a leading slash matches at the root
3421: of the transfer).
3422: .PP
3423: If a per\-directory merge\-file is specified with a path that is a parent
3424: directory of the first transfer directory, rsync will scan all the parent
3425: dirs from that starting point to the transfer directory for the indicated
3426: per\-directory file. For instance, here is a common filter (see \fB\-F\fP):
3427: .PP
3428: .RS
3429: \f(CW\-\-filter='\&: /.rsync\-filter'\&\fP
3430: .RE
3431:
3432: .PP
3433: That rule tells rsync to scan for the file .rsync\-filter in all
3434: directories from the root down through the parent directory of the
3435: transfer prior to the start of the normal directory scan of the file in
3436: the directories that are sent as a part of the transfer. (Note: for an
3437: rsync daemon, the root is always the same as the module\(cq\&s \(dq\&path\(dq\&.)
3438: .PP
3439: Some examples of this pre\-scanning for per\-directory files:
3440: .PP
3441: .RS
3442: \f(CWrsync \-avF /src/path/ /dest/dir\fP
3443: .br
3444: \f(CWrsync \-av \-\-filter='\&: ../../.rsync\-filter'\& /src/path/ /dest/dir\fP
3445: .br
3446: \f(CWrsync \-av \-\-filter='\&: .rsync\-filter'\& /src/path/ /dest/dir\fP
3447: .br
3448: .RE
3449:
3450: .PP
3451: The first two commands above will look for \(dq\&.rsync\-filter\(dq\& in \(dq\&/\(dq\& and
3452: \(dq\&/src\(dq\& before the normal scan begins looking for the file in \(dq\&/src/path\(dq\&
3453: and its subdirectories. The last command avoids the parent\-dir scan
3454: and only looks for the \(dq\&.rsync\-filter\(dq\& files in each directory that is
3455: a part of the transfer.
3456: .PP
3457: If you want to include the contents of a \(dq\&.cvsignore\(dq\& in your patterns,
3458: you should use the rule \(dq\&:C\(dq\&, which creates a dir\-merge of the .cvsignore
3459: file, but parsed in a CVS\-compatible manner. You can
3460: use this to affect where the \fB\-\-cvs\-exclude\fP (\fB\-C\fP) option\(cq\&s inclusion of the
3461: per\-directory .cvsignore file gets placed into your rules by putting the
3462: \(dq\&:C\(dq\& wherever you like in your filter rules. Without this, rsync would
3463: add the dir\-merge rule for the .cvsignore file at the end of all your other
3464: rules (giving it a lower priority than your command\-line rules). For
3465: example:
3466: .PP
3467: .RS
3468: \f(CWcat <<EOT | rsync \-avC \-\-filter='\&. \-'\& a/ b\fP
3469: .br
3470: \f(CW+ foo.o\fP
3471: .br
3472: \f(CW:C\fP
3473: .br
3474: \f(CW\- *.old\fP
3475: .br
3476: \f(CWEOT\fP
3477: .br
3478: \f(CWrsync \-avC \-\-include=foo.o \-f :C \-\-exclude='\&*.old'\& a/ b\fP
3479: .br
3480: .RE
3481:
3482: .PP
3483: Both of the above rsync commands are identical. Each one will merge all
3484: the per\-directory .cvsignore rules in the middle of the list rather than
3485: at the end. This allows their dir\-specific rules to supersede the rules
3486: that follow the :C instead of being subservient to all your rules. To
3487: affect the other CVS exclude rules (i.e. the default list of exclusions,
3488: the contents of $HOME/.cvsignore, and the value of $CVSIGNORE) you should
3489: omit the \fB\-C\fP command\-line option and instead insert a \(dq\&\-C\(dq\& rule into
3490: your filter rules; e.g. \(dq\&\fB\-\-filter=\-C\fP\(dq\&.
3491: .PP
3492: .SH "LIST\-CLEARING FILTER RULE"
3493:
3494: .PP
3495: You can clear the current include/exclude list by using the \(dq\&!\(dq\& filter
3496: rule (as introduced in the FILTER RULES section above). The \(dq\¤t\(dq\&
3497: list is either the global list of rules (if the rule is encountered while
3498: parsing the filter options) or a set of per\-directory rules (which are
3499: inherited in their own sub\-list, so a subdirectory can use this to clear
3500: out the parent\(cq\&s rules).
3501: .PP
3502: .SH "ANCHORING INCLUDE/EXCLUDE PATTERNS"
3503:
3504: .PP
3505: As mentioned earlier, global include/exclude patterns are anchored at the
3506: \(dq\&root of the transfer\(dq\& (as opposed to per\-directory patterns, which are
3507: anchored at the merge\-file\(cq\&s directory). If you think of the transfer as
3508: a subtree of names that are being sent from sender to receiver, the
3509: transfer\-root is where the tree starts to be duplicated in the destination
3510: directory. This root governs where patterns that start with a / match.
3511: .PP
3512: Because the matching is relative to the transfer\-root, changing the
3513: trailing slash on a source path or changing your use of the \fB\-\-relative\fP
3514: option affects the path you need to use in your matching (in addition to
3515: changing how much of the file tree is duplicated on the destination
3516: host). The following examples demonstrate this.
3517: .PP
3518: Let\(cq\&s say that we want to match two source files, one with an absolute
3519: path of \(dq\&/home/me/foo/bar\(dq\&, and one with a path of \(dq\&/home/you/bar/baz\(dq\&.
3520: Here is how the various command choices differ for a 2\-source transfer:
3521: .PP
3522: .RS
3523: Example cmd: rsync \-a /home/me /home/you /dest
3524: .br
3525: +/\- pattern: /me/foo/bar
3526: .br
3527: +/\- pattern: /you/bar/baz
3528: .br
3529: Target file: /dest/me/foo/bar
3530: .br
3531: Target file: /dest/you/bar/baz
3532: .br
3533: .RE
3534:
3535: .PP
3536: .RS
3537: Example cmd: rsync \-a /home/me/ /home/you/ /dest
3538: .br
3539: +/\- pattern: /foo/bar (note missing \(dq\&me\(dq\&)
3540: .br
3541: +/\- pattern: /bar/baz (note missing \(dq\&you\(dq\&)
3542: .br
3543: Target file: /dest/foo/bar
3544: .br
3545: Target file: /dest/bar/baz
3546: .br
3547: .RE
3548:
3549: .PP
3550: .RS
3551: Example cmd: rsync \-a \-\-relative /home/me/ /home/you /dest
3552: .br
3553: +/\- pattern: /home/me/foo/bar (note full path)
3554: .br
3555: +/\- pattern: /home/you/bar/baz (ditto)
3556: .br
3557: Target file: /dest/home/me/foo/bar
3558: .br
3559: Target file: /dest/home/you/bar/baz
3560: .br
3561: .RE
3562:
3563: .PP
3564: .RS
3565: Example cmd: cd /home; rsync \-a \-\-relative me/foo you/ /dest
3566: .br
3567: +/\- pattern: /me/foo/bar (starts at specified path)
3568: .br
3569: +/\- pattern: /you/bar/baz (ditto)
3570: .br
3571: Target file: /dest/me/foo/bar
3572: .br
3573: Target file: /dest/you/bar/baz
3574: .br
3575: .RE
3576:
3577: .PP
3578: The easiest way to see what name you should filter is to just
3579: look at the output when using \fB\-\-verbose\fP and put a / in front of the name
3580: (use the \fB\-\-dry\-run\fP option if you\(cq\&re not yet ready to copy any files).
3581: .PP
3582: .SH "PER\-DIRECTORY RULES AND DELETE"
3583:
3584: .PP
3585: Without a delete option, per\-directory rules are only relevant on the
3586: sending side, so you can feel free to exclude the merge files themselves
3587: without affecting the transfer. To make this easy, the \(cq\&e\(cq\& modifier adds
3588: this exclude for you, as seen in these two equivalent commands:
3589: .PP
3590: .RS
3591: \f(CWrsync \-av \-\-filter='\&: .excl'\& \-\-exclude=.excl host:src/dir /dest\fP
3592: .br
3593: \f(CWrsync \-av \-\-filter='\&:e .excl'\& host:src/dir /dest\fP
3594: .br
3595: .RE
3596:
3597: .PP
3598: However, if you want to do a delete on the receiving side AND you want some
3599: files to be excluded from being deleted, you\(cq\&ll need to be sure that the
3600: receiving side knows what files to exclude. The easiest way is to include
3601: the per\-directory merge files in the transfer and use \fB\-\-delete\-after\fP,
3602: because this ensures that the receiving side gets all the same exclude
3603: rules as the sending side before it tries to delete anything:
3604: .PP
3605: .RS
3606: \f(CWrsync \-avF \-\-delete\-after host:src/dir /dest\fP
3607: .RE
3608:
3609: .PP
3610: However, if the merge files are not a part of the transfer, you\(cq\&ll need to
3611: either specify some global exclude rules (i.e. specified on the command
3612: line), or you\(cq\&ll need to maintain your own per\-directory merge files on
3613: the receiving side. An example of the first is this (assume that the
3614: remote .rules files exclude themselves):
3615: .PP
3616: .nf
3617: rsync \-av \-\-filter=\(cq\&: .rules\(cq\& \-\-filter=\(cq\&. /my/extra.rules\(cq\&
3618: \-\-delete host:src/dir /dest
3619: .fi
3620:
3621: .PP
3622: In the above example the extra.rules file can affect both sides of the
3623: transfer, but (on the sending side) the rules are subservient to the rules
3624: merged from the .rules files because they were specified after the
3625: per\-directory merge rule.
3626: .PP
3627: In one final example, the remote side is excluding the .rsync\-filter
3628: files from the transfer, but we want to use our own .rsync\-filter files
3629: to control what gets deleted on the receiving side. To do this we must
3630: specifically exclude the per\-directory merge files (so that they don\(cq\&t get
3631: deleted) and then put rules into the local files to control what else
3632: should not get deleted. Like one of these commands:
3633: .PP
3634: .nf
3635: rsync \-av \-\-filter='\&:e /.rsync\-filter'\& \-\-delete \e
3636: host:src/dir /dest
3637: rsync \-avFF \-\-delete host:src/dir /dest
3638: .fi
3639:
3640: .PP
3641: .SH "BATCH MODE"
3642:
3643: .PP
3644: Batch mode can be used to apply the same set of updates to many
3645: identical systems. Suppose one has a tree which is replicated on a
3646: number of hosts. Now suppose some changes have been made to this
3647: source tree and those changes need to be propagated to the other
3648: hosts. In order to do this using batch mode, rsync is run with the
3649: write\-batch option to apply the changes made to the source tree to one
3650: of the destination trees. The write\-batch option causes the rsync
3651: client to store in a \(dq\&batch file\(dq\& all the information needed to repeat
3652: this operation against other, identical destination trees.
3653: .PP
3654: Generating the batch file once saves having to perform the file
3655: status, checksum, and data block generation more than once when
3656: updating multiple destination trees. Multicast transport protocols can
3657: be used to transfer the batch update files in parallel to many hosts
3658: at once, instead of sending the same data to every host individually.
3659: .PP
3660: To apply the recorded changes to another destination tree, run rsync
3661: with the read\-batch option, specifying the name of the same batch
3662: file, and the destination tree. Rsync updates the destination tree
3663: using the information stored in the batch file.
3664: .PP
3665: For your convenience, a script file is also created when the write\-batch
3666: option is used: it will be named the same as the batch file with \(dq\&.sh\(dq\&
3667: appended. This script file contains a command\-line suitable for updating a
3668: destination tree using the associated batch file. It can be executed using
3669: a Bourne (or Bourne\-like) shell, optionally passing in an alternate
3670: destination tree pathname which is then used instead of the original
3671: destination path. This is useful when the destination tree path on the
3672: current host differs from the one used to create the batch file.
3673: .PP
3674: Examples:
3675: .PP
3676: .RS
3677: \f(CW$ rsync \-\-write\-batch=foo \-a host:/source/dir/ /adest/dir/\fP
3678: .br
3679: \f(CW$ scp foo* remote:\fP
3680: .br
3681: \f(CW$ ssh remote ./foo.sh /bdest/dir/\fP
3682: .br
3683: .RE
3684:
3685: .PP
3686: .RS
3687: \f(CW$ rsync \-\-write\-batch=foo \-a /source/dir/ /adest/dir/\fP
3688: .br
3689: \f(CW$ ssh remote rsync \-\-read\-batch=\- \-a /bdest/dir/ <foo\fP
3690: .br
3691: .RE
3692:
3693: .PP
3694: In these examples, rsync is used to update /adest/dir/ from /source/dir/
3695: and the information to repeat this operation is stored in \(dq\&foo\(dq\& and
3696: \(dq\&foo.sh\(dq\&. The host \(dq\&remote\(dq\& is then updated with the batched data going
3697: into the directory /bdest/dir. The differences between the two examples
3698: reveals some of the flexibility you have in how you deal with batches:
3699: .PP
3700: .IP o
3701: The first example shows that the initial copy doesn\(cq\&t have to be
3702: local \-\- you can push or pull data to/from a remote host using either the
3703: remote\-shell syntax or rsync daemon syntax, as desired.
3704: .IP o
3705: The first example uses the created \(dq\&foo.sh\(dq\& file to get the right
3706: rsync options when running the read\-batch command on the remote host.
3707: .IP o
3708: The second example reads the batch data via standard input so that
3709: the batch file doesn\(cq\&t need to be copied to the remote machine first.
3710: This example avoids the foo.sh script because it needed to use a modified
3711: \fB\-\-read\-batch\fP option, but you could edit the script file if you wished to
3712: make use of it (just be sure that no other option is trying to use
3713: standard input, such as the \(dq\&\fB\-\-exclude\-from=\-\fP\(dq\& option).
3714:
3715: .PP
3716: Caveats:
3717: .PP
3718: The read\-batch option expects the destination tree that it is updating
3719: to be identical to the destination tree that was used to create the
3720: batch update fileset. When a difference between the destination trees
3721: is encountered the update might be discarded with a warning (if the file
3722: appears to be up\-to\-date already) or the file\-update may be attempted
3723: and then, if the file fails to verify, the update discarded with an
3724: error. This means that it should be safe to re\-run a read\-batch operation
3725: if the command got interrupted. If you wish to force the batched\-update to
3726: always be attempted regardless of the file\(cq\&s size and date, use the \fB\-I\fP
3727: option (when reading the batch).
3728: If an error occurs, the destination tree will probably be in a
3729: partially updated state. In that case, rsync can
3730: be used in its regular (non\-batch) mode of operation to fix up the
3731: destination tree.
3732: .PP
3733: The rsync version used on all destinations must be at least as new as the
3734: one used to generate the batch file. Rsync will die with an error if the
3735: protocol version in the batch file is too new for the batch\-reading rsync
3736: to handle. See also the \fB\-\-protocol\fP option for a way to have the
3737: creating rsync generate a batch file that an older rsync can understand.
3738: (Note that batch files changed format in version 2.6.3, so mixing versions
3739: older than that with newer versions will not work.)
3740: .PP
3741: When reading a batch file, rsync will force the value of certain options
3742: to match the data in the batch file if you didn\(cq\&t set them to the same
3743: as the batch\-writing command. Other options can (and should) be changed.
3744: For instance \fB\-\-write\-batch\fP changes to \fB\-\-read\-batch\fP,
3745: \fB\-\-files\-from\fP is dropped, and the
3746: \fB\-\-filter\fP/\fB\-\-include\fP/\fB\-\-exclude\fP options are not needed unless
3747: one of the \fB\-\-delete\fP options is specified.
3748: .PP
3749: The code that creates the BATCH.sh file transforms any filter/include/exclude
3750: options into a single list that is appended as a \(dq\&here\(dq\& document to the
3751: shell script file. An advanced user can use this to modify the exclude
3752: list if a change in what gets deleted by \fB\-\-delete\fP is desired. A normal
3753: user can ignore this detail and just use the shell script as an easy way
3754: to run the appropriate \fB\-\-read\-batch\fP command for the batched data.
3755: .PP
3756: The original batch mode in rsync was based on \(dq\&rsync+\(dq\&, but the latest
3757: version uses a new implementation.
3758: .PP
3759: .SH "SYMBOLIC LINKS"
3760:
3761: .PP
3762: Three basic behaviors are possible when rsync encounters a symbolic
3763: link in the source directory.
3764: .PP
3765: By default, symbolic links are not transferred at all. A message
3766: \(dq\&skipping non\-regular\(dq\& file is emitted for any symlinks that exist.
3767: .PP
3768: If \fB\-\-links\fP is specified, then symlinks are recreated with the same
3769: target on the destination. Note that \fB\-\-archive\fP implies
3770: \fB\-\-links\fP.
3771: .PP
3772: If \fB\-\-copy\-links\fP is specified, then symlinks are \(dq\&collapsed\(dq\& by
3773: copying their referent, rather than the symlink.
3774: .PP
3775: Rsync can also distinguish \(dq\&safe\(dq\& and \(dq\&unsafe\(dq\& symbolic links. An
3776: example where this might be used is a web site mirror that wishes to
3777: ensure that the rsync module that is copied does not include symbolic links to
3778: \fB/etc/passwd\fP in the public section of the site. Using
3779: \fB\-\-copy\-unsafe\-links\fP will cause any links to be copied as the file
3780: they point to on the destination. Using \fB\-\-safe\-links\fP will cause
3781: unsafe links to be omitted altogether. (Note that you must specify
3782: \fB\-\-links\fP for \fB\-\-safe\-links\fP to have any effect.)
3783: .PP
3784: Symbolic links are considered unsafe if they are absolute symlinks
3785: (start with \fB/\fP), empty, or if they contain enough \(dq\&..\(dq\&
3786: components to ascend from the directory being copied.
3787: .PP
3788: Here\(cq\&s a summary of how the symlink options are interpreted. The list is
3789: in order of precedence, so if your combination of options isn\(cq\&t mentioned,
3790: use the first line that is a complete subset of your options:
3791: .PP
3792: .IP "\fB\-\-copy\-links\fP"
3793: Turn all symlinks into normal files (leaving no
3794: symlinks for any other options to affect).
3795: .PP
3796: .IP "\fB\-\-links \-\-copy\-unsafe\-links\fP"
3797: Turn all unsafe symlinks into files
3798: and duplicate all safe symlinks.
3799: .PP
3800: .IP "\fB\-\-copy\-unsafe\-links\fP"
3801: Turn all unsafe symlinks into files, noisily
3802: skip all safe symlinks.
3803: .PP
3804: .IP "\fB\-\-links \-\-safe\-links\fP"
3805: Duplicate safe symlinks and skip unsafe
3806: ones.
3807: .PP
3808: .IP "\fB\-\-links\fP"
3809: Duplicate all symlinks.
3810: .PP
3811: .SH "DIAGNOSTICS"
3812:
3813: .PP
3814: rsync occasionally produces error messages that may seem a little
3815: cryptic. The one that seems to cause the most confusion is \(dq\&protocol
3816: version mismatch \-\- is your shell clean?\(dq\&.
3817: .PP
3818: This message is usually caused by your startup scripts or remote shell
3819: facility producing unwanted garbage on the stream that rsync is using
3820: for its transport. The way to diagnose this problem is to run your
3821: remote shell like this:
3822: .PP
3823: .RS
3824: \f(CWssh remotehost /bin/true > out.dat\fP
3825: .RE
3826:
3827: .PP
3828: then look at out.dat. If everything is working correctly then out.dat
3829: should be a zero length file. If you are getting the above error from
3830: rsync then you will probably find that out.dat contains some text or
3831: data. Look at the contents and try to work out what is producing
3832: it. The most common cause is incorrectly configured shell startup
3833: scripts (such as .cshrc or .profile) that contain output statements
3834: for non\-interactive logins.
3835: .PP
3836: If you are having trouble debugging filter patterns, then
3837: try specifying the \fB\-vv\fP option. At this level of verbosity rsync will
3838: show why each individual file is included or excluded.
3839: .PP
3840: .SH "EXIT VALUES"
3841:
3842: .PP
3843: .IP "\fB0\fP"
3844: Success
3845: .IP "\fB1\fP"
3846: Syntax or usage error
3847: .IP "\fB2\fP"
3848: Protocol incompatibility
3849: .IP "\fB3\fP"
3850: Errors selecting input/output files, dirs
3851: .IP "\fB4\fP"
3852: Requested action not supported: an attempt
3853: was made to manipulate 64\-bit files on a platform that cannot support
3854: them; or an option was specified that is supported by the client and
3855: not by the server.
3856: .IP "\fB5\fP"
3857: Error starting client\-server protocol
3858: .IP "\fB6\fP"
3859: Daemon unable to append to log\-file
3860: .IP "\fB10\fP"
3861: Error in socket I/O
3862: .IP "\fB11\fP"
3863: Error in file I/O
3864: .IP "\fB12\fP"
3865: Error in rsync protocol data stream
3866: .IP "\fB13\fP"
3867: Errors with program diagnostics
3868: .IP "\fB14\fP"
3869: Error in IPC code
3870: .IP "\fB20\fP"
3871: Received SIGUSR1 or SIGINT
3872: .IP "\fB21\fP"
3873: Some error returned by
3874: \f(CWwaitpid()\fP
3875: .IP "\fB22\fP"
3876: Error allocating core memory buffers
3877: .IP "\fB23\fP"
3878: Partial transfer due to error
3879: .IP "\fB24\fP"
3880: Partial transfer due to vanished source files
3881: .IP "\fB25\fP"
3882: The \-\-max\-delete limit stopped deletions
3883: .IP "\fB30\fP"
3884: Timeout in data send/receive
3885: .IP "\fB35\fP"
3886: Timeout waiting for daemon connection
3887:
3888: .PP
3889: .SH "ENVIRONMENT VARIABLES"
3890:
3891: .PP
3892: .IP "\fBCVSIGNORE\fP"
3893: The CVSIGNORE environment variable supplements any
3894: ignore patterns in .cvsignore files. See the \fB\-\-cvs\-exclude\fP option for
3895: more details.
3896: .IP "\fBRSYNC_ICONV\fP"
3897: Specify a default \fB\-\-iconv\fP setting using this
3898: environment variable. (First supported in 3.0.0.)
1.1.1.2 misho 3899: .IP "\fBRSYNC_PROTECT_ARGS\fP"
3900: Specify a non\-zero numeric value if you want the
3901: \fB\-\-protect\-args\fP option to be enabled by default, or a zero value to make
3902: sure that it is disabled by default. (First supported in 3.1.0.)
1.1 misho 3903: .IP "\fBRSYNC_RSH\fP"
3904: The RSYNC_RSH environment variable allows you to
3905: override the default shell used as the transport for rsync. Command line
3906: options are permitted after the command name, just as in the \fB\-e\fP option.
3907: .IP "\fBRSYNC_PROXY\fP"
3908: The RSYNC_PROXY environment variable allows you to
3909: redirect your rsync client to use a web proxy when connecting to a
3910: rsync daemon. You should set RSYNC_PROXY to a hostname:port pair.
3911: .IP "\fBRSYNC_PASSWORD\fP"
3912: Setting RSYNC_PASSWORD to the required
3913: password allows you to run authenticated rsync connections to an rsync
3914: daemon without user intervention. Note that this does not supply a
3915: password to a remote shell transport such as ssh; to learn how to do that,
3916: consult the remote shell\(cq\&s documentation.
3917: .IP "\fBUSER\fP or \fBLOGNAME\fP"
3918: The USER or LOGNAME environment variables
3919: are used to determine the default username sent to an rsync daemon.
3920: If neither is set, the username defaults to \(dq\&nobody\(dq\&.
3921: .IP "\fBHOME\fP"
3922: The HOME environment variable is used to find the user\(cq\&s
3923: default .cvsignore file.
3924:
3925: .PP
3926: .SH "FILES"
3927:
3928: .PP
3929: /etc/rsyncd.conf or rsyncd.conf
3930: .PP
3931: .SH "SEE ALSO"
3932:
3933: .PP
3934: \fBrsyncd.conf\fP(5)
3935: .PP
3936: .SH "BUGS"
3937:
3938: .PP
3939: times are transferred as *nix time_t values
3940: .PP
3941: When transferring to FAT filesystems rsync may re\-sync
3942: unmodified files.
3943: See the comments on the \fB\-\-modify\-window\fP option.
3944: .PP
3945: file permissions, devices, etc. are transferred as native numerical
3946: values
3947: .PP
3948: see also the comments on the \fB\-\-delete\fP option
3949: .PP
3950: Please report bugs! See the web site at
3951: http://rsync.samba.org/
3952: .PP
3953: .SH "VERSION"
3954:
3955: .PP
1.1.1.3 ! misho 3956: This man page is current for version 3.1.2 of rsync.
1.1 misho 3957: .PP
3958: .SH "INTERNAL OPTIONS"
3959:
3960: .PP
3961: The options \fB\-\-server\fP and \fB\-\-sender\fP are used internally by rsync,
3962: and should never be typed by a user under normal circumstances. Some
3963: awareness of these options may be needed in certain scenarios, such as
3964: when setting up a login that can only run an rsync command. For instance,
3965: the support directory of the rsync distribution has an example script
3966: named rrsync (for restricted rsync) that can be used with a restricted
3967: ssh login.
3968: .PP
3969: .SH "CREDITS"
3970:
3971: .PP
1.1.1.2 misho 3972: rsync is distributed under the GNU General Public License. See the file
1.1 misho 3973: COPYING for details.
3974: .PP
3975: A WEB site is available at
3976: http://rsync.samba.org/. The site
3977: includes an FAQ\-O\-Matic which may cover questions unanswered by this
3978: manual page.
3979: .PP
3980: The primary ftp site for rsync is
3981: ftp://rsync.samba.org/pub/rsync.
3982: .PP
3983: We would be delighted to hear from you if you like this program.
3984: Please contact the mailing\-list at rsync@lists.samba.org.
3985: .PP
3986: This program uses the excellent zlib compression library written by
3987: Jean\-loup Gailly and Mark Adler.
3988: .PP
3989: .SH "THANKS"
3990:
3991: .PP
3992: Special thanks go out to: John Van Essen, Matt McCutchen, Wesley W. Terpstra,
3993: David Dykstra, Jos Backus, Sebastian Krahmer, Martin Pool, and our
3994: gone\-but\-not\-forgotten compadre, J.W. Schultz.
3995: .PP
3996: Thanks also to Richard Brent, Brendan Mackay, Bill Waite, Stephen Rothwell
3997: and David Bell. I\(cq\&ve probably missed some people, my apologies if I have.
3998: .PP
3999: .SH "AUTHOR"
4000:
4001: .PP
4002: rsync was originally written by Andrew Tridgell and Paul Mackerras.
4003: Many people have later contributed to it. It is currently maintained
4004: by Wayne Davison.
4005: .PP
4006: Mailing lists for support and development are available at
4007: http://lists.samba.org
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>