chef 16.0.275 → 16.2.50

data/lib/chef/resource/windows_auto_run.rb

@@ -25,6 +25,17 @@ class Chef
 
       description "Use the **windows_auto_run** resource to set applications to run at login."
       introduced "14.0"
+      examples <<~DOC
+      **Run BGInfo at login**
+
+      ```ruby
+      windows_auto_run 'BGINFO' do
+        program 'C:/Sysinternals/bginfo.exe'
+        args    '\'C:/Sysinternals/Config.bgi\' /NOLICPROMPT /TIMER:0'
+        action  :create
+      end
+      ```
+      DOC
 
       property :program_name, String,
         description: "The name of the program to run at login if it differs from the resource block's name.",

data/lib/chef/resource/windows_certificate.rb

@@ -30,6 +30,32 @@ class Chef
 
       description "Use the **windows_certificate** resource to install a certificate into the Windows certificate store from a file. The resource grants read-only access to the private key for designated accounts. Due to current limitations in WinRM, installing certificates remotely may not work if the operation requires a user profile. Operations on the local machine store should still work."
       introduced "14.7"
+      examples <<~DOC
+      **Add PFX cert to local machine personal store and grant accounts read-only access to private key**
+
+      ```ruby
+      windows_certificate 'c:/test/mycert.pfx' do
+        pfx_password 'password'
+        private_key_acl ["acme\\fred", "pc\\jane"]
+      end
+      ```
+
+      **Add cert to trusted intermediate store**
+
+      ```ruby
+      windows_certificate 'c:/test/mycert.cer' do
+        store_name 'CA'
+      end
+      ```
+
+      **Remove all certificates matching the subject**
+
+      ```ruby
+      windows_certificate 'me.acme.com' do
+        action :delete
+      end
+      ```
+      DOC
 
       property :source, String,
         description: "The source file (for create and acl_add), thumbprint (for delete and acl_add) or subject (for delete) if it differs from the resource block's name.",
@@ -308,7 +334,7 @@ class Chef
         #
         def import_certificates(cert_objs, is_pfx)
           [cert_objs].flatten.each do |cert_obj|
-            thumbprint = OpenSSL::Digest::SHA1.new(cert_obj.to_der).to_s # Fetch its thumbprint
+            thumbprint = OpenSSL::Digest.new("SHA1", cert_obj.to_der).to_s # Fetch its thumbprint
             # Need to check if return value is Boolean:true
             # If not then the given certificate should be added in certstore
             if verify_cert(thumbprint) == true

data/lib/chef/resource/windows_dfs_server.rb

@@ -50,7 +50,7 @@ class Chef
         ps_results = powershell_out("Get-DfsnServerConfiguration -ComputerName '#{ENV["COMPUTERNAME"]}' | Select LdapTimeoutSec, PreferLogonDC, EnableSiteCostedReferrals, SyncIntervalSec, UseFqdn | ConvertTo-Json")
 
         if ps_results.error?
-          raise "The dfs_server resource failed to fetch the current state via the Get-DfsnServerConfiguration PowerShell cmlet. Is the DFS Windows feature installed?"
+          raise "The dfs_server resource failed to fetch the current state via the Get-DfsnServerConfiguration PowerShell cmdlet. Is the DFS Windows feature installed?"
         end
 
         Chef::Log.debug("The Get-DfsnServerConfiguration results were #{ps_results.stdout}")

data/lib/chef/resource/windows_firewall_rule.rb

@@ -93,7 +93,7 @@ class Chef
         description: "The local address the firewall rule applies to."
 
       property :local_port, [String, Integer, Array],
-               # split various formats of comma separated lists and provide a sorted array of strings to match PS output
+        # split various formats of comma separated lists and provide a sorted array of strings to match PS output
         coerce: proc { |d| d.is_a?(String) ? d.split(/\s*,\s*/).sort : Array(d).sort.map(&:to_s) },
         description: "The local port the firewall rule applies to."
 
@@ -101,7 +101,7 @@ class Chef
         description: "The remote address the firewall rule applies to."
 
       property :remote_port, [String, Integer, Array],
-               # split various formats of comma separated lists and provide a sorted array of strings to match PS output
+        # split various formats of comma separated lists and provide a sorted array of strings to match PS output
         coerce: proc { |d| d.is_a?(String) ? d.split(/\s*,\s*/).sort : Array(d).sort.map(&:to_s) },
         description: "The remote port the firewall rule applies to."
 

data/lib/chef/resource/windows_font.rb

@@ -42,7 +42,7 @@ class Chef
 
       property :source, String,
         description: "A local filesystem path or URI that is used to source the font file.",
