chef 17.4.38 → 17.7.22

data/lib/chef/resource/powershell_package_source.rb

@@ -1,4 +1,5 @@
 # Author:: Tor Magnus Rakvåg (tm@intility.no)
+# Author:: John McCrae (john.mccrae@progress.com)
 # Copyright:: 2018, Intility AS
 # License:: Apache License, Version 2.0
 #
@@ -24,29 +25,110 @@ class Chef
 
       provides :powershell_package_source
 
-      description "Use the **powershell_package_source** resource to register a PowerShell package repository."
+      description "Use the **powershell_package_source** resource to register a PowerShell package source and a Powershell package provider. There are 2 distinct objects we care about here. The first is a Package Source like a PowerShell Repository or a Nuget Source. The second object is a provider that PowerShell uses to get to that source with, like PowerShellGet, Nuget, Chocolatey, etc. "
       introduced "14.3"
+      examples <<~DOC
+        **Add a new PSRepository that is not trusted and which requires credentials to connect to**:
+
+        ```ruby
+        powershell_package_source 'PowerShellModules' do
+          source_name                  "PowerShellModules"
+          source_location              "https://pkgs.dev.azure.com/some-org/some-project/_packaging/some_feed/nuget/v2"
+          publish_location             "https://pkgs.dev.azure.com/some-org/some-project/_packaging/some_feed/nuget/v2"
+          trusted                      false
+          user                         "someuser@somelocation.io"
+          password                     "my_password"
+          provider_name                "PSRepository"
+          action                       :register
+        end
+        ```
+
+        **Add a new Package Source that uses Chocolatey as the Package Provider**:
+
+        ```ruby
+        powershell_package_source 'PowerShellModules' do
+          source_name                  "PowerShellModules"
+          source_location              "https://pkgs.dev.azure.com/some-org/some-project/_packaging/some_feed/nuget/v2"
+          publish_location             "https://pkgs.dev.azure.com/some-org/some-project/_packaging/some_feed/nuget/v2"
+          trusted                      true
+          provider_name                "chocolatey"
+          action                       :register
+        end
+        ```
+
+        **Add a new PowerShell Script source that is trusted**:
+
+        ```ruby
+        powershell_package_source 'MyDodgyScript' do
+          source_name                  "MyDodgyScript"
+          script_source_location       "https://pkgs.dev.azure.com/some-org/some-project/_packaging/some_feed/nuget/v2"
+          script_publish_location      "https://pkgs.dev.azure.com/some-org/some-project/_packaging/some_feed/nuget/v2"
+          trusted                      true
+          action                       :register
+        end
+        ```
+
+        **Update my existing PSRepository to make it Trusted after all**:
+
+        ```ruby
+        powershell_package_source 'MyPSModule' do
+          source_name                  "MyPSModule"
+          trusted                      true
+          action                       :set
+        end
+        ```
+
+        **Update a Nuget package source with a new name and make it trusted**:
+
+        ```ruby
+        powershell_package_source 'PowerShellModules -> GoldFishBowl' do
+          source_name                  "PowerShellModules"
+          new_name                     "GoldFishBowl"
+          provider_name                "Nuget"
+          trusted                      true
+          action                       :set
+        end
+        ```
+
+        **Update a Nuget package source with a new name when the source is secured with a username and password**:
+
+        ```ruby
+        powershell_package_source 'PowerShellModules -> GoldFishBowl' do
+          source_name                  "PowerShellModules"
+          new_name                     "GoldFishBowl"
+          trusted                      true
+          user                         "user@domain.io"
+          password                     "some_secret_password"
+          action                       :set
+        end
+        ```
+
+        **Unregister a package source**:
+
+        ```ruby
+        powershell_package_source 'PowerShellModules' do
+          source_name                  "PowerShellModules"
+          action                       :unregister
+        end
+        ```
+      DOC
 
       property :source_name, String,
-        description: "The name of the package source.",
+        description: "A label that names your package source.",
         name_property: true
 
-      property :url, String,
-        description: "The URL to the package source.",
-        required: [:register]
+      property :new_name, String,
+        introduced: "17.6",
+        description: "Used to change the name of a standard package source."
 
-      property :trusted, [TrueClass, FalseClass],
-        description: "Whether or not to trust packages from this source.",
-        default: false
+      property :source_location, String,
+        introduced: "17.6",
+        description: "The URL to the location to retrieve modules from."
 
