puppet 4.1.0 → 4.10.0

data/lib/puppet/type/group.rb

@@ -79,8 +79,9 @@ module Puppet
     end
 
     newproperty(:members, :array_matching => :all, :required_features => :manages_members) do
-      desc "The members of the group. For directory services where group
-      membership is stored in the group objects, not the users."
+      desc "The members of the group. For platforms or directory services where group
+        membership is stored in the group objects, not the users. This parameter's
+        behavior can be configured with `auth_membership`."
 
       def change_to_s(currentvalue, newvalue)
         currentvalue = currentvalue.join(",") if currentvalue != :absent
@@ -99,16 +100,29 @@ module Puppet
       def is_to_s(currentvalue)
         if provider.respond_to?(:members_to_s)
           currentvalue = '' if currentvalue.nil?
-          return provider.members_to_s(currentvalue.split(','))
+          currentvalue = currentvalue.is_a?(Array) ? currentvalue : currentvalue.split(',')
+
+          return provider.members_to_s(currentvalue)
         end
 
         super(currentvalue)
       end
       alias :should_to_s :is_to_s
+
+      validate do |value|
+        if provider.respond_to?(:member_valid?)
+          return provider.member_valid?(value)
+        end
+      end
     end
 
     newparam(:auth_membership, :boolean => true, :parent => Puppet::Parameter::Boolean) do
-      desc "whether the provider is authoritative for group membership."
+      desc "Configures the behavior of the `members` parameter.
+
+        * `false` (default) --- The provided list of group members is partial,
+          and Puppet **ignores** any members that aren't listed there.
+        * `true` --- The provided list of of group members is comprehensive, and
+          Puppet **purges** any members that aren't listed there."
       defaultto false
     end
 
@@ -134,7 +148,8 @@ module Puppet
     end
 
     newproperty(:attributes, :parent => Puppet::Property::KeyValue, :required_features => :manages_aix_lam) do
-      desc "Specify group AIX attributes in an array of `key=value` pairs."
+      desc "Specify group AIX attributes, as an array of `'key=value'` strings. This
+        parameter's behavior can be configured with `attribute_membership`."
 
       def membership
         :attribute_membership
@@ -150,9 +165,12 @@ module Puppet
     end
 
     newparam(:attribute_membership) do
-      desc "Whether specified attribute value pairs should be treated as the only attributes
-        of the user or whether they should merely
-        be treated as the minimum list."
+      desc "AIX only. Configures the behavior of the `attributes` parameter.
+
+        * `minimum` (default) --- The provided list of attributes is partial, and Puppet
+          **ignores** any attributes that aren't listed there.
+        * `inclusive` --- The provided list of attributes is comprehensive, and
+          Puppet **purges** any attributes that aren't listed there."
 
       newvalues(:inclusive, :minimum)
 

data/lib/puppet/type/host.rb

@@ -17,7 +17,7 @@ module Puppet
 
       def valid_v6?(addr)
         # http://forums.dartware.com/viewtopic.php?t=452
