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