-      property :provider_name, String,
-        equal_to: %w{ Programs msi NuGet msu PowerShellGet psl chocolatey },
-        validation_message: "The following providers are supported: 'Programs', 'msi', 'NuGet', 'msu', 'PowerShellGet', 'psl' or 'chocolatey'",
-        description: "The package management provider for the source.",
-        default: "NuGet"
+      alias :url :source_location
 
       property :publish_location, String,
-        description: "The URL where modules will be published to for this source. Only valid if the provider is `PowerShellGet`."
+        description: "The URL where modules will be published to. Only valid if the provider is `PowerShellGet`."
 
       property :script_source_location, String,
         description: "The URL where scripts are located for this source. Only valid if the provider is `PowerShellGet`."
@@ -54,6 +136,24 @@ class Chef
       property :script_publish_location, String,
         description: "The location where scripts will be published to for this source. Only valid if the provider is `PowerShellGet`."
 
+      property :trusted, [TrueClass, FalseClass],
+        description: "Whether or not to trust packages from this source. Used when creating a NON-PSRepository Package Source",
+        default: false
+
+      property :user, String,
+        introduced: "17.6",
+        description: "A username that, as part of a credential object, is used to register a repository or other package source with."
+
+      property :password, String,
+        introduced: "17.6",
+        description: "A password that, as part of a credential object, is used to register a repository or other package source with."
+
+      property :provider_name, String,
+        equal_to: %w{ Programs msi NuGet msu PowerShellGet psl chocolatey winget },
+        validation_message: "The following providers are supported: 'Programs', 'msi', 'NuGet', 'msu', 'PowerShellGet', 'psl', 'chocolatey' or 'winget'",
+        description: "The package management provider for the package source. The default is PowerShellGet and this option need only be set otherwise in specific use cases.",
+        default: "NuGet"
+
       load_current_value do
         cmd = load_resource_state_script(source_name)
         repo = powershell_exec!(cmd)
@@ -62,7 +162,9 @@ class Chef
         else
           status = repo.result
         end
-        url status["url"]
+        source_name status["source_name"]
+        new_name status["new_name"]
+        source_location status["source_location"]
         trusted status["trusted"]
         provider_name status["provider_name"]
         publish_location status["publish_location"]
@@ -70,97 +172,159 @@ class Chef
         script_publish_location status["script_publish_location"]
       end
 
-      action :register, description: "Registers and updates the PowerShell package source." do
-        # TODO: Ensure package provider is installed?
-        if psrepository_cmdlet_appropriate?
-          if package_source_exists?
-            converge_if_changed :url, :trusted, :publish_location, :script_source_location, :script_publish_location do
-              update_cmd = build_ps_repository_command("Set", new_resource)
-              res = powershell_exec(update_cmd)
-              raise "Failed to update #{new_resource.source_name}: #{res.errors}" if res.error?
-            end
-          else
-            converge_by("register source: #{new_resource.source_name}") do
-              register_cmd = build_ps_repository_command("Register", new_resource)
-              res = powershell_exec(register_cmd)
-              raise "Failed to register #{new_resource.source_name}: #{res.errors}" if res.error?
-            end
+      # Notes:
+      # There are 2 objects we care about with this code. 1) The Package Provider which can be Nuget, PowerShellGet, Chocolatey, et al. 2) The PackageSource where the files we want access to live. The Package Provider gets us access to the Package Source.
+      # Per the Microsoft docs you can only have one provider for one source. Enter the PSRepository. It is a sub-type of Package Source.
+      # If you register a new PSRepository you get both a PSRepository object AND a Package Source object which are distinct. If you call "Get-PSRepository -Name 'PSGallery'" from powershell, notice that the Packageprovider is Nuget
+      # now go execute "Get-PackageSource -Name 'PSGallery'" and notice that the PackageProvider is PowerShellGet. If you set a new PSRepository without specifying a PackageProvider ("Register-PSRepository -Name 'foo' -source...") the command will create both
+      # a PackageSource and a PSRepository with different providers.
+
+      # Unregistering a PackageSource (unregister-packagesource -name 'foo') where that source is also a PSRepository also causes that object to delete as well. This makes sense as PSRepository is a sub-type of packagesource.
+      # All PSRepositories are PackageSources, and all PackageSources with Provider PowerShellGet are PSRepositories. They are 2 different views of the same object.
+
+      action :register, description: "Registers a PowerShell package source." do
+        package_details = get_package_source_details
+        output = package_details.result
+        if output == "PSRepository" || output == "PackageSource"
+          action_set
+        elsif new_resource.provider_name.downcase.strip == "powershellget"
+          converge_by("register source: #{new_resource.source_name}") do
+            register_cmd = build_ps_repository_command("Register", new_resource)
+            res = powershell_exec(register_cmd)
+            raise "Failed to register #{new_resource.source_name}: #{res.errors}" if res.error?
           end
         else
