puppet 4.4.0-universal-darwin

data/lib/puppet/type/file/group.rb

@@ -0,0 +1,41 @@
+require 'puppet/util/posix'
+
+module Puppet
+  # Manage file group ownership.
+  Puppet::Type.type(:file).newproperty(:group) do
+    desc <<-EOT
+      Which group should own the file.  Argument can be either a group
+      name or a group ID.
+
+      On Windows, a user (such as "Administrator") can be set as a file's group
+      and a group (such as "Administrators") can be set as a file's owner;
+      however, a file's owner and group shouldn't be the same. (If the owner
+      is also the group, files with modes like `0640` will cause log churn, as
+      they will always appear out of sync.)
+    EOT
+
+    validate do |group|
+      raise(Puppet::Error, "Invalid group name '#{group.inspect}'") unless group and group != ""
+    end
+
+    def insync?(current)
+      # We don't want to validate/munge groups until we actually start to
+      # evaluate this property, because they might be added during the catalog
+      # apply.
+      @should.map! do |val|
+        provider.name2gid(val) or raise "Could not find group #{val}"
+      end
+
+      @should.include?(current)
+    end
+
+    # We want to print names, not numbers
+    def is_to_s(currentvalue)
+      provider.gid2name(currentvalue) || currentvalue
+    end
+
+    def should_to_s(newvalue)
+      provider.gid2name(newvalue) || newvalue
+    end
+  end
+end

data/lib/puppet/type/file/mode.rb

