chef 16.0.257 → 16.2.44

data/lib/chef/resource/windows_auto_run.rb

@@ -23,8 +23,19 @@ class Chef
     class WindowsAutorun < Chef::Resource
       provides(:windows_auto_run) { true }
 
-      description "Use the windows_auto_run resource to set applications to run at login."
+      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.",
@@ -32,7 +43,7 @@ class Chef
 
       property :path, String,
         coerce: proc { |x| x.tr("/", "\\") }, # make sure we have windows paths for the registry
-        description: "The path to the program that will run at login. "
+        description: "The path to the program that will run at login."
 
       property :args, String,
         description: "Any arguments to be used with the program."

data/lib/chef/resource/windows_certificate.rb

@@ -28,8 +28,34 @@ class Chef
     class WindowsCertificate < Chef::Resource
       provides :windows_certificate
 
-      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."
+      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_folder.rb

@@ -23,7 +23,7 @@ class Chef
     class WindowsDfsFolder < Chef::Resource
       provides :windows_dfs_folder
 
-      description "The windows_dfs_folder resources creates a folder within dfs as many levels deep as required."
+      description "Use the **windows_dfs_folder** resource to creates a folder within DFS as many levels deep as required."
       introduced "15.0"
 
       property :folder_path, String,

data/lib/chef/resource/windows_dfs_namespace.rb

@@ -23,7 +23,7 @@ class Chef
     class WindowsDfsNamespace < Chef::Resource
       provides :windows_dfs_namespace
 
-      description "Creates a share and DFS namespace on the local server."
+      description "Use the **windows_dfs_namespace** resource to creates a share and DFS namespace on a Windows server."
       introduced "15.0"
 
       property :namespace_name, String,

data/lib/chef/resource/windows_dfs_server.rb

@@ -23,7 +23,7 @@ class Chef
     class WindowsDfsServer < Chef::Resource
       provides :windows_dfs_server
 
-      description "The windows_dfs_server resource sets system-wide DFS settings."
+      description "Use the **windows_dfs_server** resource to set system-wide DFS settings."
       introduced "15.0"
 
       property :use_fqdn, [TrueClass, FalseClass],
@@ -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_env.rb

@@ -25,7 +25,16 @@ class Chef
       provides :windows_env
       provides :env # backwards compat with the pre-Chef 14 resource name
 
-      description "Use the windows_env resource to manage environment keys in Microsoft Windows. After an environment key is set, Microsoft Windows must be restarted before the environment key will be available to the Task Scheduler."
+      description "Use the **windows_env** resource to manage environment keys in Microsoft Windows. After an environment key is set, Microsoft Windows must be restarted before the environment key will be available to the Task Scheduler."
+      examples <<~DOC
+      **Set an environment variable**:
+
+      ```ruby
+      windows_env 'ComSpec' do
+        value 'C:\\Windows\\system32\\cmd.exe'
+      end
+      ```
+      DOC
 
       default_action :create
       allowed_actions :create, :delete, :modify

data/lib/chef/resource/windows_feature.rb

@@ -23,8 +23,63 @@ class Chef
     class WindowsFeature < Chef::Resource
       provides(:windows_feature) { true }
 
-      description "Use the windows_feature resource to add, remove or entirely delete Windows features and roles. This resource calls the 'windows_feature_dism' or 'windows_feature_powershell' resources depending on the specified installation method, and defaults to DISM, which is available on both Workstation and Server editions of Windows."
+      description "Use the **windows_feature** resource to add, remove or entirely delete Windows features and roles. This resource calls the 'windows_feature_dism' or 'windows_feature_powershell' resources depending on the specified installation method, and defaults to DISM, which is available on both Workstation and Server editions of Windows."
       introduced "14.0"