-          if package_source_exists?
-            converge_if_changed :url, :trusted, :provider_name do
-              update_cmd = build_package_source_command("Set", new_resource)
-              res = powershell_exec(update_cmd)
-              raise "Failed to update #{new_resource.source_name}: #{res.errors}" if res.error?
-            end
-          else
-            converge_by("register source: #{new_resource.source_name}") do
-              register_cmd = build_package_source_command("Register", new_resource)
-              res = powershell_exec(register_cmd)
-              raise "Failed to register #{new_resource.source_name}: #{res.errors}" if res.error?
-            end
+          converge_by("register source: #{new_resource.source_name}") do
+            register_cmd = build_package_source_command("Register", new_resource)
+            res = powershell_exec(register_cmd)
+            raise "Failed to register #{new_resource.source_name}: #{res.errors}" if res.error?
+          end
+        end
+      end
+
+      action :set, description: "Updates an existing PSRepository or Package Source" do
+        package_details = get_package_source_details
+        output = package_details.result
+        if output == "PSRepository"
+          converge_if_changed :source_location, :trusted, :publish_location, :script_source_location, :script_publish_location, :source_name do
+            set_cmd = build_ps_repository_command("Set", new_resource)
+            res = powershell_exec(set_cmd)
+            raise "Failed to Update #{new_resource.source_name}: #{res.errors}" if res.error?
+          end
+        elsif output == "PackageSource"
+          converge_if_changed :source_location, :trusted, :new_name, :provider_name do
+            set_cmd = build_package_source_command("Set", new_resource)
+            res = powershell_exec(set_cmd)
+            raise "Failed to Update #{new_resource.source_name}: #{res.errors}" if res.error?
           end
         end
       end
 
       action :unregister, description: "Unregisters the PowerShell package source." do
-        if package_source_exists?
-          unregister_cmd = "Get-PackageSource -Name '#{new_resource.source_name}' | Unregister-PackageSource"
+        package_details = get_package_source_details
+        output = package_details.result
+        if output == "PackageSource" || output == "PSRepository"
+          unregister_cmd = "Unregister-PackageSource -Name '#{new_resource.source_name}'"
           converge_by("unregister source: #{new_resource.source_name}") do
-            res = powershell_exec(unregister_cmd)
+            res = powershell_exec!(unregister_cmd)
             raise "Failed to unregister #{new_resource.source_name}: #{res.errors}" if res.error?
           end
+        else
+          logger.warn("*****************************************")
+          logger.warn("Failed to unregister #{new_resource.source_name}: Package Source does not exist")
+          logger.warn("*****************************************")
         end
       end
 
       action_class do
-        def package_source_exists?
-          cmd = powershell_exec!("(Get-PackageSource -Name '#{new_resource.source_name}' -ErrorAction SilentlyContinue).Name")
-          !cmd.result.empty? && cmd.result.to_s.downcase.strip == new_resource.source_name.downcase
-        end
 
-        def psrepository_cmdlet_appropriate?
-          new_resource.provider_name == "PowerShellGet"
+        def get_package_source_details
+          powershell_exec! <<~EOH
+              $package_details = Get-PackageSource -Name '#{new_resource.source_name}' -ErrorAction SilentlyContinue
+              if ($package_details.ProviderName -match "PowerShellGet"){
+                return "PSRepository"
+              }
+              elseif ($package_details.ProviderName ) {
+                return "PackageSource"
+              }
+              elseif ($null -eq $package_details)
+              {
+                return "Unregistered"
+              }
+          EOH
         end
 
         def build_ps_repository_command(cmdlet_type, new_resource)
