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