Docs: REQUIRED in ident_regex, proxy_auth_regex, ext_user_regex (#1818)

The three ACLs were documented as matching any username when configured
with a parameter spelled "REQUIRED". Neither actually treated that
parameter specially -- all interpreted it as an ordinary regex.

This dangerous documentation bug was introduced in 2000 commit 145cf92
that added ident_regex and proxy_auth_regex support. It was then
duplicated in 2003 commit abb929f that added ext_user_regex support.

This minimal documentation fix does not imply that these ACLs should not
treat REQUIRED values specially. Enabling such special treatment
requires significant code changes, especially if we want to do that well
and without duplicating the corresponding code.

diff --git a/src/cf.data.pre b/src/cf.data.pre
index 920f349f2298fa96fddfbe43c194b1100649973d..56d41d95a02f695dad1210bcc68b3bb86573ef32 100644 (file)
--- a/src/cf.data.pre
+++ b/src/cf.data.pre
@@ -1258,18 +1258,29 @@ endif
          # Referer is highly unreliable, so use with care
 
        acl aclname ident [-i] username ...
-       acl aclname ident_regex [-i] pattern ...
          # string match on ident output [slow]
          # use REQUIRED to accept any non-null ident.
+         #
+         # See also: ident_regex. The two ACLs differ only in their parameter
+         # syntax and ident output matching algorithm.
+
+       acl aclname ident_regex [-i] username_pattern ...
+         # regex match on ident output [slow]
 
        acl aclname proxy_auth [-i] username ...
-       acl aclname proxy_auth_regex [-i] pattern ...
          # perform http authentication challenge to the client and match against
          # supplied credentials [slow]
          #
          # takes a list of allowed usernames.
          # use REQUIRED to accept any valid username.
          #
+         # See proxy_auth_regex for more information. The two ACLs differ only in
+         # their parameter syntax and username matching algorithm.
+
+       acl aclname proxy_auth_regex [-i] username_pattern ...
+         # perform http authentication challenge to the client and regex match
+         # supplied username [slow]
+         #
          # Will use proxy authentication in forward-proxy scenarios, and plain
          # http authentication in reverse-proxy scenarios
          #
@@ -1353,9 +1364,14 @@ endif
          # attribute is one of DN/C/O/CN/L/ST or a numerical OID  [fast]
 
        acl aclname ext_user [-i] username ...
-       acl aclname ext_user_regex [-i] pattern ...
          # string match on username returned by external acl helper [slow]
          # use REQUIRED to accept any non-null user name.
+         #
+         # See also: ext_user_regex. The two ACLs differ only in their parameter
+         # syntax and username matching algorithm.
+
+       acl aclname ext_user_regex [-i] username_pattern ...
+         # regex match on username returned by external acl helper [slow]
 
        acl aclname tag tagvalue ...
          # string match on tag returned by external acl helper [fast]