-          cmd = "#{cmdlet_type}-PSRepository -Name '#{new_resource.source_name}'"
-          cmd << " -SourceLocation '#{new_resource.url}'" if new_resource.url
-          cmd << " -InstallationPolicy '#{new_resource.trusted ? "Trusted" : "Untrusted"}'"
-          cmd << " -PublishLocation '#{new_resource.publish_location}'" if new_resource.publish_location
-          cmd << " -ScriptSourceLocation '#{new_resource.script_source_location}'" if new_resource.script_source_location
-          cmd << " -ScriptPublishLocation '#{new_resource.script_publish_location}'" if new_resource.script_publish_location
-          cmd << " | Out-Null"
+          if new_resource.trusted == true
+            install_policy = "Trusted"
+          else
+            install_policy = "Untrusted"
+          end
+          if new_resource.user && new_resource.password
+            cmd =  "$user = '#{new_resource.user}';"
+            cmd << "[securestring]$secure_password = Convertto-SecureString -String '#{new_resource.password}' -AsPlainText -Force;"
+            cmd << "$Credentials = New-Object System.Management.Automation.PSCredential -Argumentlist ($user, $secure_password);"
+            cmd << "#{cmdlet_type}-PSRepository -Name '#{new_resource.source_name}'"
+            cmd << " -SourceLocation '#{new_resource.source_location}'" if new_resource.source_location
+            cmd << " -InstallationPolicy '#{install_policy}'"
+            cmd << " -PublishLocation '#{new_resource.publish_location}'" if new_resource.publish_location
+            cmd << " -ScriptSourceLocation '#{new_resource.script_source_location}'" if new_resource.script_source_location
+            cmd << " -ScriptPublishLocation '#{new_resource.script_publish_location}'" if new_resource.script_publish_location
+            cmd << " -Credential $Credentials"
+            cmd << " | Out-Null"
+          else
+            cmd = "#{cmdlet_type}-PSRepository -Name '#{new_resource.source_name}'"
+            cmd << " -SourceLocation '#{new_resource.source_location}'" if new_resource.source_location
+            cmd << " -InstallationPolicy '#{install_policy}'"
+            cmd << " -PublishLocation '#{new_resource.publish_location}'" if new_resource.publish_location
+            cmd << " -ScriptSourceLocation '#{new_resource.script_source_location}'" if new_resource.script_source_location
+            cmd << " -ScriptPublishLocation '#{new_resource.script_publish_location}'" if new_resource.script_publish_location
+            cmd << " | Out-Null"
+          end
           cmd
         end
 
         def build_package_source_command(cmdlet_type, new_resource)
-          cmd = "#{cmdlet_type}-PackageSource -Name '#{new_resource.source_name}'"
-          cmd << " -Location '#{new_resource.url}'" if new_resource.url
-          cmd << " -Trusted:#{new_resource.trusted ? "$true" : "$false"}"
-          cmd << " -ProviderName '#{new_resource.provider_name}'" if new_resource.provider_name
-          cmd << " | Out-Null"
-          cmd
+          if new_resource.user && new_resource.password
+            cmd =  "$user = '#{new_resource.user}';"
+            cmd << "[securestring]$secure_password = Convertto-SecureString -String '#{new_resource.password}' -AsPlainText -Force;"
+            cmd << "$Credentials = New-Object System.Management.Automation.PSCredential -Argumentlist ($user, $secure_password);"
+            cmd << "#{cmdlet_type}-PackageSource -Name '#{new_resource.source_name}'"
+            cmd << " -Location '#{new_resource.source_location}'" if new_resource.source_location
+            cmd << " -Trusted" if new_resource.trusted
+            cmd << " -ProviderName '#{new_resource.provider_name}'" if new_resource.provider_name
+            cmd << " -Credential $credentials"
+            cmd << " | Out-Null"
+            cmd
+          else
+            cmd = "#{cmdlet_type}-PackageSource -Name '#{new_resource.source_name}'"
+            cmd << " -NewName '#{new_resource.new_name}'" if new_resource.new_name
+            cmd << " -Location '#{new_resource.source_location}'" if new_resource.source_location
+            cmd << " -Trusted" if new_resource.trusted
+            cmd << " -ProviderName '#{new_resource.provider_name}'" if new_resource.provider_name
+            cmd << " | Out-Null"
+            cmd
+          end
         end
       end
     end
 
     private
 
