[PATCH] Attempt to rewrite the description of the filter parameters in rsyncd.conf.yo.

[Matt McCutchen]

- Collect material that applies to all daemon filters in the documentation of
  the "filter" parameter, and make it more complete and coherent.
- Amplify the recommendation to exclude entire subtrees properly since the
  excluded_below check is easy to circumvent and I have proposed removing it
  altogether.
- The `Only one "X" parameter can apply to a given module' wording is meant to
  avoid misleading people to think that they can't have different parameters for
  different modules.
---

I'm hoping everything I wrote here is complete and correct and I didn't
lose any information compared to the previous version, but this could
use some serious review.  The change is pullable from branch "wip" of my
repository at:

http://mattmccutchen.net/rsync/rsync.git/

Matt

 rsyncd.conf.yo |   85 +++++++++++++++++++++++++------------------------------
 1 files changed, 39 insertions(+), 46 deletions(-)

diff --git a/rsyncd.conf.yo b/rsyncd.conf.yo
index f17e3d5..9e36f79 100644
--- a/rsyncd.conf.yo
+++ b/rsyncd.conf.yo
@@ -314,56 +314,49 @@ daemon side to behave as if the bf(--fake-user) command-line option had
 been specified.  This allows the full attributes of a file to be stored
 without having to have the daemon actually running as root.
 
-dit(bf(filter)) The "filter" option allows you to specify a space-separated
-list of filter rules that the daemon will not allow to be read or written.
-This is only superficially equivalent to the client specifying these
-patterns with the bf(--filter) option.  Only one "filter" option may be
-specified, but it may contain as many rules as you like, including
-merge-file rules.  Note that per-directory merge-file rules do not provide
+dit(bf(filter)) The daemon has its own filter chain that determines what files
+it will let the client access.  This chain is not sent to the client and is
+independent of any filters the client may have specified.  Files excluded by the
+daemon filter chain (bf(daemon-excluded) files) are silently omitted from the
+file-list if the client tries to pull them, are skipped with an error message
+and exit code 23 if the client tries to push them, and are never deleted from
+the module.  You can use daemon filters to prevent clients from downloading or
+tampering with private administrative files such as user and group files.
+
+The daemon filter chain is built from the "filter", "include from", "include",
+"exclude from", and "exclude" parameters, in that order of priority.  Anchored
+patterns are anchored at the root of the module.  To prevent access to an
+entire subtree, say "/secret", you em(must) exclude everything in the subtree;
+the easiest way to do this is with a triple-star pattern like "/secret/***".  If
+you just exclude "/secret", the client can't mess with the attributes of
+"/secret" itself but can still list "/secret" using a wildcard and access files
+inside by specifying them individually.
+
+The "filter" parameter takes a space-separated list of daemon filter rules;
+merge-file rules are allowed.  (Since spaces separate rules, you must use an
+underscore between the rule type and the pattern, e.g., "+_/foo -_/bar".)  Only
+one "filter" parameter can apply to a given module, so put all the rules you
+want in a single parameter.
+Note that per-directory merge-file rules do not provide
 as much protection as global rules, but they can be used to make bf(--delete)
 work better when a client downloads the daemon's files (if the per-dir
 merge files are included in the transfer).
 
-dit(bf(exclude)) The "exclude" option allows you to specify a
-space-separated list of patterns that the daemon will not allow to be read
-or written.  This is only superficially equivalent to the client
-specifying these patterns with the bf(--exclude) option.  Only one "exclude"
-option may be specified, but you can use "-" and "+" before patterns to
-specify exclude/include.
-
-Because this exclude list is not passed to the client it only applies on
-the daemon: that is, it excludes files received by a client when receiving
-from a daemon and files deleted on a daemon when sending to a daemon, but
-it doesn't exclude files from being deleted on a client when receiving
-from a daemon.
-
-When you want to exclude a directory and all its contents, it is safest to
-use a rule that does both, such as "/some/dir/***" (the three stars tells
-rsync to exclude the directory itself and everything inside it).  This is
-better than just excluding the directory alone with "/some/dir/", as it
-helps to guard against attempts to trick rsync into accessing files deeper
-in the hierarchy.
-
-dit(bf(exclude from)) The "exclude from" option specifies a filename
-on the daemon that contains exclude patterns, one per line.
-This is only superficially equivalent
-to the client specifying the bf(--exclude-from) option with an equivalent file.
-See the "exclude" option above.
-
-dit(bf(include)) The "include" option allows you to specify a
-space-separated list of patterns which rsync should not exclude. This is
-only superficially equivalent to the client specifying these patterns with
-the bf(--include) option because it applies only on the daemon.  This is
-useful as it allows you to build up quite complex exclude/include rules.
-Only one "include" option may be specified, but you can use "+" and "-"
-before patterns to switch include/exclude.  See the "exclude" option
-above.
-
-dit(bf(include from)) The "include from" option specifies a filename
-on the daemon that contains include patterns, one per line. This is
-only superficially equivalent to the client specifying the
-bf(--include-from) option with a equivalent file.
-See the "exclude" option above.
+dit(bf(exclude)) The "exclude" parameter takes a space-separated list of daemon
+exclude patterns.  As with the bf(--exclude) option, patterns can be qualified
+with "- " or "+ " to explicitly indicate exclude/include.  Only one "exclude"
+parameter can apply to a given module.
+
+dit(bf(include)) Analogue of "exclude" for daemon include patterns.  Only one
+"include" parameter can apply to a given module.
+
+dit(bf(exclude from)) The "exclude from" option specifies the name of a file on
+the daemon that contains daemon exclude patterns, one per line.  Only one
+"exclude from" parameter can apply to a given module; if you have multiple
+exclude-from files, specify some in the "filter" parameter.
+
+dit(bf(include from)) Analogue of "exclude from" for a file of daemon include
+patterns.  Only one "include from" parameter can apply to a given module.
 
 dit(bf(incoming chmod)) This option allows you to specify a set of
 comma-separated chmod strings that will affect the permissions of all
-- 
1.5.4.3.193.g6dd0e