chef 17.3.48 → 17.6.15

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 = []
@@ -85,7 +157,7 @@ class Chef
       end
 
       property :use_etag, [ TrueClass, FalseClass ], default: true,
-        description: "Enable ETag headers. Set to false to disable ETag headers. To use this setting, `use_conditional_get` must also be set to true."
+        description: "Enable ETag headers. Set to `false` to disable ETag headers. To use this setting, `use_conditional_get` must also be set to true."
 
       alias :use_etags :use_etag
 
@@ -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/rhsm_subscription.rb

@@ -32,11 +32,11 @@ class Chef
         name_property: true
 
       action :attach, description: "Attach the node to a subscription pool." do
-        execute "Attach subscription pool #{new_resource.pool_id}" do
-          command "subscription-manager attach --pool=#{new_resource.pool_id}"
-          default_env true
-          action :run
-          not_if { subscription_attached?(new_resource.pool_id) }
+        unless subscription_attached?(new_resource.pool_id)
+          converge_by("attach subscription pool #{new_resource.pool_id}") do
+            shell_out!("subscription-manager attach --pool=#{new_resource.pool_id}")
+            build_resource(:package, "rhsm_subscription-#{new_resource.pool_id}-flush_cache").run_action(:flush_cache)
+          end
         end
       end
 

data/lib/chef/resource/ruby_block.rb

@@ -29,6 +29,106 @@ class Chef
       provides :ruby_block, target_mode: true
 
       description "Use the **ruby_block** resource to execute Ruby code during a #{ChefUtils::Dist::Infra::PRODUCT} run. Ruby code in the `ruby_block` resource is evaluated with other resources during convergence, whereas Ruby code outside of a `ruby_block` resource is evaluated before other resources, as the recipe is compiled."
+      examples <<~'DOC'
+        **Reload Chef Infra Client configuration data**
+
+        ```ruby
+        ruby_block 'reload_client_config' do
+          block do
+            Chef::Config.from_file('/etc/chef/client.rb')
+          end
+          action :run
+        end
+        ```
+
+        **Run a block on a particular platform**
+
+        The following example shows how an if statement can be used with the `windows?` method in the Chef Infra Language to run code specific to Microsoft Windows. The code is defined using the ruby_block resource:
+
+        ```ruby
+        if windows?
+          ruby_block 'copy libmysql.dll into ruby path' do
+            block do
+              require 'fileutils'
+              FileUtils.cp "#{node['mysql']['client']['lib_dir']}\\libmysql.dll",
+                node['mysql']['client']['ruby_dir']
+            end
+            not_if { ::File.exist?("#{node['mysql']['client']['ruby_dir']}\\libmysql.dll") }
+          end
+        end
+        ```
+
+        **Stash a file in a data bag**
+
+        The following example shows how to use the ruby_block resource to stash a BitTorrent file in a data bag so that it can be distributed to nodes in the organization.
+
+        ```ruby
+        ruby_block 'share the torrent file' do
+          block do
+            f = File.open(node['bittorrent']['torrent'],'rb')
+            #read the .torrent file and base64 encode it
+            enc = Base64.encode64(f.read)
+            data = {
+              'id'=>bittorrent_item_id(node['bittorrent']['file']),
+              'seed'=>node.ipaddress,
+              'torrent'=>enc
+            }
+            item = Chef::DataBagItem.new
+            item.data_bag('bittorrent')
+            item.raw_data = data
+            item.save
+          end
+          action :nothing
+          subscribes :create, "bittorrent_torrent[#{node['bittorrent']['torrent']}]", :immediately
+        end
+        ```
+
+        **Update the /etc/hosts file**
+
+        The following example shows how the ruby_block resource can be used to update the /etc/hosts file:
+
+        ```ruby
+        ruby_block 'edit etc hosts' do
+          block do
+            rc = Chef::Util::FileEdit.new('/etc/hosts')
+            rc.search_file_replace_line(/^127\.0\.0\.1 localhost$/,
+              '127.0.0.1 #{new_fqdn} #{new_hostname} localhost')
+            rc.write_file
+          end
+        end
+        ```
+
+        **Set environment variables**
+
+        The following example shows how to use variables within a Ruby block to set environment variables using rbenv.
+
+        ```ruby
+        node.override[:rbenv][:root] = rbenv_root
+        node.override[:ruby_build][:bin_path] = rbenv_binary_path
+
+        ruby_block 'initialize' do
+          block do
+            ENV['RBENV_ROOT'] = node[:rbenv][:root]
+            ENV['PATH'] = "#{node[:rbenv][:root]}/bin:#{node[:ruby_build][:bin_path]}:#{ENV['PATH']}"
+          end
+        end
+        ```
+
+        **Call methods in a gem**
+
+        The following example shows how to call methods in gems not shipped in Chef Infra Client
+
+        ```ruby
+        chef_gem 'mongodb'
+
+        ruby_block 'config_replicaset' do
+          block do
+            MongoDB.configure_replicaset(node, replicaset_name, rs_nodes)
+          end
+          action :run
+        end
+        ```
+      DOC
 
       default_action :run
       allowed_actions :create, :run