-    def load_resource_state_script(name)
+    def load_resource_state_script(source_name)
       <<-EOH
         $PSDefaultParameterValues = @{
           "*:WarningAction" = "SilentlyContinue"
         }
-        if(Get-PackageSource -Name '#{name}' -ErrorAction SilentlyContinue) {
-            if ((Get-PackageSource -Name '#{name}').ProviderName -eq 'PowerShellGet') {
-                (Get-PSRepository -Name '#{name}') | Select @{n='source_name';e={$_.Name}}, @{n='url';e={$_.SourceLocation}},
+        if(Get-PackageSource -Name '#{source_name}' -ErrorAction SilentlyContinue) {
+            if ((Get-PackageSource -Name '#{source_name}').ProviderName -eq 'PowerShellGet') {
+                (Get-PSRepository -Name '#{source_name}') | Select @{n='source_name';e={$_.Name}}, @{n='source_location';e={$_.SourceLocation}},
                 @{n='trusted';e={$_.Trusted}}, @{n='provider_name';e={$_.PackageManagementProvider}}, @{n='publish_location';e={$_.PublishLocation}},
                 @{n='script_source_location';e={$_.ScriptSourceLocation}}, @{n='script_publish_location';e={$_.ScriptPublishLocation}}
             }
             else {
-                (Get-PackageSource -Name '#{name}') | Select @{n='source_name';e={$_.Name}}, @{n='url';e={$_.Location}},
-                @{n='provider_name';e={$_.ProviderName}}, @{n='trusted';e={$_.IsTrusted}}
+                (Get-PackageSource -Name '#{source_name}') | Select @{n='source_name';e={$_.Name}}, @{n='new_name';e={$_.Name}}, @{n='source_location';e={$_.Location}},
+                @{n='provider_name';e={$_.ProviderName}}, @{n='trusted';e={$_.IsTrusted}}, @{n='publish_location';e={$_.PublishLocation}}
             }
         }
       EOH

data/lib/chef/resource/registry_key.rb

@@ -18,6 +18,7 @@
 
 require_relative "../resource"
 require_relative "../digester"
+require "chef-utils/dist" unless defined?(ChefUtils::Dist)
 
 class Chef
   class Resource
@@ -26,7 +27,7 @@ class Chef
 
       provides(:registry_key) { true }
 
-      description "Use the **registry_key** resource to create and delete registry keys in Microsoft Windows."
+      description "Use the **registry_key** resource to create and delete registry keys in Microsoft Windows. Note: 64-bit versions of Microsoft Windows have a 32-bit compatibility layer in the registry that reflects and redirects certain keys (and their values) into specific locations (or logical views) of the registry hive.\n\n#{ChefUtils::Dist::Infra::PRODUCT} can access any reflected or redirected registry key. The machine architecture of the system on which #{ChefUtils::Dist::Infra::PRODUCT} is running is used as the default (non-redirected) location. Access to the SysWow64 location is redirected must be specified. Typically, this is only necessary to ensure compatibility with 32-bit applications that are running on a 64-bit operating system.\n\nFor more information, see: [Registry Reflection](https://docs.microsoft.com/en-us/windows/win32/winprog64/registry-reflection)."
       examples <<~'DOC'
       **Create a registry key**
 
@@ -66,7 +67,7 @@ class Chef
       end
       ```
 
-      **Set proxy settings to be the same as those used by Chef Infra Client**
+      **Set proxy settings to be the same as those used by #{ChefUtils::Dist::Infra::PRODUCT}**
 
       ```ruby
       proxy = URI.parse(Chef::Config[:http_proxy])
@@ -115,14 +116,42 @@ class Chef
       end
       ```
 
-      Note: Be careful when using the :delete_key action with the recursive attribute. This will delete the registry key, all of its values and all of the names, types, and data associated with them. This cannot be undone by Chef Infra Client.
+      Note: Be careful when using the :delete_key action with the recursive attribute. This will delete the registry key, all of its values and all of the names, types, and data associated with them. This cannot be undone by #{ChefUtils::Dist::Infra::PRODUCT}.
       DOC
 
-      state_attrs :values
-
       default_action :create
       allowed_actions :create, :create_if_missing, :delete, :delete_key
 
+      VALID_VALUE_HASH_KEYS = %i{name type data}.freeze
+
+      property :key, String, name_property: true
+      property :values, [Hash, Array],
+        default: [],
+        coerce: proc { |v|
+          @unscrubbed_values =
+            case v
+            when Hash
+              [ Mash.new(v).symbolize_keys ]
+            when Array
+              v.map { |value| Mash.new(value).symbolize_keys }
+            else
+              raise ArgumentError, "Bad type for RegistryKey resource, use Hash or Array"
+            end
+          scrub_values(@unscrubbed_values)
+        },
+        callbacks: {
+        "Missing name key in RegistryKey values hash" => lambda { |v| v.all? { |value| value.key?(:name) } },
+        "Bad key in RegistryKey values hash. Should be one of: #{VALID_VALUE_HASH_KEYS}" => lambda do |v|
+          v.all? do |value|
+            value.keys.all? { |key| VALID_VALUE_HASH_KEYS.include?(key) }
+          end
+        end,
+        "Type of name should be a string" => lambda { |v| v.all? { |value| value[:name].is_a?(String) } },
+        "Type of type should be a symbol" => lambda { |v| v.all? { |value| value[:type] ? value[:type].is_a?(Symbol) : true } },
+      }
+      property :recursive, [TrueClass, FalseClass], default: false
+      property :architecture, Symbol, default: :machine, equal_to: %i{machine x86_64 i386}
+
       # Some registry key data types may not be safely reported as json.
       # Example (CHEF-5323):
       #
@@ -152,51 +181,10 @@ class Chef
       # may want to extend the state_attrs API with the ability to rename POST'd attrs.
       #
       # See lib/chef/resource_reporter.rb for more information.
-      attr_reader :unscrubbed_values
-
-      def initialize(name, run_context = nil)
-        super
-        @values, @unscrubbed_values = [], []
-      end
-
-      property :key, String, name_property: true
-
-      VALID_VALUE_HASH_KEYS = %i{name type data}.freeze
-
-      def values(arg = nil)
-        if not arg.nil?
-          if arg.is_a?(Hash)
-            @values = [ Mash.new(arg).symbolize_keys ]
-          elsif arg.is_a?(Array)
-            @values = []
-            arg.each do |value|
-              @values << Mash.new(value).symbolize_keys
-            end
-          else
-            raise ArgumentError, "Bad type for RegistryKey resource, use Hash or Array"
-          end
-
-          @values.each do |v|
-            raise ArgumentError, "Missing name key in RegistryKey values hash" unless v.key?(:name)
-
-            v.each_key do |key|
-              raise ArgumentError, "Bad key #{key} in RegistryKey values hash" unless VALID_VALUE_HASH_KEYS.include?(key)
-            end
-            raise ArgumentError, "Type of name => #{v[:name]} should be string" unless v[:name].is_a?(String)
-
-            if v[:type]
-              raise ArgumentError, "Type of type => #{v[:type]} should be symbol" unless v[:type].is_a?(Symbol)
-            end
-          end
-          @unscrubbed_values = @values
-        elsif instance_variable_defined?(:@values)
-          scrub_values(@values)
-        end
+      def unscrubbed_values
+        @unscrubbed_values ||= []
       end
 
-      property :recursive, [TrueClass, FalseClass], default: false
-      property :architecture, Symbol, default: :machine, equal_to: %i{machine x86_64 i386}
-
       private
 
       def scrub_values(values)

data/lib/chef/resource/remote_file.rb

@@ -34,6 +34,78 @@ class Chef
 
       description "Use the **remote_file** resource to transfer a file from a remote location using file specificity. This resource is similar to the **file** resource. Note: Fetching files from the `files/` directory in a cookbook should be done with the **cookbook_file** resource."
 
+      examples <<~'DOC'
+      **Download a file without checking the checksum**:
+
+      ```ruby
+        remote_file '/tmp/remote.txt' do
+          source 'https://example.org/remote.txt'
+        end
+      ```
+
+      **Download a file with a checksum to validate**:
+
+      ```ruby
+        remote_file '/tmp/test_file' do
+          source 'http://www.example.com/tempfiles/test_file'
+          mode '0755'
+          checksum '3a7dac00b1' # A SHA256 (or portion thereof) of the file.
+        end
+      ```
+
+      **Download a file only if it's not already present**:
+
+      ```ruby
+        remote_file '/tmp/remote.txt' do
+          source 'https://example.org/remote.txt'
+          checksum '3a7dac00b1' # A SHA256 (or portion thereof) of the file.
+          action :create_if_missing
+        end
+      ```
+
+      **Using HTTP Basic Authentication in Headers**:
+
+      ```ruby
+        remote_file '/tmp/remote.txt' do
+          source 'https://example.org/remote.txt'
+          headers('Authorization' => "Basic #{Base64.encode64("USERNAME_VALUE:PASSWORD_VALUE").delete("\n")}")
+          checksum '3a7dac00b1' # A SHA256 (or portion thereof) of the file.
+          action :create_if_missing
+        end
+      ```
+
+      **Downloading a file to the Chef file cache dir for execution**:
+
+      ```ruby
+        remote_file '#{Chef::Config['file_cache_path']}/install.sh' do
+          source 'https://example.org/install.sh'
+          action :create_if_missing
+        end
+
+        execute '#{Chef::Config['file_cache_path']}/install.sh'
+      ```
+
+      **Specify advanced HTTP connection options including Net::HTTP (nethttp) options:**
+
+      ```ruby
+        remote_file '/tmp/remote.txt' do
+          source 'https://example.org/remote.txt'
+          http_options({
+            http_retry_delay: 0,
+            http_retry_count: 0,
+            keepalives: false,
+            nethttp: {
+              continue_timeout: 5,
+              max_retries: 5,
+              read_timeout: 5,
+              write_timeout: 5,
+              ssl_timeout: 5,
+            },
+          })
+        end
+      ```
+      DOC
+
       def initialize(name, run_context = nil)
         super
         @source = []
@@ -96,9 +168,29 @@ class Chef
         description: "Whether #{ChefUtils::Dist::Infra::PRODUCT} uses active or passive FTP. Set to `true` to use active FTP."
 
       property :headers, Hash, default: {},
-        description: "A Hash of custom HTTP headers."
+        description: <<~'DOCS'
+        A Hash of custom headers. For example:
+
+        ```ruby
+        headers({ "Cookie" => "user=some_user; pass=p@ssw0rd!" })
+        ```
 
-      property :show_progress, [ TrueClass, FalseClass ], default: false
+        or:
+
+        ```ruby
+        headers({ "Referer" => "#{header}" })
+        ```
+
+        or:
+
+        ```ruby
+        headers( "Authorization"=>"Basic #{ Base64.encode64("#{username}:#{password}").gsub("\n", "") }" )
+        ```
+        DOCS
+
+      property :show_progress, [ TrueClass, FalseClass ],
+        description: "Displays the progress of the file download.",
+        default: false
 
       property :ssl_verify_mode, Symbol, equal_to: %i{verify_none verify_peer},
         introduced: "16.2",
@@ -118,6 +210,10 @@ class Chef
 
       property :authentication, Symbol, equal_to: %i{remote local}, default: :remote
 
+      property :http_options, Hash, default: {},
+        introduced: "17.5",
+        description: "A Hash of custom HTTP options. For example: `http_options({ http_retry_count: 0, http_retry_delay: 2 })`"
+
       def after_created
         validate_identity_platform(remote_user, remote_password, remote_domain)
         identity = qualify_user(remote_user, remote_password, remote_domain)

data/lib/chef/resource/timezone.rb

@@ -38,7 +38,7 @@ class Chef
       **Set the timezone to America/Los_Angeles with a friendly resource name on Linux/macOS**
 
       ```ruby
-      timezone 'Set the host's timezone to America/Los_Angeles' do
+      timezone "Set the host's timezone to America/Los_Angeles" do
         timezone 'America/Los_Angeles'
       end
       ```
@@ -46,7 +46,7 @@ class Chef
       **Set the timezone to PST with a friendly resource name on Windows**
 
       ```ruby
-      timezone 'Set the host's timezone to PST' do
+      timezone "Set the host's timezone to PST" do
         timezone 'Pacific Standard time'
       end
       ```

data/lib/chef/resource/user_ulimit.rb

@@ -83,6 +83,7 @@ class Chef
           source ::File.expand_path("support/ulimit.erb", __dir__)
           local true
           mode "0644"
+          sensitive new_resource.sensitive
           variables(
             ulimit_user: new_resource.username,
             filehandle_limit: new_resource.filehandle_limit,