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