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