-of the new root path, and of complicating the preservation of usernames and groups
-(see below). When "use chroot" is false, for security reasons,
-symlinks may only be relative paths pointing to other files within the root
-path, and leading slashes are removed from most absolute paths (options
-such as bf(--backup-dir), bf(--compare-dest), etc. interpret an absolute path as
-rooted in the module's "path" dir, just as if chroot was specified).
-The default for "use chroot" is true.
-
-In order to preserve usernames and groupnames, rsync needs to be able to
-use the standard library functions for looking up names and IDs (i.e.
-code(getpwuid()), code(getgrgid()), code(getpwname()), and code(getgrnam())). This means a
-process in the chroot namespace will need to have access to the resources
-used by these library functions (traditionally /etc/passwd and
-/etc/group). If these resources are not available, rsync will only be
-able to copy the IDs, just as if the bf(--numeric-ids) option had been
-specified.
-
-Note that you are free to setup user/group information in the chroot area
-differently from your normal system. For example, you could abbreviate
-the list of users and groups. Also, you can protect this information from
-being downloaded/uploaded by adding an exclude rule to the rsyncd.conf file
-(e.g. "exclude = /etc/**"). Note that having the exclusion affect uploads
-is a relatively new feature in rsync, so make sure your daemon is
-at least 2.6.3 to effect this. Also note that it is safest to exclude a
-directory and all its contents combining the rule "/some/dir/" with the
-rule "/some/dir/**" just to be sure that rsync will not allow deeper
-access to some of the excluded files inside the directory (rsync tries to
-do this automatically, but you might as well specify both to be extra
-sure).
-
-dit(bf(max connections)) The "max connections" option allows you to
+of the new root path, and of complicating the preservation of users and groups
+by name (see below).
+
+As an additional safety feature, you can specify a dot-dir in the module's
+"path" to indicate the point where the chroot should occur. This allows rsync
+to run in a chroot with a non-"/" path for the top of the transfer hierarchy.
+Doing this guards against unintended library loading (since those absolute
+paths will not be inside the transfer hierarchy unless you have used an unwise
+pathname), and lets you setup libraries for the chroot that are outside of the
+transfer. For example, specifying "/var/rsync/./module1" will chroot to the
+"/var/rsync" directory and set the inside-chroot path to "/module1". If you
+had omitted the dot-dir, the chroot would have used the whole path, and the
+inside-chroot path would have been "/".
+
+When both "use chroot" and "daemon chroot" are false, OR the inside-chroot path
+of "use chroot" is not "/", rsync will: (1) munge symlinks by
+default for security reasons (see "munge symlinks" for a way to turn this
+off, but only if you trust your users), (2) substitute leading slashes in
+absolute paths with the module's path (so that options such as
+bf(--backup-dir), bf(--compare-dest), etc. interpret an absolute path as
+rooted in the module's "path" dir), and (3) trim ".." path elements from
+args if rsync believes they would escape the module hierarchy.
+The default for "use chroot" is true, and is the safer choice (especially
+if the module is not read-only).
+
+When this parameter is enabled, the "numeric-ids" option will also default to
+being enabled (disabling name lookups). See below for what a chroot needs in
+order for name lookups to succeed.
+
+If you copy library resources into the module's chroot area, you
+should protect them through your OS's normal user/group or ACL settings (to
+prevent the rsync module's user from being able to change them), and then
+hide them from the user's view via "exclude" (see how in the discussion of
+that parameter). At that point it will be safe to enable the mapping of users
+and groups by name using the "numeric ids" daemon parameter (see below).
+
+Note also that you are free to setup custom user/group information in the
+chroot area that is different from your normal system. For example, you
+could abbreviate the list of users and groups.
+
+dit(bf(daemon chroot)) This parameter specifies a path to which the daemon will
+chroot before beginning communication with clients. Module paths (and any "use
+chroot" settings) will then be related to this one. This lets you choose if you
+want the whole daemon to be chrooted (with this setting), just the transfers to
+be chrooted (with "use chroot"), or both. Keep in mind that the "daemon chroot"
+area may need various OS/lib/etc files installed to allow the daemon to function.
+By default the daemon runs without any chrooting.
+
+dit(bf(numeric ids)) Enabling this parameter disables the mapping
+of users and groups by name for the current daemon module. This prevents
+the daemon from trying to load any user/group-related files or libraries.
+This enabling makes the transfer behave as if the client had passed
+the bf(--numeric-ids) command-line option. By default, this parameter is
+enabled for chroot modules and disabled for non-chroot modules.
+Also keep in mind that uid/gid preservation requires the module to be
+running as root (see "uid") or for "fake super" to be configured.
+
+A chroot-enabled module should not have this parameter enabled unless you've
+taken steps to ensure that the module has the necessary resources it needs
+to translate names, and that it is not possible for a user to change those
+resources. That includes being the code being able to call functions like
+code(getpwuid()), code(getgrgid()), code(getpwname()), and code(getgrnam()).
+You should test what libraries and config files are required for your OS
+and get those setup before starting to test name mapping in rsync.
+
+dit(bf(munge symlinks)) This parameter tells rsync to modify
+all symlinks in the same way as the (non-daemon-affecting)
+bf(--munge-links) command-line option (using a method described below).
+This should help protect your files from user trickery when
+your daemon module is writable. The default is disabled when "use chroot"
+is on with an inside-chroot path of "/", OR if "daemon chroot" is on,
+otherwise it is enabled.
+
+If you disable this parameter on a daemon that is not read-only, there
+are tricks that a user can play with uploaded symlinks to access
+daemon-excluded items (if your module has any), and, if "use chroot"
+is off, rsync can even be tricked into showing or changing data that
+is outside the module's path (as access-permissions allow).
+
+The way rsync disables the use of symlinks is to prefix each one with
+the string "/rsyncd-munged/". This prevents the links from being used
+as long as that directory does not exist. When this parameter is enabled,
+rsync will refuse to run if that path is a directory or a symlink to
+a directory. When using the "munge symlinks" parameter in a chroot area
+that has an inside-chroot path of "/", you should add "/rsyncd-munged/"
+to the exclude setting for the module so that
+a user can't try to create it.
+
+Note: rsync makes no attempt to verify that any pre-existing symlinks in
+the module's hierarchy are as safe as you want them to be (unless, of
+course, it just copied in the whole hierarchy). If you setup an rsync
+daemon on a new area or locally add symlinks, you can manually protect your
+symlinks from being abused by prefixing "/rsyncd-munged/" to the start of
+every symlink's value. There is a perl script in the support directory
+of the source code named "munge-symlinks" that can be used to add or remove
+this prefix from your symlinks.
+
+When this parameter is disabled on a writable module and "use chroot" is off
+(or the inside-chroot path is not "/"),
+incoming symlinks will be modified to drop a leading slash and to remove ".."
+path elements that rsync believes will allow a symlink to escape the module's
+hierarchy. There are tricky ways to work around this, though, so you had
+better trust your users if you choose this combination of parameters.
+
+dit(bf(charset)) This specifies the name of the character set in which the
+module's filenames are stored. If the client uses an bf(--iconv) option,
+the daemon will use the value of the "charset" parameter regardless of the
+character set the client actually passed. This allows the daemon to
+support charset conversion in a chroot module without extra files in the
+chroot area, and also ensures that name-translation is done in a consistent
+manner. If the "charset" parameter is not set, the bf(--iconv) option is
+refused, just as if "iconv" had been specified via "refuse options".
+
+If you wish to force users to always use bf(--iconv) for a particular
+module, add "no-iconv" to the "refuse options" parameter. Keep in mind
+that this will restrict access to your module to very new rsync clients.
+
+dit(bf(max connections)) This parameter allows you to