data/lib/chef/resource/scm/subversion.rb

@@ -28,7 +28,7 @@ class Chef
 
       provides :subversion
 
-      description "Use the **subversion** resource to manage source control resources that exist in a Subversion repository."
+      description "Use the **subversion** resource to manage source control resources that exist in a Subversion repository. Warning: The subversion resource has known bugs and may not work as expected. For more information see Chef GitHub issues, particularly [#4050](https://github.com/chef/chef/issues/4050) and [#4257](https://github.com/chef/chef/issues/4257)."
       examples <<~DOC
       **Get the latest version of an application**
 

data/lib/chef/resource/sysctl.rb

@@ -131,7 +131,7 @@ class Chef
 
       end
 
-      action :apply, description: "Apply a sysctl value." do
+      action :apply, description: "Set the kernel parameter and update the `sysctl` settings." do
         converge_if_changed do
           # set it temporarily
           set_sysctl_param(new_resource.key, new_resource.value)
@@ -150,7 +150,7 @@ class Chef
         end
       end
 
-      action :remove, description: "Remove a sysctl value." do
+      action :remove, description: "Remove the kernel parameter and update the `sysctl` settings." do
         # only converge the resource if the file actually exists to delete
         if ::File.exist?("#{new_resource.conf_dir}/99-chef-#{new_resource.key.tr("/", ".")}.conf")
           converge_by "removing sysctl config at #{new_resource.conf_dir}/99-chef-#{new_resource.key.tr("/", ".")}.conf" do

data/lib/chef/resource/systemd_unit.rb

@@ -34,7 +34,7 @@ class Chef
 
       ```ruby
       systemd_unit 'etcd.service' do
-        content(Unit: {
+        content({ Unit: {
                   Description: 'Etcd',
                   Documentation: ['https://coreos.com/etcd', 'man:etcd(1)'],
                   After: 'network.target',
@@ -46,7 +46,7 @@ class Chef
                 },
                 Install: {
                   WantedBy: 'multi-user.target',
-                })
+                } })
         action [:create, :enable]
       end
       ```
@@ -113,7 +113,7 @@ class Chef
         when Hash
           IniParse.gen do |doc|
             content.each_pair do |sect, opts|
-              doc.section(sect) do |section|
+              doc.section(sect, { option_sep: "=" }) do |section|
                 opts.each_pair do |opt, val|
                   [val].flatten.each do |v|
                     section.option(opt, v)

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,

data/lib/chef/resource/windows_printer.rb

@@ -33,7 +33,7 @@ class Chef
 
       provides(:windows_printer) { true }
 
-      description "Use the **windows_printer** resource to setup Windows printers. This resource will automatically install the driver specified in the `driver_name` property and will automatically create a printer port using either the `ipv4_address` property or the `port_name property."
+      description "Use the **windows_printer** resource to setup Windows printers. This resource will automatically install the driver specified in the `driver_name` property and will automatically create a printer port using either the `ipv4_address` property or the `port_name` property."
       introduced "14.0"
       examples <<~DOC
       **Create a printer**:

data/lib/chef/resource/windows_uac.rb

@@ -104,7 +104,9 @@ class Chef
         #
         # @return [Integer]
         def consent_behavior_users_symbol_to_reg(sym)
-          %i{auto_deny secure_prompt_for_creds prompt_for_creds}.index(sym)
+          # Since 2 isn't a valid value for ConsentPromptBehaviorUser, assign the value at index as nil.
+          # https://docs.microsoft.com/en-us/windows/security/identity-protection/user-account-control/user-account-control-group-policy-and-registry-key-settings#registry-key-settings
+          [:auto_deny, :secure_prompt_for_creds, nil, :prompt_for_creds].index(sym)
         end
       end
     end

data/lib/chef/resource/windows_user_privilege.rb

@@ -139,7 +139,7 @@ class Chef
         coerce: proc { |v| Array(v) },
         callbacks: {
           "Privilege property restricted to the following values: #{PRIVILEGE_OPTS}" => lambda { |n| (n - PRIVILEGE_OPTS).empty? },
-        }
+        }, identity: true
 
       load_current_value do |new_resource|
         if new_resource.principal && (new_resource.action.include?(:add) || new_resource.action.include?(:remove))

