X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/0f6b4909dbe592bf05f17db7772e835cff2f5839..78246d1a093ae18b102d719692bde55c266297d6:/rsync.yo diff --git a/rsync.yo b/rsync.yo index ad83ecf6..11f09171 100644 --- a/rsync.yo +++ b/rsync.yo @@ -1,41 +1,40 @@ mailto(rsync-bugs@samba.org) -manpage(rsync)(1)(6 Nov 2006)()() -manpagename(rsync)(faster, flexible replacement for rcp) +manpage(rsync)(1)(16 Dec 2007)()() +manpagename(rsync)(a fast, versatile, remote (and local) file-copying tool) manpagesynopsis() -rsync [OPTION]... SRC [SRC]... DEST +verb(Local: rsync [OPTION...] SRC... [DEST] -rsync [OPTION]... SRC [SRC]... [USER@]HOST:DEST +Access via remote shell: + Pull: rsync [OPTION...] [USER@]HOST:SRC... [DEST] + Push: rsync [OPTION...] SRC... [USER@]HOST:DEST -rsync [OPTION]... SRC [SRC]... [USER@]HOST::DEST +Access via rsync daemon: + Pull: rsync [OPTION...] [USER@]HOST::SRC... [DEST] + rsync [OPTION...] rsync://[USER@]HOST[:PORT]/SRC... [DEST] + Push: rsync [OPTION...] SRC... [USER@]HOST::DEST + rsync [OPTION...] SRC... rsync://[USER@]HOST[:PORT]/DEST) -rsync [OPTION]... SRC [SRC]... rsync://[USER@]HOST[:PORT]/DEST - -rsync [OPTION]... SRC - -rsync [OPTION]... [USER@]HOST:SRC [DEST] - -rsync [OPTION]... [USER@]HOST::SRC [DEST] - -rsync [OPTION]... rsync://[USER@]HOST[:PORT]/SRC [DEST] +Usages with just one SRC arg and no DEST arg will list the source files +instead of copying. manpagedescription() -Rsync is a program that behaves in much the same way that rcp does, -but has many more options and uses the rsync remote-update protocol to -greatly speed up file transfers when the destination file is being -updated. - -The rsync remote-update protocol allows rsync to transfer just the -differences between two sets of files across the network connection, using -an efficient checksum-search algorithm described in the technical -report that accompanies this package. - -Rsync finds files that need to be transferred using a "quick check" algorithm -that looks for files that have changed in size or in last-modified time (by -default). Any changes in the other preserved attributes (as requested by -options) are made on the destination file directly when the quick check -indicates that the file's data does not need to be updated. +Rsync is a fast and extraordinarily versatile file copying tool. It can +copy locally, to/from another host over any remote shell, or to/from a +remote rsync daemon. It offers a large number of options that control +every aspect of its behavior and permit very flexible specification of the +set of files to be copied. It is famous for its delta-transfer algorithm, +which reduces the amount of data sent over the network by sending only the +differences between the source files and the existing files in the +destination. Rsync is widely used for backups and mirroring and as an +improved copy command for everyday use. + +Rsync finds files that need to be transferred using a "quick check" +algorithm (by default) that looks for files that have changed in size or +in last-modified time. Any changes in the other preserved attributes (as +requested by options) are made on the destination file directly when the +quick check indicates that the file's data does not need to be updated. Some of the additional features of rsync are: @@ -149,33 +148,29 @@ See the following section for more details. manpagesection(ADVANCED USAGE) -The syntax for requesting multiple files from a remote host involves using -quoted spaces in the SRC. Some examples: +The syntax for requesting multiple files from a remote host is done by +specifying additional remote-host args in the same style as the first, +or with the hostname omitted. For instance, all these work: -quote(tt(rsync host::'modname/dir1/file1 modname/dir2/file2' /dest)) +quote(tt(rsync -av host:file1 :file2 host:file{3,4} /dest/)nl() +tt(rsync -av host::modname/file{1,2} host::modname/file3 /dest/)nl() +tt(rsync -av host::modname/file1 ::modname/file{3,4})) -This would copy file1 and file2 into /dest from an rsync daemon. Each -additional arg must include the same "modname/" prefix as the first one, -and must be preceded by a single space. All other spaces are assumed -to be a part of the filenames. +Older versions of rsync required using quoted spaces in the SRC, like these +examples: -quote(tt(rsync -av host:'dir1/file1 dir2/file2' /dest)) +quote(tt(rsync -av host:'dir1/file1 dir2/file2' /dest)nl() +tt(rsync host::'modname/dir1/file1 modname/dir2/file2' /dest)) -This would copy file1 and file2 into /dest using a remote shell. This -word-splitting is done by the remote shell, so if it doesn't work it means -that the remote shell isn't configured to split its args based on -whitespace (a very rare setting, but not unknown). If you need to transfer -a filename that contains whitespace, you'll need to either escape the -whitespace in a way that the remote shell will understand, or use wildcards -in place of the spaces. Two examples of this are: +This word-splitting still works (by default) in the latest rsync, but is +not as easy to use as the first method. -quote( -tt(rsync -av host:'file\ name\ with\ spaces' /dest)nl() -tt(rsync -av host:file?name?with?spaces /dest)nl() -) +If you need to transfer a filename that contains whitespace, you can either +specify the bf(--protect-args) (bf(-s)) option, or you'll need to escape +the whitespace in a way that the remote shell will understand. For +instance: -This latter example assumes that your shell passes through unmatched -wildcards. If it complains about "no match", put the name in quotes. +quote(tt(rsync -av host:'file\ name\ with\ spaces' /dest)) manpagesection(CONNECTING TO AN RSYNC DAEMON) @@ -230,7 +225,7 @@ verb( export RSYNC_CONNECT_PROG='ssh proxyhost nc %H 873' rsync -av targethost1::module/src/ /dest/ rsync -av rsync:://targethost2/module/src/ /dest/ ) -The command specifed above uses ssh to run nc (netcat) on a proxyhost, +The command specified above uses ssh to run nc (netcat) on a proxyhost, which forwards all data to port 873 (the rsync daemon) on the targethost (%H). @@ -333,7 +328,7 @@ to the detailed description below for a complete description. verb( -u, --update skip files that are newer on the receiver --inplace update destination files in-place --append append data onto shorter files - --append-verify --append w/old data in file cheksum + --append-verify --append w/old data in file checksum -d, --dirs transfer directories without recursing -l, --links copy symlinks as symlinks -L, --copy-links transform symlink into referent file/dir @@ -357,8 +352,8 @@ to the detailed description below for a complete description. verb( --super receiver attempts super-user activities --fake-super store/recover privileged attrs using xattrs -S, --sparse handle sparse files efficiently - -n, --dry-run show what would have been transferred - -W, --whole-file copy files whole (without rsync algorithm) + -n, --dry-run perform a trial run with no changes made + -W, --whole-file copy files whole (w/o delta-xfer algorithm) -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 @@ -383,7 +378,8 @@ to the detailed description below for a complete description. verb( --delay-updates put all updated files into place at end -m, --prune-empty-dirs prune empty directory chains from file-list --numeric-ids don't map uid/gid values by user/group name - --timeout=TIME set I/O timeout in seconds + --timeout=SECONDS set I/O timeout in seconds + --contimeout=SECONDS set daemon connection timeout in seconds -I, --ignore-times don't skip files that match size and time --size-only skip files that match in size --modify-window=NUM compare mod-times with reduced accuracy @@ -426,7 +422,7 @@ to the detailed description below for a complete description. verb( --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 - --iconv=CONVERT_SPEC request charset conversion of filesnames + --iconv=CONVERT_SPEC request charset conversion of filenames --checksum-seed=NUM set block/file checksum seed (advanced) -4, --ipv4 prefer IPv4 -6, --ipv6 prefer IPv6 @@ -752,6 +748,12 @@ bf(--recursive) option, rsync will skip all directories it encounters (and output a message to that effect for each one). If you specify both bf(--dirs) and bf(--recursive), bf(--recursive) takes precedence. +This option is implied by the bf(--list-only) option (including an implied +bf(--list-only) usage) if bf(--recursive) wasn't specified (so that +directories are seen in the listing). Specify bf(--no-dirs) (or bf(--no-d)) +if you want to override this. This option is also implied by +bf(--files-from). + dit(bf(-l, --links)) When symlinks are encountered, recreate the symlink on the destination. @@ -800,6 +802,14 @@ directory, and receives the file into the new directory. With bf(--keep-dirlinks), the receiver keeps the symlink and "file" ends up in "bar". +One note of caution: if you use bf(--keep-dirlinks), you must trust all +the symlinks in the copy! If it is possible for an untrusted user to +create their own symlink to any directory, the user could then (on a +subsequent copy) replace the symlink with a real directory and affect the +content of whatever directory the symlink references. For backup copies, +you are better off using something like a bind mount instead of a symlink +to modify your receiving hierarchy. + See also bf(--copy-dirlinks) for an analogous option for the sending side. dit(bf(-H, --hard-links)) This tells rsync to look for hard-linked files in @@ -845,17 +855,17 @@ permissions (while leaving existing files unchanged), make sure that the bf(--perms) option is off and use bf(--chmod=ugo=rwX) (which ensures that all non-masked bits get enabled). If you'd care to make this latter behavior easier to type, you could define a popt alias for it, such as -putting this line in the file ~/.popt (this defines the bf(-s) option, +putting this line in the file ~/.popt (the following defines the bf(-Z) option, and includes --no-g to use the default group of the destination dir): -quote(tt( rsync alias -s --no-p --no-g --chmod=ugo=rwX)) +quote(tt( rsync alias -Z --no-p --no-g --chmod=ugo=rwX)) You could then use this new option in a command such as this one: -quote(tt( rsync -asv src/ dest/)) +quote(tt( rsync -avZ src/ dest/)) -(Caveat: make sure that bf(-a) does not follow bf(-s), or it will re-enable -the "--no-*" options.) +(Caveat: make sure that bf(-a) does not follow bf(-Z), or it will re-enable +the two "--no-*" options mentioned above.) The preservation of the destination's setgid bit on newly-created directories when bf(--perms) is off was added in rsync 2.6.7. Older rsync @@ -986,7 +996,7 @@ files we create can always be accessed/changed by the creating user). This option also handles ACLs (if bf(--acls) was specified) and non-user extended attributes (if bf(--xattrs) was specified). -This is a good way to backup data withou using a super-user, and to store +This is a good way to backup data without using a super-user, and to store ACLs from incompatible systems. The bf(--fake-super) option only affects the side where the option is used. @@ -996,7 +1006,7 @@ path: quote(tt( rsync -av --rsync-path="rsync --fake-super" /src/ host:/dest/)) Since there is only one "side" in a local copy, this option affects both -the sending and recieving of files. You'll need to specify a copy using +the sending and receiving of files. You'll need to specify a copy using "localhost" if you need to avoid this, possibly using the "lsh" shell script (from the support directory) as a substitute for an actual remote shell (see bf(--rsh)). @@ -1013,10 +1023,22 @@ NOTE: Don't use this option when the destination is a Solaris "tmpfs" filesystem. It doesn't seem to handle seeks over null regions correctly and ends up corrupting the files. -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. - -dit(bf(-W, --whole-file)) With this option the delta transfer algorithm +dit(bf(-n, --dry-run)) This makes rsync perform a trial run that doesn't +make any changes (and produces mostly the same output as a real run). It +is most commonly used in combination with the bf(-v, --verbose) and/or +bf(-i, --itemize-changes) options to see what an rsync command is going +to do before one actually runs it. + +The output of bf(--itemize-changes) is supposed to be exactly the same on a +dry run and a subsequent real run (barring intentional trickery and system +call failures); if it isn't, that's a bug. Other output is the same to the +extent practical, but may differ in some areas. Notably, a dry run does not +send the actual data for file transfers, so bf(--progress) has no effect, +the "bytes sent", "bytes received", "literal data", and "matched data" +statistics are too small, and the "speedup" value is equivalent to a run +where no file transfers are needed. + +dit(bf(-W, --whole-file)) With this option the delta-transfer 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 destination machines is higher than the bandwidth to disk (especially when the @@ -1078,9 +1100,9 @@ Prior to rsync 2.6.7, this option would have no effect unless bf(--recursive) was enabled. Beginning with 2.6.7, deletions will also occur when bf(--dirs) (bf(-d)) is enabled, but only for directories whose contents are being copied. -This option can be dangerous if used incorrectly! It is a very good idea -to run first using the bf(--dry-run) option (bf(-n)) to see what files would be -deleted to make sure important files aren't listed. +This option can be dangerous if used incorrectly! It is a very good idea to +first try a run using the bf(--dry-run) option (bf(-n)) to see what files are +going to be deleted. If the sending side detects any I/O errors, then the deletion of any files at the destination will be automatically disabled. This is to @@ -1242,8 +1264,8 @@ The exclude list is initialized to exclude the following items (these initial items are marked as perishable -- see the FILTER RULES section): quote(quote(tt(RCS SCCS CVS CVS.adm RCSLOG cvslog.* tags TAGS .make.state -.nse_depinfo *~ #* .#* ,* _$* *$ *.old *.bak *.BAK *.orig *.rej -.del-* *.a *.olb *.o *.obj *.so *.exe *.Z *.elc *.ln core .svn/ .bzr/))) +.nse_depinfo *~ #* .#* ,* _$* *$ *.old *.bak *.BAK *.orig *.rej .del-* +*.a *.olb *.o *.obj *.so *.exe *.Z *.elc *.ln core .svn/ .git/ .bzr/))) then, files listed in a $HOME/.cvsignore are added to the list and any files listed in the CVSIGNORE environment variable (all cvsignore names @@ -1561,6 +1583,10 @@ 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(--contimeout)) This option allows you to set the amount of time +that rsync will wait for its connection to an rsync daemon to succeed. +If the timeout is reached, rsync exits with an error. + 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 @@ -1927,16 +1953,22 @@ dit(bf(--list-only)) This option will cause the source files to be listed instead of transferred. This option is inferred if there is a single source arg and no destination specified, so its main uses are: (1) to turn a copy command that includes a -destination arg into a file-listing command, (2) to be able to specify more -than one local source arg (note: be sure to include the destination), or -(3) to avoid the automatically added "bf(-r --exclude='/*/*')" options that -rsync usually uses as a compatibility kluge when generating a non-recursive -listing. Caution: keep in mind that a source arg with a wild-card is expanded -by the shell into multiple args, so it is never safe to try to list such an arg +destination arg into a file-listing command, or (2) to be able to specify +more than one source arg (note: be sure to include the destination). +Caution: keep in mind that a source arg with a wild-card is expanded by the +shell into multiple args, so it is never safe to try to list such an arg without using this option. For example: verb( rsync -av --list-only foo* dest/) +Compatibility note: when requesting a remote listing of files from an rsync +that is version 2.6.3 or older, you may encounter an error if you ask for a +non-recursive listing. This is because a file listing implies the bf(--dirs) +option w/o bf(--recursive), and older rsyncs don't have that option. To +avoid this problem, either specify the bf(--no-dirs) option (if you don't +need to expand a directory's content), or turn on recursion and exclude +the content of subdirectories: bf(-r --exclude='/*/*'). + dit(bf(--bwlimit=KBPS)) This option allows you to specify a maximum transfer rate in kilobytes per second. This option is most effective when using rsync with large files (several megabytes and up). Due to the nature @@ -2748,6 +2780,7 @@ 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 +dit(bf(35)) Timeout waiting for daemon connection enddit() manpagesection(ENVIRONMENT VARIABLES) @@ -2801,7 +2834,7 @@ url(http://rsync.samba.org/)(http://rsync.samba.org/) manpagesection(VERSION) -This man page is current for version 2.6.9 of rsync. +This man page is current for version 3.0.0pre7 of rsync. manpagesection(INTERNAL OPTIONS) @@ -2827,23 +2860,25 @@ The primary ftp site for rsync is url(ftp://rsync.samba.org/pub/rsync)(ftp://rsync.samba.org/pub/rsync). We would be delighted to hear from you if you like this program. +Please contact the mailing-list at rsync@lists.samba.org. This program uses the excellent zlib compression library written by Jean-loup Gailly and Mark Adler. manpagesection(THANKS) -Thanks to Richard Brent, Brendan Mackay, Bill Waite, Stephen Rothwell -and David Bell for helpful suggestions, patches and testing of rsync. -I've probably missed some people, my apologies if I have. +Especial thanks go out to: John Van Essen, Matt McCutchen, Wesley W. Terpstra, +David Dykstra, Jos Backus, Sebastian Krahmer, Martin Pool, and our +gone-but-not-forgotten compadre, J.W. Schultz. -Especial thanks also to: David Dykstra, Jos Backus, Sebastian Krahmer, -Martin Pool, Wayne Davison, J.W. Schultz. +Thanks also to Richard Brent, Brendan Mackay, Bill Waite, Stephen Rothwell +and David Bell. I've probably missed some people, my apologies if I have. manpageauthor() rsync was originally written by Andrew Tridgell and Paul Mackerras. -Many people have later contributed to it. +Many people have later contributed to it. It is currently maintained +by Wayne Davison. Mailing lists for support and development are available at url(http://lists.samba.org)(lists.samba.org)