puppet 5.3.4 → 6.29.0

data/lib/puppet/type/package.rb

@@ -1,3 +1,4 @@
+# coding: utf-8
 # Define the different packaging systems.  Each package system is implemented
 # in a module, which then gets used to individually extend each package object.
 # This allows packages to exist on the same machine using different packaging
@@ -9,8 +10,8 @@ require 'puppet/parameter/boolean'
 module Puppet
   Type.newtype(:package) do
     @doc = "Manage packages.  There is a basic dichotomy in package
-      support right now:  Some package types (e.g., yum and apt) can
-      retrieve their own package files, while others (e.g., rpm and sun)
+      support right now:  Some package types (such as yum and apt) can
+      retrieve their own package files, while others (such as rpm and sun)
       cannot.  For those package formats that cannot retrieve their own files,
       you can use the `source` parameter to point to the correct file.
 
@@ -20,8 +21,8 @@ module Puppet
       requires in order to function, and you must meet those requirements
       to use a given provider.
 
-      You can declare multiple package resources with the same `name`, as long
-      as they specify different providers and have unique titles.
+      You can declare multiple package resources with the same `name` as long
+      as they have unique titles, and specify different providers and commands.
 
       Note that you must use the _title_ to make a reference to a package
       resource; `Package[<NAME>]` is not a synonym for `Package[<TITLE>]` like
@@ -50,22 +51,29 @@ module Puppet
         package database for installed version(s), and can select
         which out of a set of available versions of a package to
         install if asked."
+    feature :version_ranges, "The provider can ensure version ranges."
     feature :holdable, "The provider is capable of placing packages on hold
         such that they are not automatically upgraded as a result of
         other package dependencies unless explicit action is taken by
-        a user or another package. Held is considered a superset of
-        installed.",
-      :methods => [:hold]
+        a user or another package.",
+      :methods => [:hold, :unhold]
+    feature :install_only, "The provider accepts options to only install packages never update (kernels, etc.)"
     feature :install_options, "The provider accepts options to be
       passed to the installer command."
     feature :uninstall_options, "The provider accepts options to be
       passed to the uninstaller command."
+    feature :disableable, "The provider can disable packages. This feature is used by specifying `disabled` as the
+      desired value for the package.",
+      :methods => [:disable]
+    feature :supports_flavors, "The provider accepts flavors, which are specific variants of packages."
     feature :package_settings, "The provider accepts package_settings to be
       ensured for the given package. The meaning and format of these settings is
       provider-specific.",
       :methods => [:package_settings_insync?, :package_settings, :package_settings=]
     feature :virtual_packages, "The provider accepts virtual package names for install and uninstall."
 
+    feature :targetable, "The provider accepts a targeted package management command."
+
     ensurable do
       desc <<-EOT
         What state the package should be in. On packaging systems that can
@@ -76,10 +84,12 @@ module Puppet
         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
+        release if the provider uses a release moniker. 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'`.
+
+        On supported providers, version ranges can also be ensured. For example,
+        inequalities: `<2.0.0`, or intersections: `>1.0.0 <2.0.0`.
       EOT
 
       attr_accessor :latest
@@ -97,7 +107,11 @@ module Puppet
       end
 
       newvalue(:held, :event => :package_held, :required_features => :holdable) do
-        provider.hold
+        provider.deprecated_hold
+      end
+
+      newvalue(:disabled, :required_features => :disableable) do
+        provider.disable
       end
 
       # Alias the 'present' value.
@@ -147,7 +161,7 @@ module Puppet
         @should.each { |should|
           case should
           when :present
-            return true unless [:absent, :purged, :held].include?(is)
+            return true unless [:absent, :purged, :held, :disabled].include?(is)
           when :latest
             # Short-circuit packages that are not present
             return false if is == :absent || is == :purged
@@ -172,7 +186,7 @@ module Puppet
               when is == @latest
                 return true
               when is == :present
-                # This will only happen on retarded packaging systems
+                # This will only happen on packaging systems
                 # that can't query versions.
                 return true
               else
@@ -242,7 +256,7 @@ module Puppet
             name   => $ssl,
           }
 
