embedaddon/rsync/rsync.1.html - view

File: [ELWIX - Embedded LightWeight unIX -] / embedaddon / rsync / rsync.1.html
Revision 1.1.1.1 (vendor branch): download - view: text, annotated - select for diffs - revision graph
Wed Mar 17 00:32:36 2021 UTC (3 years, 3 months ago) by misho
Branches: rsync, MAIN
CVS tags: v3_2_3, HEAD

rsync 3.2.3

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