Some daemon security improvements, including the new parameters
[rsync.git] / rsync.yo
index a98d1eab2df12dad2dc1b2a2cac0c1a315ad2e76..995672856057dee9415ca59b6b20fc965f1d2545 100644 (file)
--- 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)(10 Feb 2008)()()
+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
@@ -532,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.
 
@@ -601,10 +597,23 @@ machine. If instead you used
 quote(tt(   rsync -avR /foo/bar/baz.c remote:/tmp/))
 
 then a file named /tmp/foo/bar/baz.c would be created on the remote
-machine -- the full path name is preserved.  To limit the amount of
-path information that is sent, you have a couple options:  (1) With
-a modern rsync on the sending side (beginning with 2.6.7), you can
-insert a dot and a slash into the source path, like this:
+machine, preserving its full path.  These extra path elements are called
+"implied directories" (i.e. the "foo" and the "foo/bar" directories in the
+above example).
+
+Beginning with rsync 3.0.0, rsync always sends these implied directories as
+real directories in the file list, even if a path element is really a
+symlink on the sending side.  This prevents some really unexpected
+behaviors when copying the full path of a file that you didn't realize had
+a symlink in its path.  If you want to duplicate a server-side symlink,
+include both the symlink via its path, and referent directory via its real
+path.  If you're dealing with an older rsync on the sending side, you may
+need to use the bf(--no-implied-dirs) option.
+
+It is also possible to limit the amount of path information that is sent as
+implied directories for each path you specify.  With a modern rsync on the
+sending side (beginning with 2.6.7), you can insert a dot and a slash into
+the source path, like this:
 
 quote(tt(   rsync -avR /foo/./bar/baz.c remote:/tmp/))
 
@@ -617,8 +626,8 @@ quote(tt(   (cd /foo; rsync -avR bar/baz.c remote:/tmp/) ))
 
 (Note that the parens put the two commands into a sub-shell, so that the
 "cd" command doesn't remain in effect for future commands.)
-If you're pulling files, use this idiom (which doesn't work with an
-rsync daemon):
+If you're pulling files from an older rsync, use this idiom (but only
+for a non-daemon transfer):
 
 quote(
 tt(   rsync -avR --rsync-path="cd /foo; rsync" \ )nl()
@@ -632,7 +641,7 @@ means that the corresponding path elements on the destination system are
 left unchanged if they exist, and any missing implied directories are
 created with default attributes.  This even allows these implied path
 elements to have big differences, such as being a symlink to a directory on
-one side of the transfer, and a real directory on the other side.
+the receiving side.
 
 For instance, if a command-line arg or a files-from entry told rsync to
 transfer the file "path/foo/file", the directories "path" and "path/foo"
@@ -645,15 +654,9 @@ ends up being created in "path/bar".  Another way to accomplish this link
 preservation is to use the bf(--keep-dirlinks) option (which will also
 affect symlinks to directories in the rest of the transfer).
 
-In a similar but opposite scenario, if the transfer of "path/foo/file" is
-requested and "path/foo" is a symlink on the sending side, running without
-bf(--no-implied-dirs) would cause rsync to transform "path/foo" on the
-receiving side into an identical symlink, and then attempt to transfer
-"path/foo/file", which might fail if the duplicated symlink did not point
-to a directory on the receiving side.  Another way to avoid this sending of
-a symlink as an implied directory is to use bf(--copy-unsafe-links), or
-bf(--copy-dirlinks) (both of which also affect symlinks in the rest of the
-transfer -- see their descriptions for full details).
+When pulling files from an rsync older than 3.0.0, you may need to use this
+option if the sending side has a symlink in the path you request and you
+wish the implied directories to be transferred as normal directories.
 
 dit(bf(-b, --backup)) With this option, preexisting destination files are
 renamed as each file is transferred or deleted.  You can control where the
@@ -745,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.
 
@@ -793,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
@@ -800,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.
@@ -838,17 +868,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
@@ -877,12 +907,20 @@ quote(itemization(
 If bf(--perms) is enabled, this option is ignored.
 
 dit(bf(-A, --acls)) This option causes rsync to update the destination
-ACLs to be the same as the source ACLs.  This nonstandard option only
-works if the remote rsync also supports it.  bf(--acls) implies bf(--perms).
+ACLs to be the same as the source ACLs.
+The option also implies bf(--perms).
+
+The source and destination systems must have compatible ACL entries for this
+option to work properly.  See the bf(--fake-super) option for a way to backup
+and restore ACLs that are not compatible.
 
 dit(bf(-X, --xattrs)) This option causes rsync to update the remote
-extended attributes to be the same as the local ones.  This will work
-only if the remote machine's rsync also supports this option.
+extended attributes to be the same as the local ones.
+
+For systems that support extended-attribute namespaces, a copy being done by a
+super-user copies all namespaces except system.*.  A normal user only copies
+the user.* namespace.  To be able to backup and restore non-user namespaces as
+a normal user, see the bf(--fake-super) option.
 
 dit(bf(--chmod)) This option tells rsync to apply one or more
 comma-separated "chmod" strings to the permission of the files in the
@@ -907,8 +945,8 @@ dit(bf(-o, --owner)) This option causes rsync to set the owner of the
 destination file to be the same as the source file, but only if the
 receiving rsync is being run as the super-user (see also the bf(--super)
 and bf(--fake-super) options).
-Without this option, the owner is set to the invoking user on the
-receiving side.
+Without this option, the owner of new and/or transferred files are set to
+the invoking user on the receiving side.
 
 The preservation of ownership will associate matching names by default, but
 may fall back to using the ID number in some circumstances (see also the
@@ -960,14 +998,19 @@ being running as the super-user.  To turn off super-user activities, the
 super-user can use bf(--no-super).
 
 dit(bf(--fake-super)) When this option is enabled, rsync simulates
-super-user activities by saving/restoring the privileged attributes via a
-special extended attribute that is attached to each file (as needed).  This
+super-user activities by saving/restoring the privileged attributes via
+special extended attributes that are attached to each file (as needed).  This
 includes the file's owner and group (if it is not the default), the file's
 device info (device & special files are created as empty text files), and
 any permission bits that we won't allow to be set on the real file (e.g.
 the real file gets u-s,g-s,o-t for safety) or that would limit the owner's
 access (since the real super-user can always access/change a file, the
 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 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.
 To affect the remote side of a remote-shell connection, specify an rsync
@@ -976,11 +1019,10 @@ 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
-"localhost" if you need to avoid this.  Note, however, that it is always
-safe to copy from some non-fake-super files into some fake-super files
-using a local bf(--fake-super) command because the non-fake source files
-will just have their normal attributes.
+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)).
 
 This option is overridden by both bf(--super) and bf(--no-super).
 
@@ -994,10 +1036,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
@@ -1059,9 +1113,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
@@ -1223,8 +1277,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
@@ -1252,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.
 
@@ -1365,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
@@ -1542,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
@@ -1899,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
@@ -1908,16 +1971,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
@@ -1964,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.
@@ -1979,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
@@ -2729,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)
@@ -2748,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".
@@ -2782,7 +2864,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.0pre9 of rsync.
 
 manpagesection(INTERNAL OPTIONS)
 
@@ -2808,23 +2890,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)