embedaddon/rsync/rsync.1 - view

File: [ELWIX - Embedded LightWeight unIX -] / embedaddon / rsync / rsync.1
Revision 1.1.1.2 (vendor branch): download - view: text, annotated - select for diffs - revision graph
Mon Oct 14 07:51:14 2013 UTC (10 years, 8 months ago) by misho
Branches: rsync, MAIN
CVS tags: RSYNC3_1_0, HEAD

v 3.1.0

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