+      examples <<~DOC
+      **Install the DHCP Server feature**:
+
+      ```ruby
+      windows_feature 'DHCPServer' do
+        action :install
+      end
+      ```
+
+      **Install the .Net 3.5.1 feature using repository files on DVD**:
+
+      ```ruby
+      windows_feature "NetFx3" do
+        action :install
+        source 'd:\\sources\\sxs'
+      end
+      ```
+
+      **Remove Telnet Server and Client features**:
+
+      ```ruby
+      windows_feature %w(TelnetServer TelnetClient) do
+        action :remove
+      end
+      ```
+
+      **Add the SMTP Server feature using the PowerShell provider**:
+
+      ```ruby
+      windows_feature 'smtp-server' do
+        action :install
+        all true
+        install_method :windows_feature_powershell
+      end
+      ```
+
+      **Install multiple features using one resource with the PowerShell provider**:
+
+      ```ruby
+      windows_feature %w(Web-Asp-Net45 Web-Net-Ext45) do
+        action :install
+        install_method :windows_feature_powershell
+      end
+      ```
+
+      **Install the Network Policy and Access Service feature, including the management tools**:
+
+      ```ruby
+      windows_feature 'NPAS' do
+        action :install
+        management_tools true
+        install_method :windows_feature_powershell
+      end
+      ```
+      DOC
 
       property :feature_name, [Array, String],
         description: "The name of the feature(s) or role(s) to install if they differ from the resource block's name. The same feature may have different names depending on the underlying installation method being used (ie DHCPServer vs DHCP; DNS-Server-Full-Role vs DNS).",
@@ -42,7 +97,7 @@ class Chef
         default: false
 
       property :install_method, Symbol,
-        description: "The underlying installation method to use for feature installation. Specify ':windows_feature_dism' for DISM or ':windows_feature_powershell' for PowerShell.",
+        description: "The underlying installation method to use for feature installation. Specify `:windows_feature_dism` for DISM or `:windows_feature_powershell` for PowerShell.",
         equal_to: %i{windows_feature_dism windows_feature_powershell windows_feature_servermanagercmd},
         default: :windows_feature_dism
 

data/lib/chef/resource/windows_feature_dism.rb

@@ -24,8 +24,21 @@ class Chef
     class WindowsFeatureDism < Chef::Resource
       provides(:windows_feature_dism) { true }
 
-      description "Use the windows_feature_dism resource to add, remove, or entirely delete Windows features and roles using DISM."
+      description "Use the **windows_feature_dism** resource to add, remove, or entirely delete Windows features and roles using DISM."
       introduced "14.0"
+      examples <<~DOC
+      **Installing the TelnetClient service**:
+
+      ```ruby
+      windows_feature_dism "TelnetClient"
+      ```
+
+      **Installing two features by using an array**:
+
+      ```ruby
+      windows_feature_dism %w(TelnetClient TFTP)
+      ```
+      DOC
 
       property :feature_name, [Array, String],
         description: "The name of the feature(s) or role(s) to install if they differ from the resource name.",
@@ -36,7 +49,7 @@ class Chef
         description: "Specify a local repository for the feature install."
 
       property :all, [TrueClass, FalseClass],
-        description: "Install all sub-features. When set to 'true', this is the equivalent of specifying the /All switch to dism.exe",
+        description: "Install all sub-features. When set to `true`, this is the equivalent of specifying the `/All` switch to `dism.exe`",
         default: false
 
       property :timeout, Integer,

data/lib/chef/resource/windows_feature_powershell.rb

@@ -25,8 +25,35 @@ class Chef
     class WindowsFeaturePowershell < Chef::Resource
       provides(:windows_feature_powershell) { true }
 
-      description "Use the windows_feature_powershell resource to add, remove, or entirely delete Windows features and roles using PowerShell. This resource offers significant speed benefits over the windows_feature_dism resource, but requires installation of the Remote Server Administration Tools on non-server releases of Windows."
+      description "Use the **windows_feature_powershell** resource to add, remove, or entirely delete Windows features and roles using PowerShell. This resource offers significant speed benefits over the windows_feature_dism resource, but requires installation of the Remote Server Administration Tools on non-server releases of Windows."
       introduced "14.0"