@@ -0,0 +1,173 @@
+# Manage file modes.  This state should support different formats
+# for specification (e.g., u+rwx, or -0011), but for now only supports
+# specifying the full mode.
+
+
+module Puppet
+  Puppet::Type.type(:file).newproperty(:mode) do
+    require 'puppet/util/symbolic_file_mode'
+    include Puppet::Util::SymbolicFileMode
+
+    desc <<-'EOT'
+      The desired permissions mode for the file, in symbolic or numeric
+      notation. This value **must** be specified as a string; do not use
+      un-quoted numbers to represent file modes.
+
+      The `file` type uses traditional Unix permission schemes and translates
+      them to equivalent permissions for systems which represent permissions
+      differently, including Windows. For detailed ACL controls on Windows,
+      you can leave `mode` unmanaged and use
+      [the puppetlabs/acl module.](https://forge.puppetlabs.com/puppetlabs/acl)
+
+      Numeric modes should use the standard octal notation of
+      `<SETUID/SETGID/STICKY><OWNER><GROUP><OTHER>` (e.g. '0644').
+
+      * Each of the "owner," "group," and "other" digits should be a sum of the
+        permissions for that class of users, where read = 4, write = 2, and
+        execute/search = 1.
+      * The setuid/setgid/sticky digit is also a sum, where setuid = 4, setgid = 2,
+        and sticky = 1.
+      * The setuid/setgid/sticky digit is optional. If it is absent, Puppet will
+        clear any existing setuid/setgid/sticky permissions. (So to make your intent
+        clear, you should use at least four digits for numeric modes.)
+      * When specifying numeric permissions for directories, Puppet sets the search
+        permission wherever the read permission is set.
+
+      Symbolic modes should be represented as a string of comma-separated
+      permission clauses, in the form `<WHO><OP><PERM>`:
+
+      * "Who" should be u (user), g (group), o (other), and/or a (all)
+      * "Op" should be = (set exact permissions), + (add select permissions),
+        or - (remove select permissions)
+      * "Perm" should be one or more of:
+          * r (read)
+          * w (write)
+          * x (execute/search)
+          * t (sticky)
+          * s (setuid/setgid)
+          * X (execute/search if directory or if any one user can execute)
+          * u (user's current permissions)
+          * g (group's current permissions)
+          * o (other's current permissions)
+
+      Thus, mode `0664` could be represented symbolically as either `a=r,ug+w`
+      or `ug=rw,o=r`.  However, symbolic modes are more expressive than numeric
+      modes: a mode only affects the specified bits, so `mode => 'ug+w'` will
+      set the user and group write bits, without affecting any other bits.
+
+      See the manual page for GNU or BSD `chmod` for more details
+      on numeric and symbolic modes.
+
+      On Windows, permissions are translated as follows:
+
+      * Owner and group names are mapped to Windows SIDs
+      * The "other" class of users maps to the "Everyone" SID
+      * The read/write/execute permissions map to the `FILE_GENERIC_READ`,
+        `FILE_GENERIC_WRITE`, and `FILE_GENERIC_EXECUTE` access rights; a
+        file's owner always has the `FULL_CONTROL` right
+      * "Other" users can't have any permissions a file's group lacks,
+        and its group can't have any permissions its owner lacks; that is, 0644
+        is an acceptable mode, but 0464 is not.
+    EOT
+
+    validate do |value|
+      if !value.is_a?(String)
+        raise Puppet::Error, "The file mode specification must be a string, not '#{value.class.name}'"
+      end
+      unless value.nil? or valid_symbolic_mode?(value)
+        raise Puppet::Error, "The file mode specification is invalid: #{value.inspect}"
+      end
+    end
+
+    munge do |value|
+      return nil if value.nil?
+
+      unless valid_symbolic_mode?(value)
+        raise Puppet::Error, "The file mode specification is invalid: #{value.inspect}"
+      end
+
+      normalize_symbolic_mode(value)
+    end
+
+    def desired_mode_from_current(desired, current)
+      current = current.to_i(8) if current.is_a? String
+      is_a_directory = @resource.stat && @resource.stat.directory?
+      symbolic_mode_to_int(desired, current, is_a_directory)
+    end
+
+    # If we're a directory, we need to be executable for all cases
+    # that are readable.  This should probably be selectable, but eh.
+    def dirmask(value)
+      if FileTest.directory?(resource[:path]) and value =~ /^\d+$/ then
+        value = value.to_i(8)
+        value |= 0100 if value & 0400 != 0
+        value |= 010 if value & 040 != 0
+        value |= 01 if value & 04 != 0
+        value = value.to_s(8)
+      end
+
+      value
+    end
+
+    # If we're not following links and we're a link, then we just turn
+    # off mode management entirely.
+    def insync?(currentvalue)
+      if stat = @resource.stat and stat.ftype == "link" and @resource[:links] != :follow
+        self.debug "Not managing symlink mode"
+        return true
+      else
+        return super(currentvalue)
+      end
+    end
+
+    def property_matches?(current, desired)
+      return false unless current
+      current_bits = normalize_symbolic_mode(current)
+      desired_bits = desired_mode_from_current(desired, current).to_s(8)
+      current_bits == desired_bits
+    end
+
+    # Ideally, dirmask'ing could be done at munge time, but we don't know if 'ensure'
+    # will eventually be a directory or something else. And unfortunately, that logic
+    # depends on the ensure, source, and target properties. So rather than duplicate
+    # that logic, and get it wrong, we do dirmask during retrieve, after 'ensure' has
+    # been synced.
+    def retrieve
+      if @resource.stat
+        @should &&= @should.collect { |s| self.dirmask(s) }
+      end
+
+      super
+    end
+
+    # Finally, when we sync the mode out we need to transform it; since we
+    # don't have access to the calculated "desired" value here, or the
+    # "current" value, only the "should" value we need to retrieve again.
+    def sync
+      current = @resource.stat ? @resource.stat.mode : 0644
+      set(desired_mode_from_current(@should[0], current).to_s(8))
+    end
+
+    def change_to_s(old_value, desired)
+      return super if desired =~ /^\d+$/
+
+      old_bits = normalize_symbolic_mode(old_value)
+      new_bits = normalize_symbolic_mode(desired_mode_from_current(desired, old_bits))
+      super(old_bits, new_bits) + " (#{desired})"
+    end
+
+    def should_to_s(should_value)
+      should_value.rjust(4, "0")
+    end
+
+    def is_to_s(currentvalue)
+      if currentvalue == :absent
+        # This can occur during audits---if a file is transitioning from
+        # present to absent the mode will have a value of `:absent`.
+        super
+      else
+        currentvalue.rjust(4, "0")
+      end
+    end
+  end
+end

data/lib/puppet/type/file/mtime.rb

@@ -0,0 +1,18 @@
+module Puppet
+  Puppet::Type.type(:file).newproperty(:mtime) do
+    desc %q{A read-only state to check the file mtime. On \*nix-like systems, this
+      is the time of the most recent change to the content of the file.}
+
+    def retrieve
+      current_value = :absent
+      if stat = @resource.stat
+        current_value = stat.mtime
+      end
+      current_value
+    end
+
+    validate do |val|
+      fail "mtime is read-only"
+    end
+  end
+end

data/lib/puppet/type/file/owner.rb

@@ -0,0 +1,44 @@
+module Puppet
+  Puppet::Type.type(:file).newproperty(:owner) do
+    include Puppet::Util::Warnings
+
+    desc <<-EOT
+      The user to whom the file should belong.  Argument can be a user name or a
+      user ID.
+
+      On Windows, a group (such as "Administrators") can be set as a file's owner
+      and a user (such as "Administrator") can be set as a file's group; however,
+      a file's owner and group shouldn't be the same. (If the owner is also
+      the group, files with modes like `0640` will cause log churn, as they
+      will always appear out of sync.)
+    EOT
+
+    def insync?(current)
+      # We don't want to validate/munge users until we actually start to
+      # evaluate this property, because they might be added during the catalog
+      # apply.
+      @should.map! do |val|
+        provider.name2uid(val) or raise "Could not find user #{val}"
+      end
+
+      return true if @should.include?(current)
+
+      unless Puppet.features.root?
+        warnonce "Cannot manage ownership unless running as root"
+        return true
+      end
+
+      false
+    end
+
+    # We want to print names, not numbers
+    def is_to_s(currentvalue)
+      provider.uid2name(currentvalue) || currentvalue
+    end
+
+    def should_to_s(newvalue)
+      provider.uid2name(newvalue) || newvalue
+    end
+  end
+end
+

data/lib/puppet/type/file/selcontext.rb

@@ -0,0 +1,124 @@
+# Manage SELinux context of files.
+#
+# This code actually manages three pieces of data in the context.
+#
+# [root@delenn files]# ls -dZ /
+# drwxr-xr-x  root root system_u:object_r:root_t         /
+#
+# The context of '/' here is 'system_u:object_r:root_t'.  This is
+# three separate fields:
+#
+# system_u is the user context
+# object_r is the role context
+# root_t is the type context
+#
+# All three of these fields are returned in a single string by the
+# output of the stat command, but set individually with the chcon
+# command.  This allows the user to specify a subset of the three
+# values while leaving the others alone.
+#
+# See https://www.nsa.gov/selinux/ for complete docs on SELinux.
+
+
+module Puppet
+  require 'puppet/util/selinux'
+
+  class SELFileContext < Puppet::Property
+    include Puppet::Util::SELinux
+
+    def retrieve
+      return :absent unless @resource.stat
+      context = self.get_selinux_current_context(@resource[:path])
+      parse_selinux_context(name, context)
+    end
+
+    def retrieve_default_context(property)
+      if @resource[:selinux_ignore_defaults] == :true
+        return nil
+      end
+
+      unless context = self.get_selinux_default_context(@resource[:path])
+        return nil
+      end
+
+      property_default = self.parse_selinux_context(property, context)
+      self.debug "Found #{property} default '#{property_default}' for #{@resource[:path]}" if not property_default.nil?
+      property_default
+    end
+
+    def insync?(value)
+      if not selinux_support?
+        debug("SELinux bindings not found. Ignoring parameter.")
+        true
+      elsif not selinux_label_support?(@resource[:path])
+        debug("SELinux not available for this filesystem. Ignoring parameter.")
+        true
+      else
+        super
+      end
+    end
+
+    def sync
+      self.set_selinux_context(@resource[:path], @should, name)
+      :file_changed
+    end
+  end
+
+  Puppet::Type.type(:file).newparam(:selinux_ignore_defaults) do
+    desc "If this is set then Puppet will not ask SELinux (via matchpathcon) to
+      supply defaults for the SELinux attributes (seluser, selrole,
+      seltype, and selrange). In general, you should leave this set at its
+      default and only set it to true when you need Puppet to not try to fix
+      SELinux labels automatically."
+    newvalues(:true, :false)
+
+    defaultto :false
+  end
+
+  Puppet::Type.type(:file).newproperty(:seluser, :parent => Puppet::SELFileContext) do
+    desc "What the SELinux user component of the context of the file should be.
+      Any valid SELinux user component is accepted.  For example `user_u`.
+      If not specified it defaults to the value returned by matchpathcon for
+      the file, if any exists.  Only valid on systems with SELinux support
+      enabled."
+
+    @event = :file_changed
+    defaultto { self.retrieve_default_context(:seluser) }
+  end
+
+  Puppet::Type.type(:file).newproperty(:selrole, :parent => Puppet::SELFileContext) do
+    desc "What the SELinux role component of the context of the file should be.
+      Any valid SELinux role component is accepted.  For example `role_r`.
+      If not specified it defaults to the value returned by matchpathcon for
+      the file, if any exists.  Only valid on systems with SELinux support
+      enabled."
+
+    @event = :file_changed
+    defaultto { self.retrieve_default_context(:selrole) }
+  end
+
+  Puppet::Type.type(:file).newproperty(:seltype, :parent => Puppet::SELFileContext) do
+    desc "What the SELinux type component of the context of the file should be.
+      Any valid SELinux type component is accepted.  For example `tmp_t`.
+      If not specified it defaults to the value returned by matchpathcon for
+      the file, if any exists.  Only valid on systems with SELinux support
+      enabled."
+
+    @event = :file_changed
+    defaultto { self.retrieve_default_context(:seltype) }
+  end
+
+  Puppet::Type.type(:file).newproperty(:selrange, :parent => Puppet::SELFileContext) do
+    desc "What the SELinux range component of the context of the file should be.
+      Any valid SELinux range component is accepted.  For example `s0` or
+      `SystemHigh`.  If not specified it defaults to the value returned by
+      matchpathcon for the file, if any exists.  Only valid on systems with
+      SELinux support enabled and that have support for MCS (Multi-Category
+      Security)."
+
+    @event = :file_changed
+    defaultto { self.retrieve_default_context(:selrange) }
+  end
+
+end
+

data/lib/puppet/type/file/source.rb

@@ -0,0 +1,346 @@
+require 'puppet/file_serving/content'
+require 'puppet/file_serving/metadata'
+require 'puppet/file_serving/terminus_helper'
+
+require 'puppet/util/http_proxy'
+require 'puppet/network/http'
+require 'puppet/network/http/api/indirected_routes'
+require 'puppet/network/http/compression'
+
+module Puppet
+  # Copy files from a local or remote source.  This state *only* does any work
+  # when the remote file is an actual file; in that case, this state copies
+  # the file down.  If the remote file is a dir or a link or whatever, then
+  # this state, during retrieval, modifies the appropriate other states
+  # so that things get taken care of appropriately.
+  Puppet::Type.type(:file).newparam(:source) do
+    include Puppet::Network::HTTP::Compression.module
+
+    attr_accessor :source, :local
+    desc <<-'EOT'
+      A source file, which will be copied into place on the local system. This
+      attribute is mutually exclusive with `content` and `target`. Allowed
+      values are:
+
+      * `puppet:` URIs, which point to files in modules or Puppet file server
+      mount points.
+      * Fully qualified paths to locally available files (including files on NFS
+      shares or Windows mapped drives).
+      * `file:` URIs, which behave the same as local file paths.
+      * `http:` URIs, which point to files served by common web servers
+
+      The normal form of a `puppet:` URI is:
+
+      `puppet:///modules/<MODULE NAME>/<FILE PATH>`
+
+      This will fetch a file from a module on the Puppet master (or from a
+      local module when using Puppet apply). Given a `modulepath` of
+      `/etc/puppetlabs/code/modules`, the example above would resolve to
+      `/etc/puppetlabs/code/modules/<MODULE NAME>/files/<FILE PATH>`.
+
+      Unlike `content`, the `source` attribute can be used to recursively copy
+      directories if the `recurse` attribute is set to `true` or `remote`. If
+      a source directory contains symlinks, use the `links` attribute to
+      specify whether to recreate links or follow them.
+
+      *HTTP* URIs cannot be used to recursively synchronize whole directory
+      trees. It is also not possible to use `source_permissions` values other
+      than `ignore`. That's because HTTP servers do not transfer any metadata
+      that translates to ownership or permission details.
+
+      Multiple `source` values can be specified as an array, and Puppet will
+      use the first source that exists. This can be used to serve different
+      files to different system types:
+
+          file { "/etc/nfs.conf":
+            source => [
+              "puppet:///modules/nfs/conf.$host",
+              "puppet:///modules/nfs/conf.$operatingsystem",
+              "puppet:///modules/nfs/conf"
+            ]
+          }
+
+      Alternately, when serving directories recursively, multiple sources can
+      be combined by setting the `sourceselect` attribute to `all`.
+    EOT
+
+    validate do |sources|
+      sources = [sources] unless sources.is_a?(Array)
+      sources.each do |source|
+        next if Puppet::Util.absolute_path?(source)
+
+        begin
+          uri = URI.parse(URI.escape(source))
+        rescue => detail
+          self.fail Puppet::Error, "Could not understand source #{source}: #{detail}", detail
+        end
+
+        self.fail "Cannot use relative URLs '#{source}'" unless uri.absolute?
+        self.fail "Cannot use opaque URLs '#{source}'" unless uri.hierarchical?
+        unless %w{file puppet http https}.include?(uri.scheme)
+          self.fail "Cannot use URLs of type '#{uri.scheme}' as source for fileserving"
+        end
+      end
+    end
+
+    SEPARATOR_REGEX = [Regexp.escape(File::SEPARATOR.to_s), Regexp.escape(File::ALT_SEPARATOR.to_s)].join
+
+    munge do |sources|
+      sources = [sources] unless sources.is_a?(Array)
+      sources.map do |source|
+        source = self.class.normalize(source)
+
+        if Puppet::Util.absolute_path?(source)
+          URI.unescape(Puppet::Util.path_to_uri(source).to_s)
+        else
+          source
+        end
+      end
+    end
+
+    def self.normalize(source)
+      source.sub(/[#{SEPARATOR_REGEX}]+$/, '')
+    end
+
+    def change_to_s(currentvalue, newvalue)
+      # newvalue = "{md5}#{@metadata.checksum}"
+      if resource.property(:ensure).retrieve == :absent
+        return "creating from source #{metadata.source} with contents #{metadata.checksum}"
+      else
+        return "replacing from source #{metadata.source} with contents #{metadata.checksum}"
+      end
+    end
+
+    def checksum
+      metadata && metadata.checksum
+    end
+
+    # Look up (if necessary) and return local content.
+    def content
+      return @content if @content
+      raise Puppet::DevError, "No source for content was stored with the metadata" unless metadata.source
+
+      unless tmp = Puppet::FileServing::Content.indirection.find(metadata.source, :environment => resource.catalog.environment_instance, :links => resource[:links])
+        self.fail "Could not find any content at %s" % metadata.source
+      end
+      @content = tmp.content
+    end
+
+    # Copy the values from the source to the resource.  Yay.
+    def copy_source_values
+      devfail "Somehow got asked to copy source values without any metadata" unless metadata
+
+      # conditionally copy :checksum
+      if metadata.ftype != "directory" && !(metadata.ftype == "link" && metadata.links == :manage)
+        copy_source_value(:checksum)
+      end
+
+      # Take each of the stats and set them as states on the local file
+      # if a value has not already been provided.
+      [:owner, :mode, :group].each do |metadata_method|
+        next if metadata_method == :owner and !Puppet.features.root?
+        next if metadata_method == :group and !Puppet.features.root?
+
+        case resource[:source_permissions]
+        when :ignore
+          next
+        when :use_when_creating
+          next if Puppet::FileSystem.exist?(resource[:path])
+        end
+
+        copy_source_value(metadata_method)
+      end
+
+      if resource[:ensure] == :absent
+        # We know all we need to
+      elsif metadata.ftype != "link"
+        resource[:ensure] = metadata.ftype
+      elsif resource[:links] == :follow
+        resource[:ensure] = :present
+      else
+        resource[:ensure] = "link"
+        resource[:target] = metadata.destination
+      end
+    end
+
+    attr_writer :metadata
+
+    # Provide, and retrieve if necessary, the metadata for this file.  Fail
+    # if we can't find data about this host, and fail if there are any
+    # problems in our query.
+    def metadata
+      return @metadata if @metadata
+
+      if @metadata = resource.catalog.metadata[resource.title]
+        return @metadata
+      end
+
+      return nil unless value
+      value.each do |source|
+        begin
+          options = {
+            :environment          => resource.catalog.environment_instance,
+            :links                => resource[:links],
+            :checksum_type        => resource[:checksum],
+            :source_permissions   => resource[:source_permissions]
+          }
+
+          if data = Puppet::FileServing::Metadata.indirection.find(source, options)
+            @metadata = data
+            @metadata.source = source
+            break
+          end
+        rescue => detail
+          self.fail Puppet::Error, "Could not retrieve file metadata for #{source}: #{detail}", detail
+        end
+      end
+      self.fail "Could not retrieve information from environment #{resource.catalog.environment} source(s) #{value.join(", ")}" unless @metadata
+      @metadata
+    end
+
+    def local?
+      found? and scheme == "file"
+    end
+
+    def full_path
+      Puppet::Util.uri_to_path(uri) if found?
+    end
+
+    def server?
+       uri and uri.host
+    end
+
+    def server
+      (uri and uri.host) or Puppet.settings[:server]
+    end
+
+    def port
+      (uri and uri.port) or Puppet.settings[:masterport]
+    end
+
+    def uri
+      @uri ||= URI.parse(URI.escape(metadata.source))
+    end
+
+    def write(file)
+      resource.parameter(:checksum).sum_stream { |sum|
+        each_chunk_from { |chunk|
+          sum << chunk
+          file.print chunk
+        }
+      }
+    end
+
+    private
+
+    def scheme
+      (uri and uri.scheme)
+    end
+
+    def found?
+      ! (metadata.nil? or metadata.ftype.nil?)
+    end
+
+    def copy_source_value(metadata_method)
+      param_name = (metadata_method == :checksum) ? :content : metadata_method
+      if resource[param_name].nil? or resource[param_name] == :absent
+        if Puppet.features.microsoft_windows? && [:owner, :group, :mode].include?(metadata_method)
+          devfail "Should not have tried to use source owner/mode/group on Windows"
+        end
+
+        value = metadata.send(metadata_method)
+        # Force the mode value in file resources to be a string containing octal.
+        value = value.to_s(8) if param_name == :mode && value.is_a?(Numeric)
+        resource[param_name] = value
+
+        if (metadata_method == :checksum)
+          # If copying checksum, also copy checksum_type
+          resource[:checksum] = metadata.checksum_type
+        end
+      end
+    end
+
+    def each_chunk_from
+      if Puppet[:default_file_terminus] == :file_server
+        yield content
+      elsif local?
+        chunk_file_from_disk { |chunk| yield chunk }
+      else
+        chunk_file_from_source { |chunk| yield chunk }
+      end
+    end
+
+    def chunk_file_from_disk
+      File.open(full_path, "rb") do |src|
+        while chunk = src.read(8192)
+          yield chunk
+        end
+      end
+    end
+
+    def get_from_puppet_source(source_uri, content_uri, &block)
+      options = { :environment => resource.catalog.environment_instance }
+      if content_uri
+        options[:code_id] = resource.catalog.code_id
+        request = Puppet::Indirector::Request.new(:static_file_content, :find, content_uri, nil, options)
+      else
+        request = Puppet::Indirector::Request.new(:file_content, :find, source_uri, nil, options)
+      end
+
+      request.do_request(:fileserver) do |req|
+        connection = Puppet::Network::HttpPool.http_instance(req.server, req.port)
+        connection.request_get(Puppet::Network::HTTP::API::IndirectedRoutes.request_to_uri(req), add_accept_encoding({"Accept" => "binary"}), &block)
+      end
+    end
+
+    def get_from_http_source(source_uri, &block)
+      Puppet::Util::HttpProxy.request_with_redirects(URI(source_uri), :get, &block)
+    end
+
+    def get_from_source(&block)
+      source_uri = metadata.source
+      if source_uri =~ /^https?:/
+        get_from_http_source(source_uri, &block)
+      else
+        get_from_puppet_source(source_uri, metadata.content_uri, &block)
+      end
+    end
+
+
+    def chunk_file_from_source
+      get_from_source do |response|
+        case response.code
+        when /^2/;  uncompress(response) { |uncompressor| response.read_body { |chunk| yield uncompressor.uncompress(chunk) } }
+        else
+          # Raise the http error if we didn't get a 'success' of some kind.
+          message = "Error #{response.code} on SERVER: #{(response.body||'').empty? ? response.message : uncompress_body(response)}"
+          raise Net::HTTPError.new(message, response)
+        end
+      end
+    end
+  end
+
+  Puppet::Type.type(:file).newparam(:source_permissions) do
+    desc <<-'EOT'
+      Whether (and how) Puppet should copy owner, group, and mode permissions from
+      the `source` to `file` resources when the permissions are not explicitly
+      specified. (In all cases, explicit permissions will take precedence.)
+      Valid values are `use`, `use_when_creating`, and `ignore`:
+
+      * `ignore` (the default) will never apply the owner, group, or mode from
+        the `source` when managing a file. When creating new files without explicit
+        permissions, the permissions they receive will depend on platform-specific
+        behavior. On POSIX, Puppet will use the umask of the user it is running as.
+        On Windows, Puppet will use the default DACL associated with the user it is
+        running as.
+      * `use` will cause Puppet to apply the owner, group,
+        and mode from the `source` to any files it is managing.
+      * `use_when_creating` will only apply the owner, group, and mode from the
+        `source` when creating a file; existing files will not have their permissions
+        overwritten.
+    EOT
+
+    defaultto :ignore
+    newvalues(:use, :use_when_creating, :ignore)
+  end
+end