-          . etc. .
+          ...
 
           $ssh = $operatingsystem ? {
             solaris => SMCossh,
@@ -271,20 +285,59 @@ module Puppet
     providify
     paramclass(:provider).isnamevar
 
-    # We have more than one namevar, so we need title_patterns. However, we
-    # cheat and set the patterns to map to name only and completely ignore
-    # provider. So far, the logic that determines uniqueness appears to just
-    # "Do The Right Thing™" when the provider is explicitly set by the user.
+    def self.parameters_to_include
+      [:provider]
+    end
+
+    # Specify a targeted package management command.
+    newparam(:command, :required_features => :targetable) do
+      desc <<-EOT
+        The targeted command to use when managing a package:
+
+          package { 'mysql':
+            provider => gem,
+          }
+
+          package { 'mysql-opt':
+            name     => 'mysql',
+            provider => gem,
+            command  => '/opt/ruby/bin/gem',
+          }
+
+        Each provider defines a package management command; and uses the first
+        instance of the command found in the PATH.
+
+        Providers supporting the targetable feature allow you to specify the
+        absolute path of the package management command; useful when multiple
+        instances of the command are installed, or the command is not in the PATH.
+      EOT
+
+      isnamevar
+      defaultto :default
+    end
+
+    # We have more than one namevar, so we need title_patterns.
+    # However, we cheat and set the patterns to map to name only
+    # and completely ignore provider (and command, for targetable providers).
+    # So far, the logic that determines uniqueness appears to just
+    # "Do The Right Thing™" when provider (and command) are explicitly set.
     #
     # The following resources will be seen as unique by puppet:
     #
     #     # Uniqueness Key: ['mysql', nil]
-    #     package{'mysql': }
+    #     package {'mysql': }
     #
-    #     # Uniqueness Key: ['mysql', 'gem']
-    #     package{'gem-mysql':
+    #     # Uniqueness Key: ['mysql', 'gem', nil]
+    #     package {'gem-mysql':
+    #       name     => 'mysql,
+    #       provider => gem,
+    #     }
+    #
+    #     # Uniqueness Key: ['mysql', 'gem', '/opt/ruby/bin/gem']
+    #     package {'gem-mysql-opt':
     #       name     => 'mysql,
     #       provider => gem
+    #       command  => '/opt/ruby/bin/gem',
     #     }
     #
     # This does not handle the case where providers like 'yum' and 'rpm' should
@@ -362,11 +415,21 @@ module Puppet
       end
     end
 
+    newproperty(:flavor, :required_features => :supports_flavors) do
+      desc "OpenBSD and DNF modules support 'flavors', which are
+        further specifications for which type of package you want."
+      validate do |value|
+        if [:disabled, "disabled"].include?(@resource[:ensure]) && value
+          raise ArgumentError, _('Cannot have both `ensure => disabled` and `flavor`')
+        end
+      end
+    end
+
     newparam(:source) do
-      desc "Where to find the package file. This is only used by providers that don't
+      desc "Where to find the package file. This is mostly used by providers that don't
         automatically download packages from a central repository. (For example:
-        the `yum` and `apt` providers ignore this attribute, but the `rpm` and
-        `dpkg` providers require it.)
+        the `yum` provider ignores this attribute, `apt` provider uses it if present
+        and the `rpm` and `dpkg` providers require it.)
 
         Different providers accept different values for `source`. Most providers
         accept paths to local files stored on the target system. Some providers
