X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/c7b1a56b3d70fb91b20702f169ae1af9b68de8e9..b9f592fbf50b0dc9e3d1d33b8deb2bf9abad9ef6:/rsync.yo diff --git a/rsync.yo b/rsync.yo index 4805c010..0f07c46b 100644 --- a/rsync.yo +++ b/rsync.yo @@ -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 @@ -347,8 +347,8 @@ 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 @@ -897,13 +897,13 @@ 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(--write-batch=FILE)) Record a file that can later be applied to +anonther identical destination with --read-batch. 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(--read-batch=FILE)) Apply all of the changes stored in FILE, a +file previously generated by --write-batch. 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 @@ -917,16 +917,12 @@ 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(), or 32761 if -bf(--write-batch) or bf(--read-batch) are specified. This option +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. Note also that bf(--write-batch) and bf(--read-batch) -set the checksum seed to 32761, so bf(--checksum-seed=NUM) needs to -follow these options if you want to specify a different checksum -seed in batch mode. +for checksum seed. enddit() @@ -1107,53 +1103,45 @@ 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. - -The fileset consists of 4 files: - -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 -) - -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. - -Generating the batch update fileset once saves having to perform the -file status, checksum and data block generation more than once when +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 +".rsync_argvs" to the batch filename. The .rsync_argvs 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. +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. Example: verb( - $ rsync --write-batch=pfx -a /source/dir/ /adest/dir/ - $ rcp pfx.rsync_* remote: - $ ssh remote rsync --read-batch=pfx -a /bdest/dir/ + $ rsync --write-batch=batch -a /source/dir/ /adest/dir/ + $ rcp batch* remote: + $ ssh remote rsync --read-batch=batch -a /bdest/dir/ # or alternatively - $ ssh remote ./pfx.rsync_argvs /bdest/dir/ + $ ssh remote ./batch.rsync_argvs /bdest/dir/ ) In this example, rsync is used to update /adest/dir/ with /source/dir/ -and the information to repeat this operation is stored in the files -pfx.rsync_*. These files are then copied to the machine named "remote". -Rsync is then invoked on "remote" to update /bdest/dir/ the same way as -/adest/dir/. The last line shows the rsync_argvs file being used to -invoke rsync. +and the information to repeat this operation is stored in "batch" and +"batch.rsync_argvs". These files are then copied to the machine named +"remote". Rsync is then invoked on "remote" to update /bdest/dir/ the +same way as /adest/dir/. The last line shows the rsync_argvs file +being used to invoke rsync. Caveats: @@ -1165,16 +1153,23 @@ destination tree in a partially updated state. In that case, rsync can be used in its regular (non-batch) mode of operation to fix up the destination tree. -The rsync version used on all destinations should be identical to the -one used on the original destination. - -The -z/--compress option does not work in batch mode and yields a usage -error. A separate compression tool can be used instead to reduce the -size of the batch update files for transport to the destination. +The rsync version used on all destinations must be at least as new as the +one used to generate the batch file. The -n/--dryrun option does not work in batch mode and yields a runtime error. +You should use an equivalent set of options when reading a batch file that +you used when generating it with a few exceptions. For instance +--write-batch changes to --read-batch, --files-from is dropped, and the +--include/--exclude options are not needed unless --delete is specified +without --delete-excluded. Other options that affect how the update +happens should generally remain the same as it is possible to confuse rsync +into expecting a different data stream than the one that is contained in +the batch file. For example, it would not work to change the setting of +the -H or -c option, but it would work to add or remove the --delete +option. + See bf(http://www.ils.unc.edu/i2dsi/unc_rsync+.html) for papers and technical reports.