-        coerce: proc { |x| x =~ /^.:.*/ ? x.tr('\\', "/").gsub("//", "/") : x }
+        coerce: proc { |x| /^.:.*/.match?(x) ? x.tr('\\', "/").gsub("//", "/") : x }
 
       action :install do
         description "Install a font to the system fonts directory."
@@ -84,7 +84,7 @@ class Chef
 
         # install the font into the appropriate fonts directory
         def install_font
-          require "win32ole" if RUBY_PLATFORM =~ /mswin|mingw32|windows/
+          require "win32ole" if RUBY_PLATFORM.match?(/mswin|mingw32|windows/)
           fonts_dir = Chef::Util::PathHelper.join(ENV["windir"], "fonts")
           folder = WIN32OLE.new("Shell.Application").Namespace(fonts_dir)
           converge_by("install font #{new_resource.font_name} to #{fonts_dir}") do
@@ -96,7 +96,7 @@ class Chef
         #
         # @return [Boolean] Is the font is installed?
         def font_exists?
-          require "win32ole" if RUBY_PLATFORM =~ /mswin|mingw32|windows/
+          require "win32ole" if RUBY_PLATFORM.match?(/mswin|mingw32|windows/)
           fonts_dir = WIN32OLE.new("WScript.Shell").SpecialFolders("Fonts")
           logger.trace("Seeing if the font at #{Chef::Util::PathHelper.join(fonts_dir, new_resource.font_name)} exists")
           ::File.exist?(Chef::Util::PathHelper.join(fonts_dir, new_resource.font_name))

data/lib/chef/resource/windows_package.rb

@@ -19,7 +19,7 @@
 require_relative "../mixin/uris"
 require_relative "package"
 require_relative "../provider/package/windows"
-require_relative "../win32/error" if RUBY_PLATFORM =~ /mswin|mingw|windows/
+require_relative "../win32/error" if RUBY_PLATFORM.match?(/mswin|mingw|windows/)
 require_relative "../dist"
 
 class Chef
@@ -104,8 +104,8 @@ class Chef
         description: "An optional property to set the package name if it differs from the resource block's name.",
         identity: true
 
-      property :version, String,
-        description: "The version of a package to be installed or upgraded."
+      # we don't redefine the version property as a string here since we store the current value
+      # of version and that may be an array if multiple versions of a package are present on the system
 
       # windows can't take array options yet
       property :options, String,

data/lib/chef/resource/windows_pagefile.rb

@@ -113,7 +113,7 @@ class Chef
         # we do this here and not in the property itself because if automatic_managed
         # is set then this validation is not necessary / doesn't make sense at all
         def validate_name
-          return if /^.:.*.sys/ =~ new_resource.path
+          return if /^.:.*.sys/.match?(new_resource.path)
 
           raise "#{new_resource.path} does not match the format DRIVE:\\path\\file.sys for pagefiles. Example: C:\\pagefile.sys"
         end
@@ -124,7 +124,7 @@ class Chef
         # @return [Boolean]
         def exists?(pagefile)
           @exists ||= begin