@@ -411,8 +474,7 @@ module Puppet
 
     newparam(:configfiles) do
       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`."
+        upgrading a package. This only affects the `apt` and `dpkg` providers."
 
       defaultto :keep
 
@@ -442,9 +504,35 @@ module Puppet
       newvalues(:true, :false)
     end
 
-    newparam(:flavor) do
-      desc "OpenBSD supports 'flavors', which are further specifications for
-        which type of package you want."
+    newparam(:enable_only, :boolean => false, :parent => Puppet::Parameter::Boolean) do
+      desc <<-EOT
+        Tells `dnf module` to only enable a specific module, instead
+        of installing its default profile.
+
+        Modules with no default profile will be enabled automatically
+        without the use of this parameter.
+
+        Conflicts with the `flavor` property, which selects a profile
+        to install.
+      EOT
+      defaultto false
+
+      validate do |value|
+        if [true, :true, "true"].include?(value) && @resource[:flavor]
+          raise ArgumentError, _('Cannot have both `enable_only => true` and `flavor`')
+        end
+        if [:disabled, "disabled"].include?(@resource[:ensure])
+          raise ArgumentError, _('Cannot have both `ensure => disabled` and `enable_only => true`')
+        end
+      end
+    end
+
+    newparam(:install_only, :boolean => false, :parent => Puppet::Parameter::Boolean, :required_features => :install_only) do
+      desc <<-EOT
+        It should be set for packages that should only ever be installed,
+        never updated. Kernels in particular fall into this category.
+      EOT
+      defaultto false
     end
 
     newparam(:install_options, :parent => Puppet::Parameter::PackageOptions, :required_features => :install_options) do
@@ -498,18 +586,27 @@ module Puppet
     newparam(:allow_virtual, :boolean => true, :parent => Puppet::Parameter::Boolean, :required_features => :virtual_packages) do
       desc 'Specifies if virtual package names are allowed for install and uninstall.'
 
-      defaultto true
+      defaultto do
+        provider_class = provider.class
+        if provider_class.respond_to?(:defaultto_allow_virtual)
+          provider_class.defaultto_allow_virtual
+        else
+          true
+        end
+      end
     end
 
     autorequire(:file) do
       autos = []
       [:responsefile, :adminfile].each { |param|
-        if val = self[param]
+        val = self[param]
+        if val
           autos << val
         end
       }
 
-      if source = self[:source] and absolute_path?(source)
+      source = self[:source]
+      if source && absolute_path?(source)
         autos << source
       end
       autos
@@ -517,7 +614,8 @@ module Puppet
 
     # This only exists for testing.
     def clear
-      if obj = @parameters[:ensure]
+      obj = @parameters[:ensure]
+      if obj
         obj.latest = nil
       end
     end
@@ -547,9 +645,7 @@ module Puppet
 
         If you use this, be careful of notifying classes when you want to restart
         services. If the class also contains a refreshable package, doing so could
-        cause unnecessary re-installs.
-
-        Defaults to `false`."
+        cause unnecessary re-installs."
       newvalues(:true, :false)
 
       defaultto :false
@@ -567,5 +663,59 @@ module Puppet
         provider.reinstall
       end
     end
+
+    newproperty(:mark, :required_features => :holdable) do
+      mark_doc='Valid values are: hold/none'
+      desc <<-EOT
+        Set to hold to tell Debian apt/Solaris pkg to hold the package version
+
+        #{mark_doc}
+        Default is "none". Mark can be specified with or without `ensure`,
+        if `ensure` is missing will default to "present".
+
+        Mark cannot be specified together with "purged", "absent" or "held"
+        values for `ensure`.
+      EOT
+      newvalues(:hold, :none)
+      munge do |value|
+        case value
+        when "hold", :hold
+          :hold
+        when "none", :none
+          :none
+        else
+          raise ArgumentError, _('Invalid hold value %{value}. %{doc}') % { value: value.inspect, doc: mark_doc}
+        end
+      end
+
+      def insync?(is)
+        @should[0] == is
+      end
+
+      def should
+        @should[0] if @should && @should.is_a?(Array) && @should.size == 1
+      end
+
+      def retrieve
+        provider.properties[:mark]
+      end
+
+      def sync
+        if @should[0] == :hold
+          provider.hold
+        else
+          provider.unhold
+        end
+      end
+    end
+
+    validate do
+      if :held == @parameters[:ensure].should
+        warning '"ensure=>held" has been deprecated and will be removed in a future version, use "mark=hold" instead'
+      end
+      if @parameters[:mark] && [:absent, :purged, :held].include?(@parameters[:ensure].should)
+        raise ArgumentError, _('You cannot use "mark" property while "ensure" is one of ["absent", "purged", "held"]')
+      end
+    end
   end
 end

data/lib/puppet/type/resources.rb

@@ -87,6 +87,12 @@ Puppet::Type.newtype(:resources) do
     end
   end
 
+  WINDOWS_SYSTEM_SID_REGEXES =
+      # Administrator, Guest, Domain Admins, Schema Admins, Enterprise Admins.
+      # https://support.microsoft.com/en-us/help/243330/well-known-security-identifiers-in-windows-operating-systems
+      [/S-1-5-21.+-500/, /S-1-5-21.+-501/, /S-1-5-21.+-512/, /S-1-5-21.+-518/,
+       /S-1-5-21.+-519/]
+
   def check(resource)
     @checkmethod ||= "#{self[:name]}_check"
     @hascheck ||= respond_to?(@checkmethod)
@@ -126,7 +132,8 @@ Puppet::Type.newtype(:resources) do
 
   def resource_type
     unless defined?(@resource_type)
-      unless type = Puppet::Type.type(self[:name])
+      type = Puppet::Type.type(self[:name])
+      unless type
         raise Puppet::DevError, _("Could not find resource type")
       end
       @resource_type = type
@@ -145,8 +152,12 @@ Puppet::Type.newtype(:resources) do
 
     return false if system_users.include?(resource[:name])
     return false if unless_uids && unless_uids.include?(current_uid)
-
-    current_uid > self[:unless_system_user]
+    if current_uid.is_a?(String)
+      # Windows user; is a system user if any regex matches.
+      WINDOWS_SYSTEM_SID_REGEXES.none? { |regex| current_uid =~ regex }
+    else
+      current_uid > self[:unless_system_user]
+    end
   end
 
   def system_users
@@ -164,7 +175,7 @@ Puppet::Type.newtype(:resources) do
     end
 
     # Otherwise, use a sensible default based on the OS family
-    @system_users_max_uid ||= case Facter.value(:osfamily)
+    @system_users_max_uid ||= case Puppet.runtime[:facter].value(:osfamily)
       when 'OpenBSD', 'FreeBSD'
         999
       else

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`](https://docs.puppetlabs.com/puppet/latest/reference/metaparameter.html#schedule)
+      [`schedule`](https://puppet.com/docs/puppet/latest/metaparameter.html#schedule)
       metaparameter.
 
       Currently, **schedules can only be used to stop a resource from being
@@ -18,8 +18,8 @@ module Puppet
       time within that schedule, then the resources will get applied;
       otherwise, that work may never get done.
 
-      Thus, it is advisable to use wider scheduling (e.g., over a couple of
-      hours) combined with periods and repetitions.  For instance, if you
+      Thus, it is advisable to use wider scheduling (for example, over a couple
+      of hours) combined with periods and repetitions.  For instance, if you
       wanted to restrict certain resources to only running once, between
       the hours of two and 4 AM, then you would use this schedule:
 
@@ -36,7 +36,7 @@ module Puppet
       because they will be outside the scheduled range.
 
       Puppet automatically creates a schedule for each of the valid periods
-      with the same name as that period (e.g., hourly and daily).
+      with the same name as that period (such as hourly and daily).
       Additionally, a schedule named `puppet` is created and used as the
       default, with the following attributes:
 
@@ -46,6 +46,13 @@ module Puppet
           }
 
       This will cause resources to be applied every 30 minutes by default.
+
+      The `statettl` setting on the agent affects the ability of a schedule to
+      determine if a resource has already been checked. If the `statettl` is
+      set lower than the span of the associated schedule resource, then a
+      resource could be checked & applied multiple times in the schedule as
+      the information about when the resource was last checked will have
+      expired from the cache.
       EOT
 
     apply_to_all
@@ -83,7 +90,7 @@ module Puppet
         This is mostly useful for restricting certain resources to being
         applied in maintenance windows or during off-peak hours. Multiple
         ranges can be applied in array context. As a convenience when specifying
-        ranges, you may cross midnight (e.g.: range => "22:00 - 04:00").
+        ranges, you can cross midnight (for example, `range => "22:00 - 04:00"`).
       EOT
 
       # This is lame; properties all use arrays as values, but parameters don't.
@@ -112,6 +119,11 @@ module Puppet
 
           self.fail _("Invalid range %{value}") % { value: value } if range.length != 2
 
+          # Fill out 0s for unspecified minutes and seconds
+          range.each do |time_array|
+            (3 - time_array.length).times { |_| time_array << 0 }
+          end
+
           # Make sure the hours are valid
           [range[0][0], range[1][0]].each do |n|
             raise ArgumentError, _("Invalid hour '%{n}'") % { n: n } if n < 0 or n > 23
@@ -127,107 +139,51 @@ module Puppet
         ret
       end
 
+      def weekday_match?(day)
+        if @resource[:weekday]
+          @resource[:weekday].has_key?(day)
+        else
+          true
+        end
+      end
+
       def match?(previous, now)
         # The lowest-level array is of the hour, minute, second triad
         # then it's an array of two of those, to present the limits
         # then it's an array of those ranges
         @value = [@value] unless @value[0][0].is_a?(Array)
+        @value.any? do |range|
+          limit_start = Time.local(now.year, now.month, now.day, *range[0])
+          limit_end = Time.local(now.year, now.month, now.day, *range[1])
 
-        @value.each do |value|
-          limits = value.collect do |range|
-            ary = [now.year, now.month, now.day, range[0]]
-            if range[1]
-              ary << range[1]
-            else
-              ary << 0
-            end
-
-            if range[2]
-              ary << range[2]
+          if limit_start < limit_end
+            # The whole range is in one day, simple case
+            now.between?(limit_start, limit_end) && weekday_match?(now.wday)
+          else
+            # The range spans days. We have to test against a range starting
+            # today, and a range that started yesterday.
+            today = Date.new(now.year, now.month, now.day)
+            tomorrow = today.next_day
+            yesterday = today.prev_day
+
+            # First check a range starting today
+            if now.between?(limit_start, Time.local(tomorrow.year, tomorrow.month, tomorrow.day, *range[1]))
+              weekday_match?(today.wday)
             else
-              ary << 0
-            end
-
-            time = Time.local(*ary)
-
-            unless time.hour == range[0]
-              self.devfail(
-                _("Incorrectly converted time: %{time}: %{hour} vs %{value}") % { time: time, hour: time.hour, value: range[0] }
-              )
+              # Then check a range starting yesterday
+              now.between?(Time.local(yesterday.year, yesterday.month, yesterday.day, *range[0]),
+                           limit_end) &&
+                weekday_match?(yesterday.wday)
             end
-
-            time
-          end
-
-          unless limits[0] < limits[1]
-            self.info(
-            _("Assuming upper limit should be that time the next day")
-            )
-
-            # Find midnight between the two days. Adding one second
-            # to the end of the day is easier than dealing with dates.
-            ary = limits[0].to_a
-            ary[0] = 59
-            ary[1] = 59
-            ary[2] = 23
-            midnight = Time.local(*ary)+1
-
-            # If it is currently between the range start and midnight
-            # we consider that a successful match.
-            if now.between?(limits[0], midnight)
-              # We have to check the weekday match here as it is special-cased
-              # to support day-spanning ranges.
-              if @resource[:weekday]
-                return false unless @resource[:weekday].has_key?(now.wday)
-              end
-              return true
-            end
-
-            # If we didn't match between the starting time and midnight
-            # we must now move our midnight back 24 hours and try
-            # between the new midnight (24 hours prior) and the
-            # ending time.
-            midnight -= 86400
-
-            # Now we compare the current time between midnight and the
-            # end time.
-            if now.between?(midnight, limits[1])
-              # This case is the reason weekday matching is special cased
-              # in the range parameter. If we match a range that has spanned
-              # past midnight we want to match against the weekday when the range
-              # started, not when it currently is.
-              if @resource[:weekday]
-                return false unless @resource[:weekday].has_key?((now - 86400).wday)
-              end
-              return true
-            end
-
-            # If neither of the above matched then we don't match the
-            # range schedule.
-            return false
-          end
-
-          # Check to see if a weekday parameter was specified and, if so,
-          # do we match it or not. If we fail we can stop here.
-          # This is required because spanning ranges forces us to check
-          # weekday within the range parameter.
-          if @resource[:weekday]
-            return false unless @resource[:weekday].has_key?(now.wday)
           end
-
-          return true if now.between?(*limits)
         end
-
-        # Else, return false, since our current time isn't between
-        # any valid times
-        false
       end
     end
 
     newparam(:periodmatch) do
-      desc "Whether periods should be matched by number (e.g., the two times
-        are in the same hour) or by distance (e.g., the two times are
-        60 minutes apart)."
+      desc "Whether periods should be matched by a numeric value (for instance,
+        whether two times are in the same hour) or by their chronological
+        distance apart (whether two times are 60 minutes apart)."
 
       newvalues(:number, :distance)
 