+      examples <<~DOC
+      **Add the SMTP Server feature**:
+
+      ```ruby
+      windows_feature_powershell "smtp-server" do
+        action :install
+        all true
+      end
+      ```
+
+      **Install multiple features using one resource**:
+
+      ```ruby
+      windows_feature_powershell ['Web-Asp-Net45', 'Web-Net-Ext45'] do
+        action :install
+      end
+      ```
+
+      **Install the Network Policy and Access Service feature**:
+
+      ```ruby
+      windows_feature_powershell 'NPAS' do
+        action :install
+        management_tools true
+      end
+      ```
+      DOC
 
       property :feature_name, [Array, String],
         description: "The name of the feature(s) or role(s) to install if they differ from the resource block's name.",
@@ -37,7 +64,7 @@ class Chef
         description: "Specify a local repository for the feature install."
 
       property :all, [TrueClass, FalseClass],
-        description: "Install all subfeatures. When set to 'true', this is the equivalent of specifying the '-InstallAllSubFeatures' switch with 'Add-WindowsFeature'.",
+        description: "Install all subfeatures. When set to `true`, this is the equivalent of specifying the `-InstallAllSubFeatures` switch with `Add-WindowsFeature`.",
         default: false
 
       property :timeout, Integer,

data/lib/chef/resource/windows_firewall_rule.rb

@@ -26,10 +26,11 @@ class Chef
     class WindowsFirewallRule < Chef::Resource
       provides :windows_firewall_rule
 
-      description "Use the windows_firewall_rule resource to create, change or remove Windows firewall rules."
+      description "Use the **windows_firewall_rule** resource to create, change or remove Windows firewall rules."
       introduced "14.7"
       examples <<~DOC
-      Allowing port 80 access
+      **Allowing port 80 access**:
+
       ```ruby
       windows_firewall_rule 'IIS' do
         local_port '80'
@@ -38,7 +39,8 @@ class Chef
       end
       ```
 
-      Allow protocol ICMPv6 with ICMP Type
+      **Allow protocol ICMPv6 with ICMP Type**:
+
       ```ruby
       windows_firewall_rule 'CoreNet-Rule' do
         rule_name 'CoreNet-ICMP6-LR2-In'
@@ -49,7 +51,8 @@ class Chef
       end
       ```
 
-      Blocking WinRM over HTTP on a particular IP
+      **Blocking WinRM over HTTP on a particular IP**:
+
       ```ruby
       windows_firewall_rule 'Disable WinRM over HTTP' do
         local_port '5985'
@@ -59,7 +62,8 @@ class Chef
       end
       ```
 
