(#17448/#17449/#18045) Update fileserver.conf and auth.conf examples

These files still referred to the regime whereby access control lived in
both files and auth.conf usually delegated to fileserver.conf, except
when it didn't. In the meantime, we've improved auth.conf and partially
broken fileserver.conf, and in conversations with the core team, it's
become clear that we don't necessarily WANT to fix fileserver.conf,
especially if not doing so will lead to better and more centralized
access control.

Unfortunately, an awkward period seems unavoidable. This commit
attempts to describe what users SHOULD do and give enough hints that it
will be easy to do so, at the cost of a certain windiness.

NOTE ESPECIALLY that we're now using the word "deprecated," as the
warnings-and-prefs-based deprecation plan outlined at #18045 has been accepted.

2 files changed, 80 insertions, 36 deletions

diff --git a/conf/auth.conf b/conf/auth.conf
index 56a87ca61..07e5a34b6 100644
--- a/conf/auth.conf
+++ b/conf/auth.conf
@@ -1,15 +1,19 @@
-# This is an example auth.conf file, which implements the
-# defaults used by the puppet master.
+# This is the default auth.conf file, which implements the default rules
+# used by the puppet master. (That is, the rules below will still apply
+# even if this file is deleted.)
 #
-# 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.
+# The ACLs are evaluated in top-down order. More specific stanzas should
+# be towards the top of the file and more general ones at the bottom;
+# otherwise, the general rules may "steal" requests that should be
+# governed by the specific rules.
+#
+# See http://docs.puppetlabs.com/guides/rest_auth_conf.html for a more complete
+# description of auth.conf's behavior.
 #
 # Supported syntax:
-# Each stanza in auth.conf starts with a path to mach, followed
+# Each stanza in auth.conf starts with a path to match, followed
 # by optional modifiers, and finally, a series of allow or deny
-# directives. 
+# directives.
 #
 # Example Stanza
 # ---------------------------------
@@ -18,25 +22,33 @@
 # [environment envlist]
 # [method methodlist]
 # [auth[enthicated] {yes|no|on|off|any}]
-# allow [host|backreference|*]
-# deny [host|backreference|*]
+# allow [host|backreference|*|regex]
+# deny [host|backreference|*|regex]
 # allow_ip [ip|cidr|ip_wildcard|*]
 # deny_ip [ip|cidr|ip_wildcard|*]
 #
-# The path match can either be a simple prefix match or a regular 
+# 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
 #
 # Examples:
-# path ~ ^/path/to/resource    # equivalent to `path /path/to/resource`
-# allow *
 #
-# path ~ ^/catalog/([^/]+)$    # permit access only for the
-# allow $1                     # node whose cert matches the path
+# path ~ ^/path/to/resource    # Equivalent to `path /path/to/resource`.
+# allow *                      # Allow all authenticated nodes (since auth
+#                              # defaults to `yes`).
+#
+# path ~ ^/catalog/([^/]+)$    # Permit nodes to access their own catalog (by
+# allow $1                     # certname), but not any other node's catalog.
+#
+# path ~ ^/file_(metadata|content)/extra_files/  # Only allow certain nodes to
+# auth yes                                       # access the "extra_files"
+# allow /^(.+)\.example\.com$/                   # mount point; note this must
+# allow_ip 192.168.100.0/24                      # go ABOVE the "/file" rule,
+#                                                # since it is more specific.
 #
 # environment:: restrict an ACL to a comma-separated list of environments
 # method:: restrict an ACL to a comma-separated list of HTTP methods
@@ -45,7 +57,7 @@
 # (ie exactly as if auth yes was present).
 #
 
-### Authenticated paths - these apply only when the client
+### Authenticated ACLs - these rules apply only when the client
 ### has a valid certificate and is thus authenticated
 
 # allow nodes to retrieve their own catalog
@@ -68,33 +80,37 @@ path /report
 method save
 allow *
 
-# unconditionally allow access to all file services
-# which means in practice that fileserver.conf will
-# still be used
+# Allow all nodes to access all file services; this is necessary for
+# pluginsync, file serving from modules, and file serving from custom
+# mount points (see fileserver.conf). Note that the `/file` prefix matches
+# requests to both the file_metadata and file_content paths. See "Examples"
+# above if you need more granular access control for custom mount points.
 path /file
 allow *
 
-### Unauthenticated ACL, for clients for which the current master doesn't
-### have a valid certificate; we allow authenticated users, too, because
-### there isn't a great harm in letting that request through.
+### Unauthenticated ACLs, for clients without valid certificates; authenticated
+### clients can also access these paths, though they rarely need to.
 
-# allow access to the master CA
+# allow access to the CA certificate; unauthenticated nodes need this
+# in order to validate the puppet master's certificate
 path /certificate/ca
 auth any
 method find
 allow *
 
+# allow nodes to retrieve the certificate they requested earlier
 path /certificate/
 auth any
 method find
 allow *
 
+# allow nodes to request a new certificate
 path /certificate_request
 auth any
 method find, save
 allow *
 
-# this one is not stricly necessary, but it has the merit
-# of showing the default policy, which is deny everything else
+# deny everything else; this ACL is not strictly necessary, but
+# illustrates the default policy.
 path /
 auth any
diff --git a/conf/fileserver.conf b/conf/fileserver.conf
index 163ce1220..62598c4e3 100644
--- a/conf/fileserver.conf
+++ b/conf/fileserver.conf
@@ -1,13 +1,41 @@
-# $Id$
+# fileserver.conf
 
-[dist]
-    path /dist
-    allow *.puppetlabs.com
+# Puppet automatically serves PLUGINS and FILES FROM MODULES: anything in
+# <module name>/files/<file name> is available to authenticated nodes at
+# puppet:///modules/<module name>/<file name>. You do not need to edit this
+# file to enable this.
 
-[plugins]
-    path /var/lib/puppet/plugins
-    allow *.puppetlabs.com
+# MOUNT POINTS
 
-[facts]
-    path /var/lib/puppet/facts
-    allow *.puppetlabs.com
+# If you need to serve files from a directory that is NOT in a module,
+# you must create a static mount point in this file:
+#
+# [extra_files]
+#   path /etc/puppet/files
+#   allow *
+#
+# In the example above, anything in /etc/puppet/files/<file name> would be
+# available to authenticated nodes at puppet:///extra_files/<file name>.
+#
+# Mount points may also use three placeholders as part of their path:
+#
+# %H - The node's certname.
+# %h - The portion of the node's certname before the first dot. (Usually the
+#      node's short hostname.)
+# %d - The portion of the node's certname after the first dot. (Usually the
+#      node's domain name.)
+
+# PERMISSIONS
+
+# Every static mount point should have an `allow *` line; setting more
+# granular permissions in this file is deprecated. Instead, you can
+# control file access in auth.conf by controlling the
+# /file_metadata/<mount point> and /file_content/<mount point> paths:
+#
+# path ~ ^/file_(metadata|content)/extra_files/
+# auth yes
+# allow /^(.+)\.example\.com$/
+# allow_ip 192.168.100.0/24
+#
+# If added to auth.conf BEFORE the "path /file" rule, the rule above
+# will add stricter restrictions to the extra_files mount point.