X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/2d81114b23021d1e51a8b5fc7c4871126680e13d..2a5d5a8cc4ad251d8d29e45e4be3d9c39228715b:/rsync.yo diff --git a/rsync.yo b/rsync.yo index 0cad5bda..486ffae3 100644 --- a/rsync.yo +++ b/rsync.yo @@ -1,5 +1,5 @@ mailto(rsync-bugs@samba.org) -manpage(rsync)(1)(28 Feb 2005)()() +manpage(rsync)(1)(30 Mar 2005)()() manpagename(rsync)(faster, flexible replacement for rcp) manpagesynopsis() @@ -297,7 +297,6 @@ Here is a short summary of the options available in rsync. Please refer to the detailed description below for a complete description. verb( -v, --verbose increase verbosity -q, --quiet suppress non-error messages - -c, --checksum always checksum -c, --checksum skip based on checksum, not mod-time & size -a, --archive archive mode; same as -rlptgoD (no -H) -r, --recursive recurse into directories @@ -329,7 +328,7 @@ to the detailed description below for a complete description. verb( -x, --one-file-system don't cross filesystem boundaries -B, --block-size=SIZE force a fixed checksum block-size -e, --rsh=COMMAND specify the remote shell to use - --rsync-path=PATH specify path to rsync on the remote machine + --rsync-path=PROGRAM specify the rsync to run on remote machine --existing only update files that already exist --ignore-existing ignore files that already exist on receiver --remove-sent-files sent files/symlinks are removed from sender @@ -354,6 +353,7 @@ to the detailed description below for a complete description. verb( -T, --temp-dir=DIR create temporary files in directory DIR -y, --fuzzy find similar file for basis if no dest file --compare-dest=DIR also compare received files relative to DIR + --copy-dest=DIR ... and include copies of unchanged files --link-dest=DIR hardlink to files in DIR when unchanged -z, --compress compress file data during the transfer -C, --cvs-exclude auto-ignore files in the same way CVS does @@ -367,6 +367,7 @@ to the detailed description below for a complete description. verb( --files-from=FILE read list of source-file names from FILE -0, --from0 all *from file lists are delimited by nulls --version print version number + --address=ADDRESS bind address for outgoing socket to daemon --port=PORT specify double-colon alternate port number --blocking-io use blocking I/O for the remote shell --no-blocking-io turn off blocking I/O when it is default @@ -379,7 +380,9 @@ to the detailed description below for a complete description. verb( --list-only list the files instead of copying them --bwlimit=KBPS limit I/O bandwidth; KBytes per second --write-batch=FILE write a batched update to FILE + --only-write-batch=FILE like --write-batch but w/o updating dest --read-batch=FILE read a batched update from FILE + --protocol=NUM force an older protocol version to be used --checksum-seed=NUM set block/file checksum seed (advanced) -4, --ipv4 prefer IPv4 -6, --ipv6 prefer IPv6 @@ -750,8 +753,8 @@ is only relevant without bf(--delete) because deletions are now done depth-first Requires the bf(--recursive) option (which is implied by bf(-a)) to have any effect. dit(bf(--max-delete=NUM)) This tells rsync not to delete more than NUM -files or directories. This is useful when mirroring very large trees -to prevent disasters. +files or directories (NUM must be non-zero). +This is useful when mirroring very large trees to prevent disasters. dit(bf(--max-size=SIZE)) This tells rsync to avoid transferring any file that is larger than the specified SIZE. The SIZE value can be @@ -787,10 +790,18 @@ environment variable, which accepts the same range of values as bf(-e). See also the bf(--blocking-io) option which is affected by this option. -dit(bf(--rsync-path=PATH)) Use this to specify the path to the copy of -rsync on the remote machine. Useful when it's not in your path. Note -that this is the full path to the binary, not just the directory that -the binary is in. +dit(bf(--rsync-path=PROGRAM)) Use this to specify what program is to be run +on the remote machine to start-up rsync. Often used when rsync is not in +the default remote-shell's path (e.g. --rsync-path=/usr/local/bin/rsync). +Note that PROGRAM is run with the help of a shell, so it can be any +program, script, or command sequence you'd care to run, so long as it does +not corrupt the standard-in & standard-out that rsync is using to +communicate. + +One tricky example is to set a different default directory on the remote +machine for use with the bf(--relative) option. For instance: + +quote(tt( rsync -avR --rsync-path="cd /a/b && rsync" hst:c/d /e/)) dit(bf(-C, --cvs-exclude)) This is a useful shorthand for excluding a broad range of files that you often don't want to transfer between @@ -814,7 +825,7 @@ See the bf(cvs(1)) manual for more information. If you're combining bf(-C) with your own bf(--filter) rules, you should note that these CVS excludes are appended at the end of your own rules, -regardless of where the -C was placed on the command-line. This makes them +regardless of where the bf(-C) was placed on the command-line. This makes them a lower priority than any rules you specified explicitly. If you want to control where these CVS excludes get inserted into your filter rules, you should omit the bf(-C) as a command-line option and use a combination of @@ -945,14 +956,32 @@ directory. This is useful for creating a sparse backup of just files that have changed from an earlier backup. Beginning in version 2.6.4, multiple bf(--compare-dest) directories may be -provided and rsync will search the list in the order specified until it -finds an existing file. That first discovery is used as the basis file, -and also determines if the transfer needs to happen. +provided, which will cause rsync to search the list in the order specified +for an exact match. +If a match is found that differs only in attributes, a local copy is made +and the attributes updated. +If a match is not found, a basis file from one of the em(DIR)s will be +selected to try to speed up the transfer. + +If em(DIR) is a relative path, it is relative to the destination directory. +See also bf(--copy-dest) and bf(--link-dest). + +dit(bf(--copy-dest=DIR)) This option behaves like bf(--compare-dest), but +rsync will also copy unchanged files found in em(DIR) to the destination +directory using a local copy. +This is useful for doing transfers to a new destination while leaving +existing files intact, and then doing a flash-cutover when all files have +been successfully transferred. + +Multiple bf(--copy-dest) directories may be provided, which will cause +rsync to search the list in the order specified for an unchanged file. +If a match is not found, a basis file from one of the em(DIR)s will be +selected to try to speed up the transfer. If em(DIR) is a relative path, it is relative to the destination directory. -See also bf(--link-dest). +See also bf(--compare-dest) and bf(--link-dest). -dit(bf(--link-dest=DIR)) This option behaves like bf(--compare-dest), but +dit(bf(--link-dest=DIR)) This option behaves like bf(--copy-dest), but unchanged files are hard linked from em(DIR) to the destination directory. The files must be identical in all preserved attributes (e.g. permissions, possibly ownership) in order for the files to be linked together. @@ -960,13 +989,16 @@ An example: quote(tt( rsync -av --link-dest=$PWD/prior_dir host:src_dir/ new_dir/)) -Beginning with version 2.6.4, if more than one bf(--link-dest) option is -specified, rsync will try to find an exact match to link with (searching -the list in the order specified), and if not found, a basis file from one -of the em(DIR)s will be selected to try to speed up the transfer. +Beginning in version 2.6.4, multiple bf(--link-dest) directories may be +provided, which will cause rsync to search the list in the order specified +for an exact match. +If a match is found that differs only in attributes, a local copy is made +and the attributes updated. +If a match is not found, a basis file from one of the em(DIR)s will be +selected to try to speed up the transfer. If em(DIR) is a relative path, it is relative to the destination directory. -See also bf(--compare-dest). +See also bf(--compare-dest) and bf(--copy-dest). Note that rsync versions prior to 2.6.1 had a bug that could prevent bf(--link-dest) from working properly for a non-root user when bf(-o) was specified @@ -1002,6 +1034,11 @@ dit(bf(--timeout=TIMEOUT)) This option allows you to set a maximum I/O timeout in seconds. If no data is transferred for the specified time then rsync will exit. The default is 0, which means no timeout. +dit(bf(--address)) By default rsync will bind to the wildcard address when +connecting to an rsync daemon. The bf(--address) option allows you to +specify a specific IP address (or hostname) to bind to. See also this +option in the bf(--daemon) mode section. + dit(bf(--port=PORT)) This specifies an alternate TCP port number to use rather than the default of 873. This is only needed if you are using the double-colon (::) syntax to connect with an rsync daemon (since the URL @@ -1021,25 +1058,35 @@ dit(bf(-i, --itemize-changes)) Requests a simple itemized list of the changes that are being made to each file, including attribute changes. This is exactly the same as specifying bf(--log-format='%i %n%L'). -The "%i" escape has a cryptic output that is 8 letters long. The general -format is as follows: +The "%i" escape has a cryptic output that is 9 letters long. The general +format is like the string bf(UXcstpoga)), where bf(U) is replaced by the +kind of update being done, bf(X) is replaced by the file-type, and the +other letters represent attributes that may be output if they are being +modified. -quote(tt( =Xcstpog)) +The update types that replace the bf(U) are as follows: -The bf(=) is output as either a bf(<) (receive) or a bf(>) (send) if the -item is being transferred, a bf(.) if only the attributes are being -updated, or a bf(=) if the items are identical. Note that when a symlink -or a device gets its value changed, that is considered to be a transfer (as -opposed to a change in permissions, ownership, etc.). +quote(itemize( + it() A bf(<) means that a file is being transferred to the remote host + (sent). + it() A bf(>) means that a file is being transferred to the local host + (received). + it() A bf(c) means that a local change/creation is occuring for the item + (such as the creation of a directory or the changing of a symlink, etc.). + it() A bf(h) means that the item is a hard-link to another item (requires + bf(--hard-links)). + it() A bf(.) means that the item is not being updated (though it might + have attributes that are being modified). +)) -The bf(X) will be replaced by one of the following: an "f" for a file, a -"d" for a dir, an "L" for a symlink, or a "D" for a device. +The file-types that replace the bf(X) are: bf(f) for a file, a bf(d) for a +directory, an bf(L) for a symlink, and a bf(D) for a device. -The rest of the letters in the string above are the actual letters that +The other letters in the string above are the actual letters that will be output if the associated attribute for the item is being updated or a "." for no change. Three exceptions to this are: (1) a newly created -item replaces each letter with a "+", (2) an identical item replaces each -letter with a space, and (3) an unknown attribute replaces each letter with +item replaces each letter with a "+", (2) an identical item replaces the +dots with spaces, and (3) an unknown attribute replaces each letter with a "?" (this happens when talking to an older rsync). The attribute that is associated with each letter is as follows: @@ -1060,10 +1107,12 @@ quote(itemize( server's value (requires bf(--owner) and root privileges). it() A bf(g) means the group is different and is being updated to the server's value (requires bf(--group) and the authority to set the group). + it() The bf(a) is reserved for a future enhanced version that supports + extended file attributes, such as ACLs. )) One other output is possible: when deleting files, the "%i" will output -the string "deleting" for each item that is being removed (assuming that +the string "*deleting" for each item that is being removed (assuming that you are talking to a recent enough rsync that it logs deletions instead of outputting them as a verbose message). @@ -1227,13 +1276,38 @@ of zero specifies no limit. dit(bf(--write-batch=FILE)) Record a file that can later be applied to another identical destination with bf(--read-batch). See the "BATCH MODE" -section for details. +section for details, and also the bf(--only-write-batch) option. + +dit(bf(--only-write-batch=FILE)) Works like bf(--write-batch), except that +no updates are made on the destination system when creating the batch. +This lets you transport the changes to the destination system via some +other means and then apply the changes via bf(--read-batch). + +Note that you can feel free to write the batch directly to some portable +media: if this media fills to capacity before the end of the transfer, you +can just apply that partial transfer to the destination and repeat the +whole process to get the rest of the changes (as long as you don't mind a +partially updated destination system while the multi-update cycle is +happening). + +Also note that you only save bandwidth when pushing changes to a remote +system because this allows the batched data to be diverted from the sender +into the batch file without having to flow over the wire to the receiver +(when pulling, the sender is remote, and thus can't write the batch). dit(bf(--read-batch=FILE)) Apply all of the changes stored in FILE, a file previously generated by bf(--write-batch). If em(FILE) is "-" the batch data will be read from standard input. See the "BATCH MODE" section for details. +dit(bf(--protocol=NUM)) Force an older protocol version to be used. This +is useful for creating a batch file that is compatible with an older +version of rsync. For instance, if rsync 2.6.4 is being used with the +bf(--write-batch) option, but rsync 2.6.3 is what will be used to run the +bf(--read-batch) option, you should use "--protocol=28" (when creating the +batch file) to force the older protocol version to be used in the batch +file (assuming you can't upgrade the rsync on the reading system to 2.6.4). + dit(bf(-4, --ipv4) or bf(-6, --ipv6)) Tells rsync to prefer IPv4/IPv6 when creating sockets. This only affects sockets that rsync has direct control over, such as the outgoing socket when directly contacting an @@ -1266,12 +1340,11 @@ become a background daemon. The daemon will read the config file requests accordingly. See the rsyncd.conf(5) man page for more details. -dit(bf(--address)) By default rsync will bind to the wildcard address -when run as a daemon with the bf(--daemon) option or when connecting to a -rsync server. The bf(--address) option allows you to specify a specific IP -address (or hostname) to bind to. This makes virtual hosting possible -in conjunction with the bf(--config) option. See also the "address" global -option in the rsyncd.conf manpage. +dit(bf(--address)) By default rsync will bind to the wildcard address when +run as a daemon with the bf(--daemon) option. The bf(--address) option +allows you to specify a specific IP address (or hostname) to bind to. This +makes virtual hosting possible in conjunction with the bf(--config) option. +See also the "address" global option in the rsyncd.conf manpage. dit(bf(--bwlimit=KBPS)) This option allows you to specify a maximum transfer rate in kilobytes per second for the data the daemon sends. @@ -1813,7 +1886,7 @@ Caveats: The read-batch option expects the destination tree that it is updating to be identical to the destination tree that was used to create the batch update fileset. When a difference between the destination trees -is encountered the update might be discarded with no error (if the file +is encountered the update might be discarded with a warning (if the file appears to be up-to-date already) or the file-update may be attempted and then, if the file fails to verify, the update discarded with an error. This means that it should be safe to re-run a read-batch operation @@ -1828,10 +1901,10 @@ destination tree. The rsync version used on all destinations must be at least as new as the one used to generate the batch file. Rsync will die with an error if the protocol version in the batch file is too new for the batch-reading rsync -to handle. - -The bf(--dry-run) (bf(-n)) option does not work in batch mode and yields a runtime -error. +to handle. See also the bf(--protocol) option for a way to have the +creating rsync generate a batch file that an older rsync can understand. +(Note that batch files changed format in version 2.6.3, so mixing versions +older than that with newer versions will not work.) When reading a batch file, rsync will force the value of certain options to match the data in the batch file if you didn't set them to the same @@ -1915,6 +1988,7 @@ was made to manipulate 64-bit files on a platform that cannot support them; or an option was specified that is supported by the client and not by the server. dit(bf(5)) Error starting client-server protocol +dit(bf(6)) Daemon unable to append to log-file dit(bf(10)) Error in socket I/O dit(bf(11)) Error in file I/O dit(bf(12)) Error in rsync protocol data stream @@ -1925,6 +1999,7 @@ dit(bf(21)) Some error returned by waitpid() dit(bf(22)) Error allocating core memory buffers dit(bf(23)) Partial transfer due to error dit(bf(24)) Partial transfer due to vanished source files +dit(bf(25)) The --max-delete limit stopped deletions dit(bf(30)) Timeout in data send/receive enddit()