Merge pull request #1369 from nfagerlund/fileserver_conf

Fileserver conf/auth.conf improvements

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

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.

conf/tagmail.conf

@@ -1 +1,16 @@
-all: user@domain.com
+# tagmail.conf
+
+# This file configures the `tagmail` report, which can be enabled by including
+# tagmail in the puppet master's `reports` setting. (`reports = https, tagmail`)
+
+# Each line in this file should consist of a comma-separated list of tags and/or
+# negated tags (`!tag`), a colon, and a comma-separated list of email addresses.
+# The `all` psuedo-tag will email all log events.
+# See http://docs.puppetlabs.com/guides/configuring.html#tagmailconf for
+# a complete description of this file.
+
+# Example:
+
+# all: log-archive@example.com
+# webserver, !mailserver: httpadmins@example.com
+# emerg, crit: james@example.com, zach@example.com, ben@example.com

ext/debian/fileserver.conf

@@ -1,17 +1,41 @@
-# This file consists of arbitrarily named sections/modules
-# defining where files are served from and to whom
+# fileserver.conf
 
-# Define a section 'files'
-# Adapt the allow/deny settings to your needs. Order
-# for allow/deny does not matter, allow always takes precedence
-# over deny
-#[files]
-#  path /etc/puppet/files
-#  allow *.example.com
-#  deny *.evil.example.com
-#  allow 192.168.0.0/24
+# 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]
-#  allow *.example.com
-#  deny *.evil.example.com
-#  allow 192.168.0.0/24
+# MOUNT POINTS
+
+# 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.

ext/gentoo/puppet/fileserver.conf

@@ -1,12 +1,41 @@
-# This file consists of arbitrarily named sections/modules
-# defining where files are served from and to whom
-
-# Define a section 'files'
-# Adapt the allow/deny settings to your needs. Order
-# for allow/deny does not matter, allow always takes precedence
-# over deny
-[files]
-  path /var/lib/puppet/files
-#  allow *.example.com
-#  deny *.evil.example.com
-#  allow 192.168.0.0/24
+# fileserver.conf
+
+# 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.
+
+# MOUNT POINTS
+
+# 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.

ext/redhat/fileserver.conf

@@ -1,12 +1,41 @@
-# This file consists of arbitrarily named sections/modules
-# defining where files are served from and to whom
-
-# Define a section 'files'
-# Adapt the allow/deny settings to your needs. Order
-# for allow/deny does not matter, allow always takes precedence
-# over deny
-# [files]
-#  path /var/lib/puppet/files
-#  allow *.example.com
-#  deny *.evil.example.com
-#  allow 192.168.0.0/24
+# fileserver.conf
+
+# 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.
+
+# MOUNT POINTS
+
+# 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.