(#16184) Improve example auth.conf

auth.conf was outdated and did not include examples of the allow_ip
and deny_ip functionality. I tightened up the text a bit, fixed
spelling and grammar, and tried to improve the clarity of the doc.

1 files changed, 34 insertions, 34 deletions

diff --git a/conf/auth.conf b/conf/auth.conf
index ba389c076..56a87ca61 100644
--- a/conf/auth.conf
+++ b/conf/auth.conf
@@ -1,54 +1,54 @@
-# This is an example auth.conf file, it mimics the puppetmasterd defaults
+# This is an example auth.conf file, which implements the
+# defaults used by the puppet master.
 #
-# The ACL are checked in order of appearance in this file.
+# The ACLs are evaluated in top-down order. More general
+# stanzas should be towards the bottom of the file and more
+# specific ones at the top, otherwise the general rules
+# take precedence and later rules will not be evaluated.
 #
 # Supported syntax:
-# This file supports two different syntax depending on how
-# you want to express the ACL.
+# Each stanza in auth.conf starts with a path to mach, followed
+# by optional modifiers, and finally, a series of allow or deny
+# directives. 
 #
-# Path syntax (the one used below):
+# Example Stanza
 # ---------------------------------
-# path /path/to/resource
+# path /path/to/resource     # simple prefix match
+# # path ~ regex             # alternately, regex match
 # [environment envlist]
 # [method methodlist]
 # [auth[enthicated] {yes|no|on|off|any}]
-# allow [host|ip|*]
-# deny [host|ip]
+# allow [host|backreference|*]
+# deny [host|backreference|*]
+# allow_ip [ip|cidr|ip_wildcard|*]
+# deny_ip [ip|cidr|ip_wildcard|*]
 #
-# The path is matched as a prefix. That is /file match at
-# the same time /file_metadat and /file_content.
+# The path match can either be a simple prefix match or a regular 
+# expression. `path /file` would match both `/file_metadata` and
+# `/file_content`. Regex matches allow the use of backreferences
+# in the allow/deny directives.
+# 
+# The regex syntax is the same as for Ruby regex, and captures backreferences
+# for use in the `allow` and `deny` lines of that stanza
 #
-# Regex syntax:
-# -------------
-# This one is differenciated from the path one by a '~'
+# Examples:
+# path ~ ^/path/to/resource    # equivalent to `path /path/to/resource`
+# allow *
 #
-# path ~ regex
-# [environment envlist]
-# [method methodlist]
-# [auth[enthicated] {yes|no|on|off|any}]
-# allow [host|ip|*]
-# deny [host|ip]
-#
-# The regex syntax is the same as ruby ones.
-#
-# Ex:
-# path ~ .pp$
-# will match every resource ending in .pp (manifests files for instance)
-#
-# path ~ ^/path/to/resource
-# is essentially equivalent to path /path/to/resource
+# path ~ ^/catalog/([^/]+)$    # permit access only for the
+# allow $1                     # node whose cert matches the path
 #
-# environment:: restrict an ACL to a specific set of environments
-# method:: restrict an ACL to a specific set of methods
+# environment:: restrict an ACL to a comma-separated list of environments
+# method:: restrict an ACL to a comma-separated list of HTTP methods
 # auth:: restrict an ACL to an authenticated or unauthenticated request
 # the default when unspecified is to restrict the ACL to authenticated requests
 # (ie exactly as if auth yes was present).
 #
 
-### Authenticated ACL - those applies only when the client
+### Authenticated paths - these apply only when the client
 ### has a valid certificate and is thus authenticated
 
-# allow nodes to retrieve their own catalog (ie their configuration)
+# allow nodes to retrieve their own catalog
 path ~ ^/catalog/([^/]+)$
 method find
 allow $1
@@ -68,7 +68,7 @@ path /report
 method save
 allow *
 
-# inconditionnally allow access to all files services
+# unconditionally allow access to all file services
 # which means in practice that fileserver.conf will
 # still be used
 path /file
@@ -95,6 +95,6 @@ method find, save
 allow *
 
 # this one is not stricly necessary, but it has the merit
-# to show the default policy which is deny everything else
+# of showing the default policy, which is deny everything else
 path /
 auth any