@@ -241,8 +197,8 @@ module Puppet
 
         Note that the period defines how often a given resource will get
         applied but not when; if you would like to restrict the hours
-        that a given resource can be applied (e.g., only at night during
-        a maintenance window), then use the `range` attribute.
+        that a given resource can be applied (for instance, only at night
+        during a maintenance window), then use the `range` attribute.
 
         If the provided periods are not sufficient, you can provide a
         value to the *repeat* attribute, which will cause Puppet to
@@ -258,12 +214,16 @@ module Puppet
 
         At the moment, Puppet cannot guarantee that level of repetition; that
         is, the resource can applied _up to_ every 10 minutes, but internal
-        factors might prevent it from actually running that often (e.g. if a
-        Puppet run is still in progress when the next run is scheduled to start,
-        that next run will be suppressed).
+        factors might prevent it from actually running that often (for instance,
+        if a Puppet run is still in progress when the next run is scheduled to
+        start, that next run will be suppressed).
 
         See the `periodmatch` attribute for tuning whether to match
         times by their distance apart or by their specific value.
+        
+        > **Tip**: You can use `period => never,` to prevent a resource from being applied
+        in the given `range`. This is useful if you need to create a blackout window to
+        perform sensitive operations without interruption.
       EOT
 
       newvalues(:hourly, :daily, :weekly, :monthly, :never)
@@ -312,7 +272,7 @@ module Puppet
 
     newparam(:repeat) do
       desc "How often a given resource may be applied in this schedule's `period`.
-        Defaults to 1; must be an integer."
+        Must be an integer."
 
       defaultto 1
 
@@ -378,7 +338,7 @@ module Puppet
       end
 
       def weekday_integer?(value)
-        value.is_a?(Integer) && (0..6).include?(value)
+        value.is_a?(Integer) && (0..6).cover?(value)
       end
 
       def weekday_string?(value)