-        # ...and, yes, it is this hard.  Doing it programatically is harder.
+        # ...and, yes, it is this hard. Doing it programmatically is harder.
         return true if addr =~ /^\s*((([0-9A-Fa-f]{1,4}:){7}([0-9A-Fa-f]{1,4}|:))|(([0-9A-Fa-f]{1,4}:){6}(:[0-9A-Fa-f]{1,4}|((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3})|:))|(([0-9A-Fa-f]{1,4}:){5}(((:[0-9A-Fa-f]{1,4}){1,2})|:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3})|:))|(([0-9A-Fa-f]{1,4}:){4}(((:[0-9A-Fa-f]{1,4}){1,3})|((:[0-9A-Fa-f]{1,4})?:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:))|(([0-9A-Fa-f]{1,4}:){3}(((:[0-9A-Fa-f]{1,4}){1,4})|((:[0-9A-Fa-f]{1,4}){0,2}:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:))|(([0-9A-Fa-f]{1,4}:){2}(((:[0-9A-Fa-f]{1,4}){1,5})|((:[0-9A-Fa-f]{1,4}){0,3}:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:))|(([0-9A-Fa-f]{1,4}:){1}(((:[0-9A-Fa-f]{1,4}){1,6})|((:[0-9A-Fa-f]{1,4}){0,4}:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:))|(:(((:[0-9A-Fa-f]{1,4}){1,7})|((:[0-9A-Fa-f]{1,4}){0,5}:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:)))(%.+)?\s*$/
 
         return false

data/lib/puppet/type/interface.rb

@@ -45,19 +45,24 @@ Puppet::Type.newtype(:interface) do
       newvalues(:auto, :full, :half)
     end
 
+    newproperty(:access_vlan) do
+      desc "Interface static access vlan."
+      newvalues(/^\d+/)
+    end
+
     newproperty(:native_vlan) do
-      desc "Interface native vlan (for access mode only)."
+      desc "Interface native vlan when trunking."
       newvalues(/^\d+/)
     end
 
     newproperty(:encapsulation) do
       desc "Interface switchport encapsulation."
-      newvalues(:none, :dot1q, :isl )
+      newvalues(:none, :dot1q, :isl, :negotiate)
     end
 
     newproperty(:mode) do
       desc "Interface switchport mode."
-      newvalues(:access, :trunk)
+      newvalues(:access, :trunk, 'dynamic auto', 'dynamic desirable')
     end
 
     newproperty(:allowed_trunk_vlans) do

data/lib/puppet/type/macauthorization.rb

@@ -1,7 +1,7 @@
 Puppet::Type.newtype(:macauthorization) do
 
   @doc = "Manage the Mac OS X authorization database. See the
-    [Apple developer site](http://developer.apple.com/documentation/Security/Conceptual/Security_Overview/Security_Services/chapter_4_section_5.html)
+    [Apple developer site](https://developer.apple.com/documentation/Security/Conceptual/Security_Overview/Security_Services/chapter_4_section_5.html)
     for more information.
 
     Note that authorization store directives with hyphens in their names have

data/lib/puppet/type/mount.rb

@@ -14,7 +14,10 @@ module Puppet
 
       **Autorequires:** If Puppet is managing any parents of a mount resource ---
       that is, other mount points higher up in the filesystem --- the child
-      mount will autorequire them."
+      mount will autorequire them.
+
+      **Autobefores:**  If Puppet is managing any child file paths of a mount
+      point, the mount resource will autobefore them."
 
     feature :refreshable, "The provider can remount the filesystem.",
       :methods => [:remount]
@@ -164,6 +167,7 @@ module Puppet
 
       validate do |value|
         raise Puppet::Error, "fstype must not contain whitespace: #{value}" if value =~ /\s/
+        raise Puppet::Error, "fstype must not be an empty string" if value.empty?
       end
     end
 
@@ -174,6 +178,7 @@ module Puppet
 
       validate do |value|
         raise Puppet::Error, "options must not contain whitespace: #{value}" if value =~ /\s/
+        raise Puppet::Error, "options must not be an empty string" if value.empty?
       end
     end
 
@@ -291,5 +296,15 @@ module Puppet
       dependencies[0..-2]
     end
 
+    # Autobefore the mount point's child file paths
+    autobefore(:file) do
+      dependencies = []
+      file_resources = catalog.resources.select { |resource| resource.type == :file }
+      children_file_resources = file_resources.select { |resource| File.expand_path(resource[:path]) =~ %r(^#{self[:name]}/.) }
+      children_file_resources.each do |child|
+        dependencies.push Pathname.new(child[:path])
+      end
+      dependencies
+    end
   end
 end

data/lib/puppet/type/notify.rb

@@ -6,7 +6,7 @@ module Puppet
   Type.newtype(:notify) do
     @doc = "Sends an arbitrary message to the agent run-time log."
 
-    newproperty(:message) do
+    newproperty(:message, :idempotent => false) do
       desc "The message to be sent to the log."
       def sync
         case @resource["withpath"]

data/lib/puppet/type/package.rb

@@ -74,6 +74,12 @@ module Puppet
         value. On packaging systems that manage configuration files separately
         from "normal" system files, you can uninstall config files by
         specifying `purged` as the ensure value. This defaults to `installed`.
+
+        Version numbers must match the full version to install, including
+        release if the provider uses a release moniker. Ranges or semver
+        patterns are not accepted except for the `gem` package provider. For
+        example, to install the bash package from the rpm
+        `bash-4.1.2-29.el6.x86_64.rpm`, use the string `'4.1.2-29.el6'`.
       EOT
 
       attr_accessor :latest
@@ -144,7 +150,7 @@ module Puppet
             return true unless [:absent, :purged, :held].include?(is)
           when :latest
             # Short-circuit packages that are not present
-            return false if is == :absent or is == :purged
+            return false if is == :absent || is == :purged
 
             # Don't run 'latest' more than about every 5 minutes
             if @latest and ((Time.now.to_i - @lateststamp) / 60) < 5
@@ -175,7 +181,7 @@ module Puppet
 
 
           when :absent
-            return true if is == :absent or is == :purged
+            return true if is == :absent || is == :purged
           when :purged
             return true if is == :purged
           # this handles version number matches and
@@ -205,6 +211,17 @@ module Puppet
           super(newvalue)
         end
       end
+
+      def change_to_s(currentvalue, newvalue)
+        # Handle transitioning from any previous state to 'purged'
+        return 'purged' if newvalue == :purged
+
+        # Check for transitions from nil/purged/absent to 'created' (any state that is not absent and not purged)
+        return 'created' if (currentvalue.nil? || currentvalue == :absent || currentvalue == :purged) && (newvalue != :absent && newvalue != :purged)
+
+        # The base should handle the normal property transitions
+        super(currentvalue, newvalue)
+      end
     end
 
     newparam(:name) do
@@ -221,8 +238,8 @@ module Puppet
           }
 
           package { 'openssl':
+            ensure => installed,
             name   => $ssl,
-            ensure => installed
           }
 
           . etc. .
@@ -233,9 +250,9 @@ module Puppet
           }
 
           package { 'openssh':
-            name    => $ssh
             ensure  => installed,
-            require => Package['openssl']
+            name    => $ssh,
+            require => Package['openssl'],
           }
 
       "
@@ -259,7 +276,7 @@ module Puppet
     # provider. So far, the logic that determines uniqueness appears to just
     # "Do The Right Thing™" when the provider is explicitly set by the user.
     #
-    # The following resources will be seen as uniqe by puppet:
+    # The following resources will be seen as unique by puppet:
     #
     #     # Uniqueness Key: ['mysql', nil]
     #     package{'mysql': }
@@ -393,8 +410,9 @@ module Puppet
     end
 
     newparam(:configfiles) do
-      desc "Whether configfiles should be kept or replaced.  Most packages
-        types do not support this parameter. Defaults to `keep`."
+      desc "Whether to keep or replace modified config files when installing or
+        upgrading a package. This only affects the `apt` and `dpkg` providers.
+        Defaults to `keep`."
 
       defaultto :keep
 
@@ -445,10 +463,12 @@ module Puppet
         key and value pair are interpreted in a provider specific way.  Each
         option will automatically be quoted when passed to the install command.
 
-        On Windows, this is the **only** place in Puppet where backslash
-        separators should be used.  Note that backslashes in double-quoted
-        strings _must_ be double-escaped and backslashes in single-quoted
-        strings _may_ be double-escaped.
+        With Windows packages, note that file paths in an install option must
+        use backslashes. (Since install options are passed directly to the
+        installation command, forward slashes won't be automatically converted
+        like they are in `file` resources.) Note also that backslashes in
+        double-quoted strings _must_ be escaped and backslashes in single-quoted
+        strings _can_ be escaped.
       EOT
     end
 

data/lib/puppet/type/resources.rb

@@ -4,7 +4,7 @@ require 'puppet/parameter/boolean'
 Puppet::Type.newtype(:resources) do
   @doc = "This is a metatype that can manage other resource types.  Any
     metaparams specified here will be passed on to any generated resources,
-    so you can purge umanaged resources but set `noop` to true so the
+    so you can purge unmanaged resources but set `noop` to true so the
     purging is only logged and does not actually happen."
 
 

data/lib/puppet/type/schedule.rb

@@ -2,7 +2,7 @@ module Puppet
   Type.newtype(:schedule) do
     @doc = <<-'EOT'
       Define schedules for Puppet. Resources can be limited to a schedule by using the
-      [`schedule`](http://docs.puppetlabs.com/references/latest/metaparameter.html#schedule)
+      [`schedule`](https://docs.puppetlabs.com/puppet/latest/reference/metaparameter.html#schedule)
       metaparameter.
 
       Currently, **schedules can only be used to stop a resource from being
@@ -24,7 +24,7 @@ module Puppet
       the hours of two and 4 AM, then you would use this schedule:
 
           schedule { 'maint':
-            range  => "2 - 4",
+            range  => '2 - 4',
             period => daily,
             repeat => 1,
           }
@@ -57,10 +57,10 @@ module Puppet
 
             schedule { 'everyday':
               period => daily,
-              range  => "2 - 4",
+              range  => '2 - 4',
             }
 
-            exec { "/usr/bin/apt-get update":
+            exec { '/usr/bin/apt-get update':
               schedule => 'everyday',
             }
 
@@ -77,7 +77,7 @@ module Puppet
         separator. For instance:
 
             schedule { 'maintenance':
-              range => "1:30 - 4:30",
+              range => '1:30 - 4:30',
             }
 
         This is mostly useful for restricting certain resources to being

data/lib/puppet/type/scheduled_task.rb

@@ -118,7 +118,7 @@ Puppet::Type.newtype(:scheduled_task) do
           * `months` --- Which months the task should run, as an array. Defaults to
             all months. Each month must be an integer between 1 and 12.
           * `on` **(Required)** --- Which days of the month the task should run,
-            as an array. Each day must beeither an integer between 1 and 31,
+            as an array. Each day must be either an integer between 1 and 31,
             or the special value `last,` which is always the last day of the month.
       * For `monthly` (by weekday) triggers:
           * `months` --- Which months the task should run, as an array. Defaults to

data/lib/puppet/type/service.rb

@@ -42,6 +42,9 @@ module Puppet
 
     feature :flaggable, "The provider can pass flags to the service."
 
+    feature :maskable, "The provider can 'mask' the service.",
+      :methods => [:mask]
+
     newproperty(:enable, :required_features => :enableable) do
       desc "Whether a service should be enabled to start at boot.
         This property behaves quite differently depending on the platform;
@@ -60,10 +63,27 @@ module Puppet
         provider.manual_start
       end
 
+      # This only makes sense on systemd systems. Otherwise, it just defaults
+      # to disable.
+      newvalue(:mask, :event => :service_disabled, :required_features => :maskable) do
+        provider.mask
+      end
+
       def retrieve
         provider.enabled?
       end
 
+      # This only makes sense on systemd systems. Static services cannot be enabled
+      # or disabled manually.
+      def insync?(current)
+        if provider.respond_to?(:cached_enabled?) && provider.cached_enabled? == 'static'
+          Puppet.debug("Unable to enable or disable static service #{@resource[:name]}")
+          return true
+        end
+
+        super(current)
+      end
+
       validate do |value|
         if value == :manual and !Puppet.features.microsoft_windows?
           raise Puppet::Error.new("Setting enable to manual is only supported on Microsoft Windows.")
@@ -230,5 +250,9 @@ module Puppet
         debug "Skipping restart; service is not running"
       end
     end
+
+    def self.needs_ensure_retrieved
+      false
+    end
   end
 end

data/lib/puppet/type/ssh_authorized_key.rb

@@ -2,18 +2,20 @@ module Puppet
   Type.newtype(:ssh_authorized_key) do
     @doc = "Manages SSH authorized keys. Currently only type 2 keys are supported.
 
-      In their native habitat, SSH keys usually appear as a single long line. This
-      resource type requires you to split that line into several attributes. Thus, a
-      key that appears in your `~/.ssh/id_rsa.pub` file like this...
+      In their native habitat, SSH keys usually appear as a single long line, in
+      the format `<TYPE> <KEY> <NAME/COMMENT>`. This resource type requires you
+      to split that line into several attributes. Thus, a key that appears in
+      your `~/.ssh/id_rsa.pub` file like this...
 
-          ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAy5mtOAMHwA2ZAIfW6Ap70r+I4EclYHEec5xIN59ROUjss23Skb1OtjzYpVPaPH8mSdSmsN0JHaBLiRcu7stl4O8D8zA4mz/vw32yyQ/Kqaxw8l0K76k6t2hKOGqLTY4aFbFISV6GDh7MYLn8KU7cGp96J+caO5R5TqtsStytsUhSyqH+iIDh4e4+BrwTc6V4Y0hgFxaZV5d18mLA4EPYKeG5+zyBCVu+jueYwFqM55E0tHbfiaIN9IzdLV+7NEEfdLkp6w2baLKPqWUBmuvPF1Mn3FwaFLjVsMT3GQeMue6b3FtUdTDeyAYoTxrsRo/WnDkS6Pa3YhrFwjtUqXfdaQ== nick@magpie.puppetlabs.lan
+          ssh-rsa AAAAB3Nza[...]qXfdaQ== nick@magpie.example.com
 
       ...would translate to the following resource:
 
-          ssh_authorized_key { 'nick@magpie.puppetlabs.lan':
-            user => 'nick',
-            type => 'ssh-rsa',
-            key  => 'AAAAB3NzaC1yc2EAAAABIwAAAQEAy5mtOAMHwA2ZAIfW6Ap70r+I4EclYHEec5xIN59ROUjss23Skb1OtjzYpVPaPH8mSdSmsN0JHaBLiRcu7stl4O8D8zA4mz/vw32yyQ/Kqaxw8l0K76k6t2hKOGqLTY4aFbFISV6GDh7MYLn8KU7cGp96J+caO5R5TqtsStytsUhSyqH+iIDh4e4+BrwTc6V4Y0hgFxaZV5d18mLA4EPYKeG5+zyBCVu+jueYwFqM55E0tHbfiaIN9IzdLV+7NEEfdLkp6w2baLKPqWUBmuvPF1Mn3FwaFLjVsMT3GQeMue6b3FtUdTDeyAYoTxrsRo/WnDkS6Pa3YhrFwjtUqXfdaQ==',
+          ssh_authorized_key { 'nick@magpie.example.com':
+            ensure => present,
+            user   => 'nick',
+            type   => 'ssh-rsa',
+            key    => 'AAAAB3Nza[...]qXfdaQ==',
           }
 
       To ensure that only the currently approved keys are present, you can purge
@@ -36,8 +38,12 @@ module Puppet
     ensurable
 
     newparam(:name) do
-      desc "The SSH key comment. This attribute is currently used as a
-        system-wide primary key and therefore has to be unique."
+      desc "The SSH key comment. This can be anything, and doesn't need to match
+        the original comment from the `.pub` file.
+
+        Due to internal limitations, this must be unique across all user accounts;
+        if you want to specify one key for multiple users, you must use a different
+        comment for each instance."
 
       isnamevar
 
@@ -145,7 +151,7 @@ module Puppet
     end
 
     # regular expression suitable for use by a ParsedFile based provider
-    REGEX = /^(?:(.+) )?(ssh-dss|ssh-ed25519|ssh-rsa|ecdsa-sha2-nistp256|ecdsa-sha2-nistp384|ecdsa-sha2-nistp521) ([^ ]+) ?(.*)$/
+    REGEX = /^(?:(.+)\s+)?(ssh-dss|ssh-ed25519|ssh-rsa|ecdsa-sha2-nistp256|ecdsa-sha2-nistp384|ecdsa-sha2-nistp521)\s+([^ ]+)\s*(.*)$/
     def self.keyline_regex
       REGEX
     end

data/lib/puppet/type/sshkey.rb

@@ -1,8 +1,10 @@
 module Puppet
   Type.newtype(:sshkey) do
-    @doc = "Installs and manages ssh host keys.  At this point, this type
-      only knows how to install keys into `/etc/ssh/ssh_known_hosts`.  See
-      the `ssh_authorized_key` type to manage authorized keys."
+    @doc = "Installs and manages ssh host keys.  By default, this type will
+      install keys into `/etc/ssh/ssh_known_hosts`. To manage ssh keys in a
+      different `known_hosts` file, such as a user's personal `known_hosts`,
+      pass its path to the `target` parameter. See the `ssh_authorized_key`
+      type to manage authorized keys."
 
     ensurable
 

data/lib/puppet/type/stage.rb

@@ -2,7 +2,7 @@ Puppet::Type.newtype(:stage) do
   desc "A resource type for creating new run stages.  Once a stage is available,
     classes can be assigned to it by declaring them with the resource-like syntax
     and using
-    [the `stage` metaparameter](http://docs.puppetlabs.com/references/latest/metaparameter.html#stage).
+    [the `stage` metaparameter](https://docs.puppetlabs.com/puppet/latest/reference/metaparameter.html#stage).
 
     Note that new stages are not useful unless you also declare their order
     in relation to the default `main` stage.

data/lib/puppet/type/tidy.rb

@@ -16,6 +16,9 @@ Puppet::Type.newtype(:tidy) do
     actual deletion.
     "
 
+  # Tidy names are not isomorphic with the objects.
+  @isomorphic = false
+
   newparam(:path) do
     desc "The path to the file or directory to manage.  Must be fully
       qualified."
@@ -56,10 +59,10 @@ Puppet::Type.newtype(:tidy) do
 
       Example:
 
-          tidy { "/tmp":
-            age     => "1w",
+          tidy { '/tmp':
+            age     => '1w',
             recurse => 1,
-            matches => [ "[0-9]pub*.tmp", "*.temp", "tmpfile?" ]
+            matches => [ '[0-9]pub*.tmp', '*.temp', 'tmpfile?' ],
           }
 
       This removes files from `/tmp` if they are one week old or older,
@@ -73,7 +76,7 @@ Puppet::Type.newtype(:tidy) do
       Finally, note that you must now specify a non-zero/non-false value
       for recurse if matches is used, as matches only apply to files found
       by recursion (there's no reason to use static patterns match against
-      a statically determined path).  Requiering explicit recursion clears
+      a statically determined path).  Requiring explicit recursion clears
       up a common source of confusion.
     EOT
 

data/lib/puppet/type/user.rb

@@ -16,9 +16,10 @@ module Puppet
       about them.  It does not directly modify `/etc/passwd` or anything.
 
       **Autorequires:** If Puppet is managing the user's primary group (as
-      provided in the `gid` attribute), the user resource will autorequire
-      that group. If Puppet is managing any role accounts corresponding to the
-      user's roles, the user resource will autorequire those role accounts."
+      provided in the `gid` attribute) or any group listed in the `groups`
+      attribute then the user resource will autorequire that group. If Puppet
+      is managing any role accounts corresponding to the user's roles, the
+      user resource will autorequire those role accounts."
 
     feature :allows_duplicates,
       "The provider supports duplicate users with the same UID."
@@ -170,8 +171,23 @@ module Puppet
 
     newproperty(:comment) do
       desc "A description of the user.  Generally the user's full name."
-      munge do |v|
-        v.respond_to?(:force_encoding) ? v.force_encoding(Encoding::ASCII_8BIT) : v
+      def insync?(is)
+        # nameservice provider requires special attention to encoding
+        # Overrides Puppet::Property#insync?
+        if !@should.empty? && provider.respond_to?(:comments_insync?)
+          return provider.comments_insync?(is, @should)
+        end
+        super(is)
+      end
+
+      # In the case that our comments have incompatible encodings, set external
+      # encoding to support concatenation for display.
+      # overrides Puppet::Property#change_to_s
+      def change_to_s(currentvalue, newvalue)
+        if newvalue.respond_to?(:force_encoding) && !Encoding.compatible?(currentvalue, newvalue)
+          return super(currentvalue, newvalue.dup.force_encoding(currentvalue.encoding))
+        end
+        super(currentvalue, newvalue)
       end
     end
 
@@ -183,25 +199,26 @@ module Puppet
     end
 
     newproperty(:password, :required_features => :manages_passwords) do
-      desc %q{The user's password, in whatever encrypted format the local
-        system requires.
-
-        * Most modern Unix-like systems use salted SHA1 password hashes. You can use
-          Puppet's built-in `sha1` function to generate a hash from a password.
-        * Mac OS X 10.5 and 10.6 also use salted SHA1 hashes.
-        * Mac OS X 10.7 (Lion) uses salted SHA512 hashes. The Puppet Labs [stdlib][]
-          module contains a `str2saltedsha512` function which can generate password
-          hashes for Lion.
-        * Mac OS X 10.8 and higher use salted SHA512 PBKDF2 hashes. When
-          managing passwords on these systems the salt and iterations properties
-          need to be specified as well as the password.
+      desc %q{The user's password, in whatever encrypted format the local system
+        requires. Consult your operating system's documentation for acceptable password
+        encryption formats and requirements.
+
+        * Mac OS X 10.5 and 10.6, and some older Linux distributions, use salted SHA1
+          hashes. You can use Puppet's built-in `sha1` function to generate a salted SHA1
+          hash from a password.
+        * Mac OS X 10.7 (Lion), and many recent Linux distributions, use salted SHA512
+          hashes. The Puppet Labs [stdlib][] module contains a `str2saltedsha512` function
+          which can generate password hashes for these operating systems.
+        * OS X 10.8 and higher use salted SHA512 PBKDF2 hashes. When managing passwords
+          on these systems, the `salt` and `iterations` attributes need to be specified as
+          well as the password.
         * Windows passwords can only be managed in cleartext, as there is no Windows API
           for setting the password hash.
 
         [stdlib]: https://github.com/puppetlabs/puppetlabs-stdlib/
 
-        Be sure to enclose any value that includes a dollar sign ($) in single
-        quotes (') to avoid accidental variable interpolation.}
+        Enclose any value that includes a dollar sign ($) in single quotes (') to avoid
+        accidental variable interpolation.}
 
       validate do |value|
         raise ArgumentError, "Passwords cannot include ':'" if value.is_a?(String) and value.include?(":")
@@ -320,9 +337,14 @@ module Puppet
     end
 
     newparam(:membership) do
-      desc "Whether specified groups should be considered the **complete list**
-        (`inclusive`) or the **minimum list** (`minimum`) of groups to which
-        the user belongs. Defaults to `minimum`."
+      desc "If `minimum` is specified, Puppet will ensure that the user is a
+        member of all specified groups, but will not remove any other groups
+        that the user is a part of.
+
+        If `inclusive` is specified, Puppet will ensure that the user is a
+        member of **only** specified groups.
+
+        Defaults to `minimum`."
 
       newvalues(:inclusive, :minimum)
 
@@ -582,14 +604,15 @@ module Puppet
     end
 
     newproperty(:salt, :required_features => :manages_password_salt) do
-      desc "This is the 32 byte salt used to generate the PBKDF2 password used in
+      desc "This is the 32-byte salt used to generate the PBKDF2 password used in
             OS X. This field is required for managing passwords on OS X >= 10.8."
     end
 
     newproperty(:iterations, :required_features => :manages_password_salt) do
       desc "This is the number of iterations of a chained computation of the
-            password hash (http://en.wikipedia.org/wiki/PBKDF2).  This parameter
-            is used in OS X. This field is required for managing passwords on OS X >= 10.8."
+            [PBKDF2 password hash](https://en.wikipedia.org/wiki/PBKDF2). This parameter
+            is used in OS X, and is required for managing passwords on OS X 10.8 and
+            newer."
 
       munge do |value|
         if value.is_a?(String) and value =~/^[-0-9]+$/
@@ -716,7 +739,9 @@ module Puppet
     def unknown_keys_in_file(keyfile)
       names = []
       name_index = 0
-      File.new(keyfile).each do |line|
+      # RFC 4716 specifies UTF-8 allowed in public key files per https://www.ietf.org/rfc/rfc4716.txt
+      # the authorized_keys file may contain UTF-8 comments
+      Puppet::FileSystem.open(keyfile, nil, 'r:UTF-8').each do |line|
         next unless line =~ Puppet::Type.type(:ssh_authorized_key).keyline_regex
         # the name is stored in the 4th capture of the regex
         name = $4