X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/a0c823b22b81d5ecb01058e4a14186f6252f959e..ef57235623e1a268ae96fe7fe772c493e06b0e36:/rsync.yo diff --git a/rsync.yo b/rsync.yo index fe27e078..f94d5d4a 100644 --- a/rsync.yo +++ b/rsync.yo @@ -1,5 +1,5 @@ mailto(rsync-bugs@samba.org) -manpage(rsync)(1)(17 Apr 2004)()() +manpage(rsync)(1)(30 Apr 2004)()() manpagename(rsync)(faster, flexible replacement for rcp) manpagesynopsis() @@ -32,7 +32,7 @@ report that accompanies this package. Some of the additional features of rsync are: itemize( - it() support for copying links, devices, owners, groups and permissions + it() support for copying links, devices, owners, groups, and permissions it() exclude and exclude-from options similar to GNU tar it() a CVS exclude mode for ignoring the same files that CVS would ignore it() can use any transparent remote shell, including ssh or rsh @@ -289,6 +289,8 @@ verb( --backup-dir make backups into this directory --suffix=SUFFIX backup suffix (default ~ w/o --backup-dir) -u, --update update only (don't overwrite newer files) + --inplace update the destination files inplace + -K, --keep-dirlinks treat symlinked dir on receiver as dir -l, --links copy symlinks as symlinks -L, --copy-links copy the referent of all symlinks --copy-unsafe-links copy the referent of "unsafe" symlinks @@ -304,7 +306,7 @@ verb( -W, --whole-file copy whole files, no incremental checks --no-whole-file turn off --whole-file -x, --one-file-system don't cross filesystem boundaries - -B, --block-size=SIZE checksum blocking size (default 700) + -B, --block-size=SIZE force a fixed checksum block-size -e, --rsh=COMMAND specify the remote shell --rsync-path=PATH specify path to rsync on the remote machine --existing only update files that already exist @@ -315,6 +317,7 @@ verb( --ignore-errors delete even if there are I/O errors --max-delete=NUM don't delete more than NUM files --partial keep partially transferred files + --partial-dir=DIR put a partially transferred file into DIR --force force deletion of dirs even if not empty --numeric-ids don't map uid/gid values by user/group name --timeout=TIME set I/O timeout in seconds @@ -346,8 +349,11 @@ verb( --log-format=FORMAT log file transfers using specified format --password-file=FILE get password from FILE --bwlimit=KBPS limit I/O bandwidth, KBytes per second - --write-batch=PREFIX write batch fileset starting with PREFIX - --read-batch=PREFIX read batch fileset starting with PREFIX + --write-batch=FILE write a batch to FILE + --read-batch=FILE read a batch from FILE + --checksum-seed=NUM set block/file checksum seed + -4 --ipv4 prefer IPv4 + -6 --ipv6 prefer IPv6 -h, --help show this help screen @@ -469,11 +475,42 @@ dit(bf(-u, --update)) This forces rsync to skip any files for which the destination file already exists and has a date later than the source file. +In the currently implementation, a difference of file format is always +considered to be important enough for an update, no matter what date +is on the objects. In other words, if the source has a directory or a +symlink where the destination has a file, the transfer would occur +regardless of the timestamps. This might change in the future (feel +free to comment on this on the mailing list if you have an opinion). + +dit(bf(-K, --keep-dirlinks)) On the receiving side, if a symlink is +pointing to a directory, it will be treated as matching a directory +from the sender. + +dit(bf(--inplace)) This causes rsync not to create a new copy of the file +and then move it into place. Instead rsync will overwrite the existing +file, meaning that the rsync algorithm can't extract the full amount of +network reduction it might otherwise. + +This option is useful for transfer of large files with block-based change +or appended data, and also on systems that are disk bound not network bound. + +WARNING: The file's data will be in an inconsistent state during the +transfer (and possibly afterward if the transfer gets interrupted), so you +should not use this option to update files that are in use. Also note that +rsync will be unable to update a file inplace that is not writable by the +receiving user. + dit(bf(-l, --links)) When symlinks are encountered, recreate the symlink on the destination. dit(bf(-L, --copy-links)) When symlinks are encountered, the file that -they point to (the referent) is copied, rather than the symlink. +they point to (the referent) is copied, rather than the symlink. In older +versions of rsync, this option also had the side-effect of telling the +receiving side to follow symlinks, such as symlinks to directories. In a +modern rsync such as this one, you'll need to specify --keep-dirlinks (-K) +to get this extra behavior. The only exception is when sending files to +an rsync that is too old to understand -K -- in that case, the -L option +will still have the side-effect of -K on that older receiving rsync. dit(bf(--copy-unsafe-links)) This tells rsync to copy the referent of symbolic links that point outside the copied tree. Absolute symlinks @@ -497,9 +534,9 @@ This option can be quite slow, so only use it if you need it. dit(bf(-W, --whole-file)) With this option the incremental rsync algorithm is not used and the whole file is sent as-is instead. The transfer may be faster if this option is used when the bandwidth between the source and -target machines is higher than the bandwidth to disk (especially when the +destination machines is higher than the bandwidth to disk (especially when the "disk" is actually a networked filesystem). This is the default when both -the source and target are on the local machine. +the source and destination are specified as local paths. dit(bf(--no-whole-file)) Turn off --whole-file, for use when it is the default. @@ -533,9 +570,9 @@ dit(bf(-t, --times)) This tells rsync to transfer modification times along with the files and update them on the remote system. Note that if this option is not used, the optimization that excludes files that have not been modified cannot be effective; in other words, a missing -t or -a will -cause the next transfer to behave as if it used -I, and all files will have -their checksums compared and show up in log messages even if they haven't -changed. +cause the next transfer to behave as if it used -I, causing all files to be +updated (though the rsync algorithm will make the update fairly efficient +if the files haven't actually changed, you're much better off using -t). dit(bf(-n, --dry-run)) This tells rsync to not do any file transfers, instead it will just report the actions it would have taken. @@ -596,8 +633,9 @@ they are not empty when they are to be replaced by non-directories. This is only relevant without --delete because deletions are now done depth-first. Requires the --recursive option (which is implied by -a) to have any effect. -dit(bf(-B , --block-size=BLOCKSIZE)) This controls the block size used in -the rsync algorithm. See the technical report for details. +dit(bf(-B, --block-size=BLOCKSIZE)) This forces the block size used in +the rsync algorithm to a fixed value. It is normally selected based on +the size of each file being updated. See the technical report for details. dit(bf(-e, --rsh=COMMAND)) This option allows you to choose an alternative remote shell program to use for communication between the local and @@ -671,11 +709,11 @@ See the EXCLUDE PATTERNS section for detailed information on this option. dit(bf(--include-from=FILE)) This specifies a list of include patterns from a file. -If em(FILE) is bf(-) the list will be read from standard input. +If em(FILE) is "-" the list will be read from standard input. dit(bf(--files-from=FILE)) Using this option allows you to specify the exact list of files to transfer (as read from the specified FILE or "-" -for stdin). It also tweaks the default behavior of rsync to make +for standard input). It also tweaks the default behavior of rsync to make transferring just the specified files and directories easier. For instance, the --relative option is enabled by default when this option is used (use --no-relative if you want to turn that off), all @@ -835,6 +873,29 @@ it is more desirable to keep partially transferred files. Using the --partial option tells rsync to keep the partial file which should make a subsequent transfer of the rest of the file much faster. +dit(bf(--partial-dir=DIR)) Turns on --partial mode, but tells rsync to +put a partially transferred file into DIR instead of writing out the +file to the destination dir. Rsync will also use a file found in this +dir as data to speed up the transfer (i.e. when you redo the send after +rsync creates a partial file) and delete such a file after it has served +its purpose. + +Rsync will create the dir if it is missing (just the last dir -- not the +whole path). This makes it easy to use a relative path (such as +"--partial-dir=.rsync-partial") to have rsync create the partial-directory +in the destination file's directory (rsync will also try to remove the DIR +if a partial file was found to exist at the start of the transfer and the +DIR was specified as a relative path). + +If you are deleting files on the destination and your partial-dir is +inside the destination hierarchy, make sure you specify an exclude to +prevent the partial file from being deleted (it could get deleted at the +end of the transfer when using --delete-after, or at the beginning of the +transfer when using --delete). E.g. "--exclude=.rsync-partial/". + +IMPORTANT: the --partial-dir should not be writable by other users to +avoid a security risk. E.g. AVOID "/tmp". + dit(bf(--progress)) This option tells rsync to print information showing the progress of the transfer. This gives a bored user something to watch. @@ -882,13 +943,33 @@ transfer was too fast, it will wait before sending the next data block. The result is an average transfer rate equaling the specified limit. A value of zero specifies no limit. -dit(bf(--write-batch=PREFIX)) Generate a set of files that can be -transferred as a batch update. Each filename in the set starts with -PREFIX. See the "BATCH MODE" section for details. - -dit(bf(--read-batch=PREFIX)) Apply a previously generated change batch, -using the fileset whose filenames start with PREFIX. See the "BATCH -MODE" section for details. +dit(bf(--write-batch=FILE)) Record a file that can later be applied to +another identical destination with --read-batch. See the "BATCH MODE" +section for details. + +dit(bf(--read-batch=FILE)) Apply all of the changes stored in FILE, a +file previously generated by --write-batch. +If em(FILE) is "-" the batch data will be read from standard input. +See the "BATCH MODE" section for details. + +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 +rsync daemon, or the incoming sockets that an rsync daemon uses to +listen for connections. One of these options may be required in older +versions of Linux to work around an IPv6 bug in the kernel (if you see +an "address already in use" error when nothing else is using the port, +try specifying --ipv6 or --ipv4 when starting the daemon). + +dit(bf(--checksum-seed=NUM)) Set the MD4 checksum seed to the integer +NUM. This 4 byte checksum seed is included in each block and file +MD4 checksum calculation. By default the checksum seed is generated +by the server and defaults to the current time(). This option +is used to set a specific checksum seed, which is useful for +applications that want repeatable block and file checksums, or +in the case where the user wants a more random checksum seed. +Note that setting NUM to 0 causes rsync to use the default of time() +for checksum seed. enddit() @@ -912,7 +993,7 @@ is where the tree starts to be duplicated in the destination directory. This root governs where patterns that start with a / match (see below). Because the matching is relative to the transfer-root, changing the -trailing slash on the source path or changing your use of the --relative +trailing slash on a source path or changing your use of the --relative option affects the path you need to use in your matching (in addition to changing how much of the file tree is duplicated on the destination system). The following examples demonstrate this. @@ -955,6 +1036,11 @@ Note that, when using the --recursive (-r) option (which is implied by -a), every subcomponent of every path is visited from the top down, so include/exclude patterns get applied recursively to each subcomponent. +The exclude patterns actually short-circuit the directory traversal stage +when rsync finds the files to send. If a pattern excludes a particular +parent directory, it can render a deeper include pattern ineffectual +because rsync did not descend through that excluded section of the +hierarchy. Note also that the --include and --exclude options take one pattern each. To add multiple patterns use the --include-from and @@ -1006,16 +1092,36 @@ itemize( The +/- rules are most useful in a list that was read from a file, allowing you to have a single exclude list that contains both include and exclude -options. +options in the proper order. -If you end an exclude list with --exclude '*', note that since the -algorithm is applied recursively that unless you explicitly include -parent directories of files you want to include then the algorithm -will stop at the parent directories and never see the files below -them. To include all directories, use --include '*/' before the ---exclude '*'. +Remember that the matching occurs at every step in the traversal of the +directory hierarchy, so you must be sure that all the parent directories of +the files you want to include are not excluded. This is particularly +important when using a trailing '*' rule. For instance, this won't work: + +verb( + + /some/path/this-file-will-not-be-found + + /file-is-included + - * +) + +This fails because the parent directory "some" is excluded by the '*' rule, +so rsync never visits any of the files in the "some" or "some/path" +directories. One solution is to ask for all directories in the hierarchy +to be included by using a single rule: --include='*/' (put it somewhere +before the --exclude='*' rule). Another solution is to add specific +include rules for all the parent dirs that need to be visited. For +instance, this set of rules works fine: + +verb( + + /some/ + + /some/path/ + + /some/path/this-file-is-found + + /file-also-included + - * +) -Here are some exclude/include examples: +Here are some examples of exclude/include matching: itemize( it() --exclude "*.o" would exclude all filenames matching *.o @@ -1035,7 +1141,8 @@ itemize( manpagesection(BATCH MODE) bf(Note:) Batch mode should be considered experimental in this version -of rsync. The interface or behaviour may change before it stabilizes. +of rsync. The interface and behavior have now stabilized, though, so +feel free to try this out. Batch mode can be used to apply the same set of updates to many identical systems. Suppose one has a tree which is replicated on a @@ -1044,80 +1151,109 @@ source tree and those changes need to be propagated to the other hosts. In order to do this using batch mode, rsync is run with the write-batch option to apply the changes made to the source tree to one of the destination trees. The write-batch option causes the rsync -client to store the information needed to repeat this operation against -other destination trees in a batch update fileset (see below). The -filename of each file in the fileset starts with a prefix specified by -the user as an argument to the write-batch option. This fileset is -then copied to each remote host, where rsync is run with the read-batch -option, again specifying the same prefix, and the destination tree. -Rsync updates the destination tree using the information stored in the -batch update fileset. +client to store in a "batch file" all the information needed to repeat +this operation against other, identical destination trees. + +To apply the recorded changes to another destination tree, run rsync +with the read-batch option, specifying the name of the same batch +file, and the destination tree. Rsync updates the destination tree +using the information stored in the batch file. + +For convenience, one additional file is creating when the write-batch +option is used. This file's name is created by appending +".sh" to the batch filename. The .sh file contains +a command-line suitable for updating a destination tree using that +batch file. It can be executed using a Bourne(-like) shell, optionally +passing in an alternate destination tree pathname which is then used +instead of the original path. This is useful when the destination tree +path differs from the original destination tree path. + +Generating the batch file once saves having to perform the file +status, checksum, and data block generation more than once when +updating multiple destination trees. Multicast transport protocols can +be used to transfer the batch update files in parallel to many hosts +at once, instead of sending the same data to every host individually. -The fileset consists of 4 files: +Examples: -itemize( -it() bf(.rsync_argvs) command-line arguments -it() bf(.rsync_flist) rsync internal file metadata -it() bf(.rsync_csums) rsync checksums -it() bf(.rsync_delta) data blocks for file update & change +verb( + $ rsync --write-batch=foo -a host:/source/dir/ /adest/dir/ + $ scp foo* remote: + $ ssh remote ./foo.sh /bdest/dir/ ) -The .rsync_argvs file contains a command-line suitable for updating a -destination tree using that batch update fileset. It can be executed -using a Bourne(-like) shell, optionally passing in an alternate -destination tree pathname which is then used instead of the original -path. This is useful when the destination tree path differs from the -original destination tree path. +verb( + $ rsync --write-batch=foo -a /source/dir/ /adest/dir/ + $ ssh remote rsync --read-batch=- -a /bdest/dir/