data/lib/chef/resource/yum_package.rb

@@ -27,11 +27,7 @@ class Chef
       provides :yum_package
       provides :package, platform_family: "fedora_derived"
 
-      description "Use the **yum_package** resource to install, upgrade, and remove packages with Yum"\
-                  " for the Red Hat and CentOS platforms. The yum_package resource is able to resolve"\
-                  " `provides` data for packages much like Yum can do when it is run from the command line."\
-                  " This allows a variety of options for installing packages, like minimum versions,"\
-                  " virtual provides, and library names."
+      description "Use the **yum_package** resource to install, upgrade, and remove packages with Yum for the Red Hat and CentOS platforms. The yum_package resource is able to resolve `provides` data for packages much like Yum can do when it is run from the command line. This allows a variety of options for installing packages, like minimum versions, virtual provides, and library names. Note: Support for using file names to install packages (as in `yum_package '/bin/sh'`) is not available because the volume of data required to parse for this is excessive."
       examples <<~DOC
         **Install an exact version**:
 

data/lib/chef/resource.rb

@@ -1063,7 +1063,8 @@ class Chef
     # action for the resource.
     #
     # @param name [Symbol] The action name to define.
-    # @param description [String] optional description for the action
+    # @param description [String] optional description for the action. Used for
+    #   documentation generation.
     # @param recipe_block The recipe to run when the action is taken. This block
     #   takes no parameters, and will be evaluated in a new context containing:
     #
@@ -1076,11 +1077,8 @@ class Chef
     def self.action(action, description: nil, &recipe_block)
       action = action.to_sym
       declare_action_class
-      action_class.action(action, &recipe_block)
+      action_class.action(action, description: description, &recipe_block)
       self.allowed_actions += [ action ]
-      # Accept any non-nil description, which will correctly override
-      # any specific inherited description.
-      action_descriptions[action] = description unless description.nil?
       default_action action if Array(default_action) == [:nothing]
     end
 
@@ -1090,18 +1088,15 @@ class Chef
     # @param action [Symbol,String] the action name
     # @return the description of the action provided, or nil if no description
     # was defined
-    def self.action_description(action)
-      action_descriptions[action.to_sym]
-    end
-
-    # @api private
-    #
-    # @return existing action description hash, or newly-initialized
-    # hash containing action descriptions inherited from parent Resource,
-    # if any.
-    def self.action_descriptions
-      @action_descriptions ||=
-        superclass.respond_to?(:action_descriptions) ? superclass.action_descriptions.dup : { nothing: nil }
+    def action_description(action)
+      provider_for_action(action).class.action_description(action)
+    rescue Chef::Exceptions::ProviderNotFound
+      # If a provider can't be found, there can be no description defined on the provider.
+      nil
+    rescue NameError => e
+      # This can happen when attempting to load a provider in a platform-specific
+      # environment where we have not required the necessary files yet
+      raise unless e.message =~ /uninitialized constant/
     end
 
     # Define a method to load up this resource's properties with the current
@@ -1191,6 +1186,7 @@ class Chef
             if superclass.custom_resource?
               superclass.action_class
             else
+
               ActionClass
             end
 

data/lib/chef/resource_inspector.rb

@@ -23,6 +23,11 @@ require_relative "node"
 require_relative "resources"
 require_relative "json_compat"
 
+# We need to require providers  so that we can resolve
+# action documentation that may have been defined on the providers
+# instead of the resources.
+require_relative "providers"
+
 class Chef
   module ResourceInspector
     def self.get_default(default)
@@ -39,11 +44,10 @@ class Chef
     def self.extract_resource(resource, complete = false)
       data = {}
       data[:description] = resource.description
-      # data[:deprecated] = resource.deprecated || false
       data[:default_action] = resource.default_action
       data[:actions] = {}
       resource.allowed_actions.each do |action|
-        data[:actions][action] = resource.action_description(action)
+        data[:actions][action] = resource.new(resource.to_s, nil).action_description(action)
       end
 
       data[:examples] = resource.examples

data/lib/chef/resources.rb

@@ -73,6 +73,8 @@ require_relative "resource/homebrew_package"
 require_relative "resource/homebrew_tap"
 require_relative "resource/homebrew_update"
 require_relative "resource/ifconfig"
+require_relative "resource/inspec_input"
+require_relative "resource/inspec_waiver"
 require_relative "resource/inspec_waiver_file_entry"
 require_relative "resource/kernel_module"
 require_relative "resource/ksh"