-      Deleting an existing rule
+      **Deleting an existing rule**
+
       ```ruby
       windows_firewall_rule 'Remove the SSH rule' do
         rule_name 'ssh'
@@ -89,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."
 
@@ -97,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

@@ -24,8 +24,17 @@ class Chef
 
       provides(:windows_font) { true }
 
-      description "Use the windows_font resource to install font files on Windows. By default, the font is sourced from the cookbook using the resource, but a URI source can be specified as well."
+      description "Use the **windows_font** resource to install font files on Windows. By default, the font is sourced from the cookbook using the resource, but a URI source can be specified as well."
       introduced "14.0"
+      examples <<~DOC
+      **Install a font from a https source**:
+
+      ```ruby
+      windows_font 'Custom.otf' do
+        source "https://example.com/Custom.otf"
+      end
+      ```
+      DOC
 
       property :font_name, String,
         description: "An optional property to set the name of the font to install if it differs from the resource block's name.",
@@ -33,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."
@@ -75,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
@@ -87,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
@@ -30,8 +30,68 @@ class Chef
       provides(:windows_package) { true }
       provides :package, os: "windows"
 
-      description "Use the windows_package resource to manage packages on the Microsoft Windows platform. The windows_package resource supports these installer formats:\n\n Microsoft Installer Package (MSI)\n Nullsoft Scriptable Install System (NSIS)\n Inno Setup (inno)\n Wise\n InstallShield\n Custom installers such as installing a non-.msi file that embeds an .msi-based installer\n"
+      description "Use the **windows_package** resource to manage packages on the Microsoft Windows platform. The windows_package resource supports these installer formats:\n\n Microsoft Installer Package (MSI)\n Nullsoft Scriptable Install System (NSIS)\n Inno Setup (inno)\n Wise\n InstallShield\n Custom installers such as installing a non-.msi file that embeds an .msi-based installer\n"
       introduced "11.12"
+      examples <<~DOC
+      **Install a package**:
+
+      ```ruby
+      windows_package '7zip' do
+        action :install
+        source 'C:\\7z920.msi'
+      end
+      ```
+
+      **Specify a URL for the source attribute**:
+
+      ```ruby
+      windows_package '7zip' do
+        source 'http://www.7-zip.org/a/7z938-x64.msi'
+      end
+      ```
+
+      **Specify path and checksum**:
+
+      ```ruby
+      windows_package '7zip' do
+        source 'http://www.7-zip.org/a/7z938-x64.msi'
+        checksum '7c8e873991c82ad9cfc123415254ea6101e9a645e12977dcd518979e50fdedf3'
+      end
+      ```
+
+      **Modify remote_file resource attributes**:
+
+      The windows_package resource may specify a package at a remote location using the remote_file_attributes property. This uses the remote_file resource to download the contents at the specified URL and passes in a Hash that modifies the properties of the remote_file resource.
+
+      ```ruby
+      windows_package '7zip' do
+        source 'http://www.7-zip.org/a/7z938-x64.msi'
+        remote_file_attributes ({
+          :path => 'C:\\7zip.msi',
+          :checksum => '7c8e873991c82ad9cfc123415254ea6101e9a645e12977dcd518979e50fdedf3'
+        })
+      end
+      ```
+
+      **Download a nsis (Nullsoft) package resource**:
+
+      ```ruby
+      windows_package 'Mercurial 3.6.1 (64-bit)' do
+        source 'http://mercurial.selenic.com/release/windows/Mercurial-3.6.1-x64.exe'
+        checksum 'febd29578cb6736163d232708b834a2ddd119aa40abc536b2c313fc5e1b5831d'
+      end
+      ```
+
+      **Download a custom package**:
+
+      ```ruby
+      windows_package 'Microsoft Visual C++ 2005 Redistributable' do
+        source 'https://download.microsoft.com/download/6/B/B/6BB661D6-A8AE-4819-B79F-236472F6070C/vcredist_x86.exe'
+        installer_type :custom
+        options '/Q'
+      end
+      ```
+      DOC
 
       allowed_actions :install, :remove
 
@@ -44,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,
@@ -75,11 +135,11 @@ class Chef
           end
         end),
         default_description: "The resource block's name", # this property is basically a name_property but not really so we need to spell it out
-        description: "The path to a package in the local file system. The location of the package may be at a URL. \n"
+        description: "The path to a package in the local file system. The location of the package may be at a URL."
 
       property :checksum, String,
         desired_state: false, coerce: (proc { |c| c.downcase }),
-        description: "The SHA-256 checksum of the file. Use to prevent a file from being re-downloaded. When the local file matches the checksum, #{Chef::Dist::PRODUCT} does not download it. Use when a URL is specified by the source property."
+        description: "The SHA-256 checksum of the file. Use to prevent a file from being re-downloaded. When the local file matches the checksum, #{Chef::Dist::PRODUCT} does not download it. Use when a URL is specified by the `source` property."
 
       property :remote_file_attributes, Hash,
         desired_state: false,