Some daemon security improvements, including the new parameters
[rsync.git] / rsync.yo
index 658ad99df73f3bfcc8edef71fc96291db09178ad..995672856057dee9415ca59b6b20fc965f1d2545 100644 (file)
--- a/rsync.yo
+++ b/rsync.yo
@@ -1,5 +1,5 @@
 mailto(rsync-bugs@samba.org)
-manpage(rsync)(1)(26 Oct 2007)()()
+manpage(rsync)(1)(10 Feb 2008)()()
 manpagename(rsync)(a fast, versatile, remote (and local) file-copying tool)
 manpagesynopsis()
 
@@ -353,7 +353,7 @@ to the detailed description below for a complete description.  verb(
      --fake-super            store/recover privileged attrs using xattrs
  -S, --sparse                handle sparse files efficiently
  -n, --dry-run               perform a trial run with no changes made
- -W, --whole-file            copy files whole (without rsync algorithm)
+ -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
@@ -527,7 +528,7 @@ either a changed size or a changed checksum are selected for transfer.
 
 Note that rsync always verifies that each em(transferred) file was
 correctly reconstructed on the receiving side by checking a whole-file
-checksum that is generated when as the file is transferred, but that
+checksum that is generated as the file is transferred, but that
 automatic after-the-transfer verification has nothing to do with this
 option's before-the-transfer "Does this file need to be updated?" check.
 
@@ -816,11 +817,24 @@ the transfer and link together the corresponding files on the receiving
 side.  Without this option, hard-linked files in the transfer are treated
 as though they were separate files.
 
-Note that rsync can only detect hard links if both parts of the link
-are in the list of files being sent.
+When you are updating a non-empty destination, this option only ensures
+that files that are hard-linked together on the source are hard-linked
+together on the destination.  It does NOT currently endeavor to break
+already existing hard links on the destination that do not exist between
+the source files.  Note, however, that if one or more extra-linked files
+have content changes, they will become unlinked when updated (assuming you
+are not using the bf(--inplace) option).
+
+Note that rsync can only detect hard links between files that are inside
+the transfer set.  If rsync updates a file that has extra hard-link
+connections to files outside the transfer, that linkage will be broken.  If
+you are tempted to use the bf(--inplace) option to avoid this breakage, be
+very careful that you know how your files are being updated so that you are
+certain that no unintended changes happen due to lingering hard links (and
+see the bf(--inplace) option for more caveats).
 
 If incremental recursion is active (see bf(--recursive)), rsync may transfer
-a missing hard-linked file before it finds that another link for the file
+a missing hard-linked file before it finds that another link for that contents
 exists elsewhere in the hierarchy.  This does not affect the accuracy of
 the transfer, just its efficiency.  One way to avoid this is to disable
 incremental recursion using the bf(--no-inc-recursive) option.
@@ -1037,7 +1051,7 @@ 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
+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
@@ -1292,7 +1306,10 @@ exclude certain files from the list of files to be transferred. This is
 most useful in combination with a recursive transfer.
 
 You may use as many bf(--filter) options on the command line as you like
-to build up the list of files to exclude.
+to build up the list of files to exclude.  If the filter contains whitespace,
+be sure to quote it so that the shell gives the rule to rsync as a single
+argument.  The text below also mentions that you can use an underscore to
+replace the space that separates a rule from its arg.
 
 See the FILTER RULES section for detailed information on this option.
 
@@ -1405,7 +1422,7 @@ characters are not translated (such as ~, $, ;, &, etc.).  Wildcards are
 expanded on the remote host by rsync (instead of the shell doing it).
 
 If you use this option with bf(--iconv), the args will also be translated
-from the local to the remote character set.  The translation happens before
+from the local to the remote character-set.  The translation happens before
 wild-cards are expanded.  See also the bf(--files-from) option.
 
 dit(bf(-T, --temp-dir=DIR)) This option instructs rsync to use DIR as a
@@ -1582,6 +1599,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
@@ -1939,6 +1960,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
@@ -2010,11 +2033,17 @@ 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).
-Finally, you can specify a CONVERT_SPEC of "-" to turn off any conversion.
+separated by a comma in the order bf(--iconv=LOCAL,REMOTE), e.g.
+bf(--iconv=utf8,iso88591).  This order ensures that the option
+will stay the same whether you're pushing or pulling files.
+Finally, you can specify either bf(--no-iconv) or 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.
 
+For a list of what charset names your local iconv library supports, you can
+run "iconv --list".
+
 If you specify the bf(--protect-args) option (bf(-s)), rsync will translate
 the filenames you specify on the command-line that are being sent to the
 remote host.  See also the bf(--files-from) option.
@@ -2025,6 +2054,11 @@ specifying matching rules that can match on both sides of the transfer.
 For instance, you can specify extra include/exclude rules if there are
 filename differences on the two sides that need to be accounted for.
 
+When you pass an bf(--iconv) option to an rsync daemon that allows it, the
+daemon uses the charset specified in its "charset" configuration parameter
+regardless of the remote charset you actually pass.  Thus, you may feel free to
+specify just the local charset for a daemon transfer (e.g. bf(--iconv=utf8)).
+
 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
@@ -2775,6 +2809,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)
@@ -2794,7 +2829,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".
@@ -2828,7 +2864,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.0pre9 of rsync.
 
 manpagesection(INTERNAL OPTIONS)