-            logger.trace("Checking if #{pagefile} exists by runing: wmic.exe pagefileset where SettingID=\"#{get_setting_id(pagefile)}\" list /format:list")
+            logger.trace("Checking if #{pagefile} exists by running: wmic.exe pagefileset where SettingID=\"#{get_setting_id(pagefile)}\" list /format:list")
             cmd = shell_out("wmic.exe pagefileset where SettingID=\"#{get_setting_id(pagefile)}\" list /format:list", returns: [0])
             cmd.stderr.empty? && (cmd.stdout =~ /SettingID=#{get_setting_id(pagefile)}/i)
           end

data/lib/chef/resource/windows_printer.rb

@@ -62,7 +62,7 @@ class Chef
 
       property :driver_name, String,
         description: "The exact name of printer driver installed on the system.",
-        required: true
+        required: [:create]
 
       property :location, String,
         description: "Printer location, such as `Fifth floor copy room`."

data/lib/chef/resource/windows_script.rb

@@ -16,34 +16,20 @@
 # limitations under the License.
 #
 
-require_relative "../platform/query_helpers"
 require_relative "script"
 require_relative "../mixin/windows_architecture_helper"
 
 class Chef
   class Resource
     class WindowsScript < Chef::Resource::Script
-      unified_mode true
+      include Chef::Mixin::WindowsArchitectureHelper
 
-      provides :windows_script
+      unified_mode true
 
       # This is an abstract resource meant to be subclasses; thus no 'provides'
 
       set_guard_inherited_attributes(:architecture)
 
-      protected
-
-      def initialize(name, run_context, resource_name, interpreter_command)
-        super(name, run_context)
-        @interpreter = interpreter_command
-        @resource_name = resource_name if resource_name
-        @default_guard_interpreter = self.resource_name
-      end
-
-      include Chef::Mixin::WindowsArchitectureHelper
-
-      public
-
       def architecture(arg = nil)
         assert_architecture_compatible!(arg) unless arg.nil?
         result = set_or_return(

data/lib/chef/resource/windows_security_policy.rb

@@ -21,28 +21,59 @@ require_relative "../resource"
 class Chef
   class Resource
     class WindowsSecurityPolicy < Chef::Resource
-      resource_name :windows_security_policy
+      provides :windows_security_policy
 
       # The valid policy_names options found here
       # https://github.com/ChrisAWalker/cSecurityOptions under 'AccountSettings'
-      policy_names = %w{MinimumPasswordAge
-                MaximumPasswordAge
-                MinimumPasswordLength
-                PasswordComplexity
-                PasswordHistorySize
-                LockoutBadCount
-                RequireLogonToChangePassword
-                ForceLogoffWhenHourExpire
-                NewAdministratorName
-                NewGuestName
-                ClearTextPassword
-                LSAAnonymousNameLookup
-                EnableAdminAccount
-                EnableGuestAccount
-                }
+      policy_names = %w{LockoutDuration
+                        MaximumPasswordAge
+                        MinimumPasswordAge
+                        MinimumPasswordLength
+                        PasswordComplexity
+                        PasswordHistorySize
+                        LockoutBadCount
+                        ResetLockoutCount
+                        RequireLogonToChangePassword
+                        ForceLogoffWhenHourExpire
+                        NewAdministratorName
+                        NewGuestName
+                        ClearTextPassword
+                        LSAAnonymousNameLookup
+                        EnableAdminAccount
+                        EnableGuestAccount
+                       }
       description "Use the **windows_security_policy** resource to set a security policy on the Microsoft Windows platform."
       introduced "16.0"
 
+      examples <<~DOC
+      **Set Administrator Account to Enabled**:
+
+      ```ruby
+      windows_security_policy 'EnableAdminAccount' do
+        secvalue       '1'
+        action         :set
+      end
+      ```
+
+      **Rename Administrator Account**:
+
+      ```ruby
+      windows_security_policy 'NewAdministratorName' do
+        secvalue       'AwesomeChefGuy'
+        action         :set
+      end
+      ```
+
+      **Set Guest Account to Disabled**:
+
+      ```ruby
+      windows_security_policy 'EnableGuestAccount' do
+        secvalue       '0'
+        action         :set
+      end
+      ```
+      DOC
+
       property :secoption, String, name_property: true, required: true, equal_to: policy_names,
       description: "The name of the policy to be set on windows platform to maintain its security."
 

data/lib/chef/resource/windows_share.rb

@@ -187,8 +187,8 @@ class Chef
         [f_users, c_users, r_users]
       end
 
-# local names are returned from Get-SmbShareAccess in the full format MACHINE\\NAME
-# but users of this resource would simply say NAME so we need to strip the values for comparison
+      # local names are returned from Get-SmbShareAccess in the full format MACHINE\\NAME
+      # but users of this resource would simply say NAME so we need to strip the values for comparison
       def stripped_account(name)
         name.slice!("#{node["hostname"]}\\")
         name

data/lib/chef/resource/windows_shortcut.rb

@@ -34,7 +34,6 @@ class Chef
         description 'Make a shortcut to C:\\original_dir'
       end
       ```
-
       DOC
 
       property :shortcut_name, String,
@@ -57,7 +56,7 @@ class Chef
         description: "Icon to use for the shortcut. Accepts the format of `path, index`, where index is the icon file to use. See Microsoft's [documentation](https://msdn.microsoft.com/en-us/library/3s9bx7at.aspx) for details"
 
       load_current_value do |desired|
-        require "win32ole" if RUBY_PLATFORM =~ /mswin|mingw32|windows/
+        require "win32ole" if RUBY_PLATFORM.match?(/mswin|mingw32|windows/)
 
         link = WIN32OLE.new("WScript.Shell").CreateShortcut(desired.shortcut_name)
         name desired.shortcut_name

data/lib/chef/resource/windows_task.rb

@@ -189,11 +189,11 @@ class Chef
                description: "The frequency with which to run the task."
 
       property :start_day, String,
-        description: "Specifies the first date on which the task runs in MM/DD/YYYY format.",
+        description: "Specifies the first date on which the task runs in **MM/DD/YYYY** format.",
         default_description: "The current date."
 
       property :start_time, String,
-        description: "Specifies the start time to run the task, in HH:mm format."
+        description: "Specifies the start time to run the task, in **HH:mm** format."
 
       property :day, [String, Integer],
         description: "The day(s) on which the task runs."
@@ -272,16 +272,16 @@ class Chef
 
       private
 
-        ## Resource is not idempotent when day, start_day is not provided with frequency :weekly
-        ## we set start_day when not given by user as current date based on which we set the day property for current current date day is monday ..
-        ## we set the monday as the day so at next run when  new_resource.day is nil and current_resource day is monday due to which udpate gets called
+      ## Resource is not idempotent when day, start_day is not provided with frequency :weekly
+      ## we set start_day when not given by user as current date based on which we set the day property for current current date day is monday ..
+      ## we set the monday as the day so at next run when  new_resource.day is nil and current_resource day is monday due to which update gets called
       def idempotency_warning_for_frequency_weekly(day, start_day)
         if start_day.nil? && day.nil?
           logger.warn "To maintain idempotency for frequency :weekly provide start_day, start_time and day."
         end
       end
 
-        # Validate the passed value is numeric values only if it is a string
+      # Validate the passed value is numeric values only if it is a string
       def numeric_value_in_string?(val)
         return true if Integer(val)
       rescue ArgumentError
@@ -295,19 +295,19 @@ class Chef
       end
 
       def validate_frequency_monthly(frequency_modifier, months, day)
-        # validates the frequency :monthly and raises error if frequency_modifier is first, second, thrid etc and day is not provided
+        # validates the frequency :monthly and raises error if frequency_modifier is first, second, third etc and day is not provided
         if (frequency_modifier != 1) && (frequency_modifier_includes_days_of_weeks?(frequency_modifier)) && !(day)
-          raise ArgumentError, "Please select day on which you want to run the task e.g. 'Mon, Tue'. Multiple values must be seprated by comma."
+          raise ArgumentError, "Please select day on which you want to run the task e.g. 'Mon, Tue'. Multiple values must be separated by comma."
         end
 
-        # frequency_modifer 2-12 is used to set every (n) months, so using :months propety with frequency_modifer is not valid since they both used to set months.
-        # Not checking value 1 here for frequecy_modifier since we are setting that as default value it won't break anything since preference is given to months property
+        # frequency_modifier 2-12 is used to set every (n) months, so using :months property with frequency_modifier is not valid since they both used to set months.
+        # Not checking value 1 here for frequency_modifier since we are setting that as default value it won't break anything since preference is given to months property
         if (frequency_modifier.to_i.between?(2, 12)) && !(months.nil?)
           raise ArgumentError, "For frequency :monthly either use property months or frequency_modifier to set months."
         end
       end
 
-        # returns true if frequency_modifer has values First, second, third, fourth, last, lastday
+      # returns true if frequency_modifier has values First, second, third, fourth, last, lastday
       def frequency_modifier_includes_days_of_weeks?(frequency_modifier)
         frequency_modifier = frequency_modifier.to_s.split(",")
         frequency_modifier.map! { |value| value.strip.upcase }
@@ -322,7 +322,7 @@ class Chef
         raise ArgumentError, "Invalid value passed for `random_delay`. Please pass seconds as an Integer (e.g. 60) or a String with numeric values only (e.g. '60')." unless numeric_value_in_string?(random_delay)
       end
 
-        # @todo when we drop ruby 2.3 support this should be converted to .match?() instead of =~f
+      # @todo when we drop ruby 2.3 support this should be converted to .match?() instead of =~f
       def validate_start_day(start_day, frequency)
         if start_day && frequency == :none
           raise ArgumentError, "`start_day` property is not supported with frequency: #{frequency}"
@@ -330,15 +330,15 @@ class Chef
 
         # make sure the start_day is in MM/DD/YYYY format: http://rubular.com/r/cgjHemtWl5
         if start_day
-          raise ArgumentError, "`start_day` property must be in the MM/DD/YYYY format." unless %r{^(0[1-9]|1[012])[- /.](0[1-9]|[12][0-9]|3[01])[- /.](19|20)\d\d$} =~ start_day
+          raise ArgumentError, "`start_day` property must be in the MM/DD/YYYY format." unless %r{^(0[1-9]|1[012])[- /.](0[1-9]|[12][0-9]|3[01])[- /.](19|20)\d\d$}.match?(start_day)
         end
       end
 
-        # @todo when we drop ruby 2.3 support this should be converted to .match?() instead of =~
+      # @todo when we drop ruby 2.3 support this should be converted to .match?() instead of =~
       def validate_start_time(start_time, frequency)
         if start_time
           raise ArgumentError, "`start_time` property is not supported with `frequency :none`" if frequency == :none
-          raise ArgumentError, "`start_time` property must be in the HH:mm format (e.g. 6:20pm -> 18:20)." unless /^[0-2][0-9]:[0-5][0-9]$/ =~ start_time
+          raise ArgumentError, "`start_time` property must be in the HH:mm format (e.g. 6:20pm -> 18:20)." unless /^[0-2][0-9]:[0-5][0-9]$/.match?(start_time)
         else
           raise ArgumentError, "`start_time` needs to be provided with `frequency :once`" if frequency == :once
         end
@@ -434,7 +434,7 @@ class Chef
         end
       end
 
-        # This method returns true if day has values from 1-31 which is a days of moths and used with frequency :monthly
+      # This method returns true if day has values from 1-31 which is a days of moths and used with frequency :monthly
       def days_includes_days_of_months?(days)
         days.map! { |day| day.to_s.strip.downcase }
         (days - VALID_DAYS_OF_MONTH).empty?
@@ -452,11 +452,11 @@ class Chef
         end
       end
 
-        # Converts the number of seconds to an ISO8601 duration format and returns it.
-        # Ref : https://github.com/arnau/ISO8601/blob/master/lib/iso8601/duration.rb#L18-L23
-        # e.g.
-        # ISO8601::Duration.new(65707200).to_s
-        # returns 'PT65707200S'
+      # Converts the number of seconds to an ISO8601 duration format and returns it.
+      # Ref : https://github.com/arnau/ISO8601/blob/master/lib/iso8601/duration.rb#L18-L23
+      # e.g.
+      # ISO8601::Duration.new(65707200).to_s
+      # returns 'PT65707200S'
       def sec_to_dur(seconds)
         ISO8601::Duration.new(seconds.to_i).to_s
       end

data/lib/chef/resource/windows_user_privilege.rb

@@ -68,10 +68,52 @@ class Chef
                         }
 
       provides :windows_user_privilege
-      description "The windows_user_privilege resource allows to add and set principal (User/Group) to the specified privilege. \n Ref: https://docs.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/user-rights-assignment"
+      description "The windows_user_privilege resource allows to add and set principal (User/Group) to the specified privilege.\n Ref: https://docs.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/user-rights-assignment"
 
       introduced "16.0"
 
+      examples <<~DOC
+      **Set the SeNetworkLogonRight Privilege for the Builtin Administrators Group and Authenticated Users**:
+
+      ```ruby
+      windows_user_privilege 'Network Logon Rights' do
+        privilege      'SeNetworkLogonRight'
+        users          ['BUILTIN\\Administrators', 'NT AUTHORITY\\Authenticated Users']
+        action         :set
+      end
+      ```
+
+      **Add the SeDenyRemoteInteractiveLogonRight Privilege to the Builtin Guests and Local Accounts User Groups**:
+
+      ```ruby
+      windows_user_privilege 'Remote interactive logon' do
+        privilege      'SeDenyRemoteInteractiveLogonRight'
+        users          ['Builtin\\Guests', 'NT AUTHORITY\\Local Account']
+        action         :add
+      end
+      ```
+
+      **Provide only the Builtin Guests and Administrator Groups with the SeCreatePageFile Privilege**:
+
+      ```ruby
+      windows_user_privilege 'Create Pagefile' do
+        privilege      'SeCreatePagefilePrivilege'
+        users          ['BUILTIN\\Guests', 'BUILTIN\\Administrators']
+        action         :set
+      end
+      ```
+
+      **Remove the SeCreatePageFile Privilege from the Builtin Guests Group**:
+
+      ```ruby
+      windows_user_privilege 'Create Pagefile' do
+        privilege      'SeCreatePagefilePrivilege'
+        users          ['BUILTIN\\Guests']
+        action         :remove
+      end
+      ```
+      DOC
+
       property :principal, String,
         description: "An optional property to add the user to the given privilege. Use only with add and remove action.",
         name_property: true
@@ -84,8 +126,8 @@ class Chef
         required: true,
         coerce: proc { |v| v.is_a?(String) ? Array[v] : v },
         callbacks: {
-           "Option privilege must include any of the: #{privilege_opts}" => lambda {
-             |v| (privilege_opts & v).size == v.size
+           "Option privilege must include any of the: #{privilege_opts}" => lambda { |v|
+             (privilege_opts & v).size == v.size
            },
          }