X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/6a85ee9623f40afa976e2cbe6ced5529c509a3c7..71daa07fb1c791c0f5eba3fc1b615df3a46441fc:/rsync.yo diff --git a/rsync.yo b/rsync.yo index 4563866a..8145687b 100644 --- a/rsync.yo +++ b/rsync.yo @@ -1,5 +1,5 @@ mailto(rsync-bugs@samba.org) -manpage(rsync)(1)(26 Oct 2007)()() +manpage(rsync)(1)(12 Jan 2008)()() manpagename(rsync)(a fast, versatile, remote (and local) file-copying tool) manpagesynopsis() @@ -225,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). @@ -328,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 @@ -352,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 @@ -378,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 @@ -421,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 @@ -801,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 @@ -846,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 @@ -987,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. @@ -997,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)). @@ -1014,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 @@ -1562,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 @@ -1919,6 +1944,8 @@ dit(bf(--password-file)) This option allows you to provide a password in a file for accessing an rsync daemon. The file must not be world readable. It should contain just the password as a single line. +This option does not supply a password to a remote shell transport such as +ssh; to learn how to do that, consult the remote shell's documentation. When accessing an rsync daemon using a remote shell as the transport, this option only comes into effect after the remote shell finishes its authentication (i.e. if you have also specified a password in the daemon's @@ -1990,7 +2017,8 @@ dit(bf(--iconv=CONVERT_SPEC)) Rsync can convert filenames between character sets using this option. Using a CONVERT_SPEC of "." tells rsync to look up the default character-set via the locale setting. Alternately, you can fully specify what conversion to do by giving a local and a remote charset -separated by a comma (local first), e.g. bf(--iconv=utf8,iso88591). +separated by a comma (local first), e.g. bf(--iconv=utf8,iso88591). (Run +"iconv --list" to see a list of the charset names that a machine supports.) Finally, you can specify a CONVERT_SPEC of "-" to turn off any conversion. The default setting of this option is site-specific, and can also be affected via the RSYNC_ICONV environment variable. @@ -2755,6 +2783,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) @@ -2774,7 +2803,8 @@ rsync daemon. You should set RSYNC_PROXY to a hostname:port pair. dit(bf(RSYNC_PASSWORD)) Setting RSYNC_PASSWORD to the required password allows you to run authenticated rsync connections to an rsync daemon without user intervention. Note that this does not supply a -password to a shell transport such as ssh. +password to a remote shell transport such as ssh; to learn how to do that, +consult the remote shell's documentation. dit(bf(USER) or bf(LOGNAME)) The USER or LOGNAME environment variables are used to determine the default username sent to an rsync daemon. If neither is set, the username defaults to "nobody". @@ -2808,7 +2838,7 @@ url(http://rsync.samba.org/)(http://rsync.samba.org/) manpagesection(VERSION) -This man page is current for version 3.0.0pre4 of rsync. +This man page is current for version 3.0.0pre8 of rsync. manpagesection(INTERNAL OPTIONS)