chef 16.0.257-universal-mingw32 → 16.2.44-universal-mingw32

data/lib/chef/resource/archive_file.rb

@@ -19,6 +19,7 @@
 #
 
 require_relative "../resource"
+require "fileutils" unless defined?(FileUtils)
 
 class Chef
   class Resource
@@ -29,15 +30,28 @@ class Chef
       provides :libarchive_file # legacy cookbook name
 
       introduced "15.0"
-      description "Use the archive_file resource to extract archive files to disk. This resource uses the libarchive library to extract multiple archive formats including tar, gzip, bzip, and zip formats."
+      description "Use the **archive_file** resource to extract archive files to disk. This resource uses the libarchive library to extract multiple archive formats including tar, gzip, bzip, and zip formats."
       examples <<~DOC
-        Extract a zip file to a specified directory
+        **Extract a zip file to a specified directory**:
+
         ```ruby
         archive_file 'Precompiled.zip' do
           path '/tmp/Precompiled.zip'
           destination '/srv/files'
         end
         ```
+
+        **Set specific permissions on the extracted files**:
+
+        ```ruby
+        archive_file 'Precompiled.zip' do
+          owner 'tsmith'
+          group 'staff'
+          mode '700'
+          path '/tmp/Precompiled.zip'
+          destination '/srv/files'
+        end
+        ```
       DOC
 
       property :path, String,
@@ -52,7 +66,7 @@ class Chef
         description: "The group of the extracted files."
 
       property :mode, [String, Integer],
-        description: "The mode of the extracted files.",
+        description: "The mode of the extracted files. Integer values are deprecated as octal values (ex. 0755) would not be interpreted correctly.",
         default: "755"
 
       property :destination, String,
@@ -60,22 +74,22 @@ class Chef
         required: true
 
       property :options, [Array, Symbol],
-        description: "An array of symbols representing extraction flags. Example: :no_overwrite to prevent overwriting files on disk. By default, this properly sets :time which preserves the modification timestamps of files in the archive when writing them to disk.",
+        description: "An array of symbols representing extraction flags. Example: `:no_overwrite` to prevent overwriting files on disk. By default, this properly sets `:time` which preserves the modification timestamps of files in the archive when writing them to disk.",
         default: lazy { [:time] }
 
       property :overwrite, [TrueClass, FalseClass, :auto],
-        description: "Should the resource overwrite the destination file contents if they already exist? If set to :auto the date stamp of files within the archive will be compared to those on disk and disk contents will be overwritten if they differ. This may cause unintended consequences if disk date stamps are changed between runs, which will result in the files being overwritten during each client run. Make sure to properly test any change to this property.",
+        description: "Should the resource overwrite the destination file contents if they already exist? If set to `:auto` the date stamp of files within the archive will be compared to those on disk and disk contents will be overwritten if they differ. This may cause unintended consequences if disk date stamps are changed between runs, which will result in the files being overwritten during each client run. Make sure to properly test any change to this property.",
         default: false
 
       # backwards compatibility for the legacy cookbook names
       alias_method :extract_options, :options
       alias_method :extract_to, :destination
 
-      require "fileutils" unless defined?(FileUtils)
-
       action :extract do
         description "Extract and archive file."
 
+        require_libarchive
+
         unless ::File.exist?(new_resource.path)
           raise Errno::ENOENT, "No archive found at #{new_resource.path}! Cannot continue."
         end
@@ -84,7 +98,8 @@ class Chef
           Chef::Log.trace("File or directory does not exist at destination path: #{new_resource.destination}")
 
           converge_by("create directory #{new_resource.destination}") do
-            FileUtils.mkdir_p(new_resource.destination, mode: new_resource.mode.to_i)
+            # @todo when we remove the ability for mode to be an int we can remove the .to_s below
+            FileUtils.mkdir_p(new_resource.destination, mode: new_resource.mode.to_s.to_i(8))
           end
 
           extract(new_resource.path, new_resource.destination, Array(new_resource.options))
@@ -112,6 +127,16 @@ class Chef
       end
 
       action_class do
+        def require_libarchive
+          require "ffi-libarchive"
+        end
+
+        def define_resource_requirements
+          if new_resource.mode.is_a?(Integer)
+            Chef.deprecated(:archive_file_integer_file_mode, "The mode property should be passed to archive_file resources as a String and not an Integer to ensure the value is properly interpreted.")
+          end
+        end
+
         # This can't be a constant since we might not have required 'ffi-libarchive' yet.
         def extract_option_map
           {
@@ -135,8 +160,6 @@ class Chef
         #
         # @return [Boolean]
         def archive_differs_from_disk?(src, dest)
-          require "ffi-libarchive"
-
           modified = false
           Dir.chdir(dest) do
             archive = Archive::Reader.open_filename(src)
@@ -163,8 +186,6 @@ class Chef
         #
         # @return [void]
         def extract(src, dest, options = [])
-          require "ffi-libarchive"
-
           converge_by("extract #{src} to #{dest}") do
             flags = [options].flatten.map { |option| extract_option_map[option] }.compact.reduce(:|)
 

data/lib/chef/resource/bash.rb

@@ -17,7 +17,6 @@
 #
 
 require_relative "script"
-require_relative "../provider/script"
 
 class Chef
   class Resource
@@ -26,7 +25,7 @@ class Chef
 
       provides :bash
 
-      description "Use the bash resource to execute scripts using the Bash interpreter. This resource may also use any of the actions and properties that are available to the execute resource. Commands that are executed with this resource are (by their nature) not idempotent, as they are typically unique to the environment in which they are run. Use not_if and only_if to guard this resource for idempotence."
+      description "Use the **bash** resource to execute scripts using the Bash interpreter. This resource may also use any of the actions and properties that are available to the execute resource. Commands that are executed with this resource are (by their nature) not idempotent, as they are typically unique to the environment in which they are run. Use not_if and only_if to guard this resource for idempotence."
 
       def initialize(name, run_context = nil)
         super

data/lib/chef/resource/batch.rb

@@ -25,10 +25,12 @@ class Chef
 
       provides :batch
 
-      description "Use the batch resource to execute a batch script using the cmd.exe interpreter on Windows. The batch resource creates and executes a temporary file (similar to how the script resource behaves), rather than running the command inline. Commands that are executed with this resource are (by their nature) not idempotent, as they are typically unique to the environment in which they are run. Use not_if and only_if to guard this resource for idempotence."
+      description "Use the **batch** resource to execute a batch script using the cmd.exe interpreter on Windows. The batch resource creates and executes a temporary file (similar to how the script resource behaves), rather than running the command inline. Commands that are executed with this resource are (by their nature) not idempotent, as they are typically unique to the environment in which they are run. Use not_if and only_if to guard this resource for idempotence."
 
-      def initialize(name, run_context = nil)
-        super(name, run_context, nil, "cmd.exe")
+      def initialize(*args)
+        super
+        @interpreter = "cmd.exe"
+        @default_guard_interpreter = resource_name
       end
 
     end

data/lib/chef/resource/bff_package.rb

@@ -25,7 +25,7 @@ class Chef
 
       provides :bff_package
 
-      description "Use the bff_package resource to manage packages for the AIX platform using the installp utility. When a package is installed from a local file, it must be added to the node using the remote_file or cookbook_file resources."
+      description "Use the **bff_package** resource to manage packages for the AIX platform using the installp utility. When a package is installed from a local file, it must be added to the node using the **remote_file** or **cookbook_file** resources."
       introduced "12.0"
 
       property :package_name, String,

data/lib/chef/resource/breakpoint.rb

@@ -26,7 +26,7 @@ class Chef
 
       provides :breakpoint, target_mode: true
 
-      description "Use the breakpoint resource to add breakpoints to recipes. Run the #{Chef::Dist::SHELL} in #{Chef::Dist::PRODUCT} mode, and then use those breakpoints to debug recipes. Breakpoints are ignored by the #{Chef::Dist::CLIENT} during an actual #{Chef::Dist::CLIENT} run. That said, breakpoints are typically used to debug recipes only when running them in a non-production environment, after which they are removed from those recipes before the parent cookbook is uploaded to the Chef server."
+      description "Use the **breakpoint** resource to add breakpoints to recipes. Run the #{Chef::Dist::SHELL} in #{Chef::Dist::PRODUCT} mode, and then use those breakpoints to debug recipes. Breakpoints are ignored by the #{Chef::Dist::CLIENT} during an actual #{Chef::Dist::CLIENT} run. That said, breakpoints are typically used to debug recipes only when running them in a non-production environment, after which they are removed from those recipes before the parent cookbook is uploaded to the Chef server."
       introduced "12.0"
 
       default_action :break

data/lib/chef/resource/build_essential.rb

@@ -24,22 +24,25 @@ class Chef
 
       provides(:build_essential) { true }
 
-      description "Use the build_essential resource to install the packages required for compiling C software from source."
+      description "Use the **build_essential** resource to install the packages required for compiling C software from source."
       introduced "14.0"
       examples <<~DOC
-        Install compilation packages
+        **Install compilation packages**:
+
         ```ruby
         build_essential
         ```
 
-        Install compilation packages during the compilation phase
+        **Install compilation packages during the compilation phase**:
+
         ```ruby
         build_essential 'Install compilation tools' do
           compile_time true
         end
         ```
 
-        Upgrade compilation packages on macOS systems
+        **Upgrade compilation packages on macOS systems**:
+
         ```ruby
         build_essential 'Install compilation tools' do
           action :upgrade
@@ -52,6 +55,7 @@ class Chef
 
       property :raise_if_unsupported, [TrueClass, FalseClass],
         description: "Raise a hard error on platforms where this resource is unsupported.",
+        introduced: "15.5",
         default: false, desired_state: false # FIXME: make this default to true
 
       action :install do

data/lib/chef/resource/cab_package.rb

@@ -27,7 +27,7 @@ class Chef
 
       provides :cab_package
 
-      description "Use the cab_package resource to install or remove Microsoft Windows cabinet (.cab) packages."
+      description "Use the **cab_package** resource to install or remove Microsoft Windows cabinet (.cab) packages."
       introduced "12.15"
 
       allowed_actions :install, :remove

data/lib/chef/resource/chef_client_cron.rb

@@ -26,23 +26,26 @@ class Chef
 
       provides :chef_client_cron
 
-      description "Use the chef_client_cron resource to setup the #{Chef::Dist::PRODUCT} to run as a cron job. This resource will also create the specified log directory if it doesn't already exist."
+      description "Use the **chef_client_cron** resource to setup the #{Chef::Dist::PRODUCT} to run as a cron job. This resource will also create the specified log directory if it doesn't already exist."
       introduced "16.0"
       examples <<~DOC
-      Setup #{Chef::Dist::PRODUCT} to run using the default 30 minute cadence
+      **Setup #{Chef::Dist::PRODUCT} to run using the default 30 minute cadence**:
+
       ```ruby
-      chef_client_cron "Run chef-client as a cron job"
+      chef_client_cron "Run #{Chef::Dist::PRODUCT} as a cron job"
       ```
 
-      Run #{Chef::Dist::PRODUCT} twice a day
+      **Run #{Chef::Dist::PRODUCT} twice a day**:
+
       ```ruby
-      chef_client_cron "Run chef-client every 12 hours" do
+      chef_client_cron "Run #{Chef::Dist::PRODUCT} every 12 hours" do
         minute 0
         hour "0,12"
       end
       ```
 
-      Run #{Chef::Dist::PRODUCT} with extra options passed to the client
+      **Run #{Chef::Dist::PRODUCT} with extra options passed to the client**:
+
       ```ruby
       chef_client_cron "Run an override recipe" do
         daemon_options ["--override-runlist mycorp_base::default"]
@@ -133,14 +136,14 @@ class Chef
 
       property :environment, Hash,
         default: lazy { {} },
-        description: "A Hash containing additional arbitrary environment variables under which the cron job will be run in the form of ``({'ENV_VARIABLE' => 'VALUE'})``."
+        description: "A Hash containing additional arbitrary environment variables under which the cron job will be run in the form of `({'ENV_VARIABLE' => 'VALUE'})`."
 
       action :add do
         # TODO: Replace this with a :create_if_missing action on directory when that exists
         unless ::Dir.exist?(new_resource.log_directory)
           directory new_resource.log_directory do
             owner new_resource.user
-            mode "0640"
+            mode "0750"
             recursive true
           end
         end
@@ -160,7 +163,7 @@ class Chef
       end
 
       action :remove do
-        cron_d new_resource.job_name do
+        declare_resource(cron_resource_type, new_resource.job_name) do
           action :delete
         end
       end

data/lib/chef/resource/chef_client_scheduled_task.rb

@@ -24,27 +24,40 @@ class Chef
 
       provides :chef_client_scheduled_task
 
-      description "Use the chef_client_cron resource to setup the #{Chef::Dist::PRODUCT} to run as a Windows scheduled task. This resource will also create the specified log directory if it doesn't already exist."
+      description "Use the **chef_client_scheduled_task** resource to setup the #{Chef::Dist::PRODUCT} to run as a Windows scheduled task. This resource will also create the specified log directory if it doesn't already exist."
       introduced "16.0"
       examples <<~DOC
-      Setup #{Chef::Dist::PRODUCT} to run using the default 30 minute cadence
+      **Setup #{Chef::Dist::PRODUCT} to run using the default 30 minute cadence**:
+
       ```ruby
-        chef_client_scheduled_task "Run chef-client as a scheduled task"
+        chef_client_scheduled_task "Run #{Chef::Dist::PRODUCT} as a scheduled task"
       ```
 
-      Run #{Chef::Dist::PRODUCT} on system start
+      **Run #{Chef::Dist::PRODUCT} on system start**:
+
       ```ruby
-        chef_client_scheduled_task 'Chef Client on start' do
+        chef_client_scheduled_task '#{Chef::Dist::PRODUCT} on start' do
           frequency 'onstart'
         end
       ```
 
-      Run #{Chef::Dist::PRODUCT} with extra options passed to the client
+      **Run #{Chef::Dist::PRODUCT} with extra options passed to the client**:
+
       ```ruby
         chef_client_scheduled_task "Run an override recipe" do
           daemon_options ["--override-runlist mycorp_base::default"]
         end
       ```
+
+      **Run #{Chef::Dist::PRODUCT} daily at 01:00 am, specifying a named run-list**:
+
+      ```ruby
+        chef_client_scheduled_task "Run chef-client named run-list daily" do
+          frequency 'daily'
+          start_time '01:00'
+          daemon_options ['-n audit_only']
+        end
+      ```
       DOC
 
       resource_name :chef_client_scheduled_task
@@ -69,7 +82,8 @@ class Chef
         coerce: proc { |x| Integer(x) },
         callbacks: { "should be a positive number" => proc { |v| v > 0 } },
         description: "Numeric value to go with the scheduled task frequency",
-        default: 30
+        default: lazy { frequency == "minute" ? 30 : 1 },
+        default_description: "30 if frequency is 'minute', 1 otherwise"
 
       property :accept_chef_license, [true, false],
         description: "Accept the Chef Online Master License and Services Agreement. See <https://www.chef.io/online-master-agreement/>",
@@ -126,6 +140,7 @@ class Chef
 
         # According to https://docs.microsoft.com/en-us/windows/desktop/taskschd/schtasks,
         # the :once, :onstart, :onlogon, and :onidle schedules don't accept schedule modifiers
+
         windows_task new_resource.task_name do
           run_level                      :highest
           command                        full_command

data/lib/chef/resource/chef_client_systemd_timer.rb

@@ -24,22 +24,25 @@ class Chef
 
       provides :chef_client_systemd_timer
 
-      description "Use the chef_client_systemd_timer resource to setup the #{Chef::Dist::PRODUCT} to run as a systemd timer."
+      description "Use the **chef_client_systemd_timer** resource to setup the #{Chef::Dist::PRODUCT} to run as a systemd timer."
       introduced "16.0"
       examples <<~DOC
-      Setup #{Chef::Dist::PRODUCT} to run using the default 30 minute cadence
+      **Setup #{Chef::Dist::PRODUCT} to run using the default 30 minute cadence**:
+
       ```ruby
-      chef_client_systemd_timer "Run chef-client as a systemd timer"
+      chef_client_systemd_timer "Run #{Chef::Dist::PRODUCT} as a systemd timer"
       ```
 
-      Run #{Chef::Dist::PRODUCT} every 1 hour
+      **Run #{Chef::Dist::PRODUCT} every 1 hour**:
+
       ```ruby
-      chef_client_systemd_timer "Run chef-client every 1 hour" do
+      chef_client_systemd_timer "Run #{Chef::Dist::PRODUCT} every 1 hour" do
         interval "1hr"
       end
       ```
 
-      Run #{Chef::Dist::PRODUCT} with extra options passed to the client
+      **Run #{Chef::Dist::PRODUCT} with extra options passed to the client**:
+
       ```ruby
       chef_client_systemd_timer "Run an override recipe" do
         daemon_options ["--override-runlist mycorp_base::default"]
@@ -92,7 +95,7 @@ class Chef
         default: lazy { [] }
 
       property :environment, Hash,
-        description: "A Hash containing additional arbitrary environment variables under which the systemd timer will be run in the form of ``({'ENV_VARIABLE' => 'VALUE'})``.",
+        description: "A Hash containing additional arbitrary environment variables under which the systemd timer will be run in the form of `({'ENV_VARIABLE' => 'VALUE'})`.",
         default: lazy { {} }
 
       action :add do

data/lib/chef/resource/chef_gem.rb

@@ -34,6 +34,10 @@ class Chef
     #    installed
     #  - Runs Gem.clear_paths after the action, ensuring that gem is aware of changes so that it can be required
     #    immediately after it is installed
+
+    require_relative "gem_package"
+    require_relative "../dist"
+
     class ChefGem < Chef::Resource::Package::GemPackage
       unified_mode true
       provides :chef_gem
@@ -45,8 +49,8 @@ class Chef
       property :version, String,
         description: "The version of a package to be installed or upgraded."
 
-      property :gem_binary, default: "#{RbConfig::CONFIG["bindir"]}/gem", default_description: "Chef's built-in gem binary.",
-                            description: "The path of a gem binary to use for the installation. By default, the same version of Ruby that is used by the #{Chef::Dist::CLIENT} will be installed.",
+      property :gem_binary, default: "#{RbConfig::CONFIG["bindir"]}/gem", default_description: "The `gem` binary included with #{Chef::Dist::PRODUCT}.",
+                            description: "The path of a gem binary to use for the installation. By default, the same version of Ruby that is used by #{Chef::Dist::PRODUCT} will be installed.",
                             callbacks: {
                  "The chef_gem resource is restricted to the current gem environment, use gem_package to install to other environments." => proc { |v| v == "#{RbConfig::CONFIG["bindir"]}/gem" },
                }

data/lib/chef/resource/chef_handler.rb

@@ -25,7 +25,7 @@ class Chef
 
       provides(:chef_handler) { true }
 
-      description "Use the chef_handler resource to install or uninstall reporting/exception handlers."
+      description "Use the **chef_handler** resource to install or uninstall reporting/exception handlers."
       introduced "14.0"
 
       property :class_name, String,
@@ -107,7 +107,7 @@ class Chef
           end
         end
 
-        # Walks down the namespace heirarchy to return the class object for the given class name.
+        # Walks down the namespace hierarchy to return the class object for the given class name.
         # If the class is not available, NameError is thrown.
         #
         # @param class_full_name [String] full class name such as 'Chef::Handler::Foo' or 'MyHandler'.
@@ -118,7 +118,7 @@ class Chef
           class_name = ancestors.pop
 
           # We need to search the ancestors only for the first/uppermost namespace of the class, so we
-          # need to enable the #const_get inherit paramenter only when we are searching in Kernel scope
+          # need to enable the #const_get inherit parameter only when we are searching in Kernel scope
           # (see COOK-4117).
           parent = ancestors.inject(Kernel) { |scope, const_name| scope.const_get(const_name, scope === Kernel) }
           child = parent.const_get(class_name, parent === Kernel)

data/lib/chef/resource/chef_sleep.rb

@@ -24,22 +24,25 @@ class Chef
 
       unified_mode true
 
-      description "Use the chef_sleep resource to set the number of seconds to sleep during a #{Chef::Dist::PRODUCT} run. Only use this resource when a command or service exits successfully but is not ready for the next step of the recipe."
+      description "Use the **chef_sleep** resource to pause (sleep) for a number of seconds during a #{Chef::Dist::PRODUCT} run. Only use this resource when a command or service exits successfully but is not ready for the next step in a recipe."
       introduced "15.5"
       examples <<~DOC
-        Sleep for 10 seconds
+        **Sleep for 10 seconds**:
+
         ```ruby
         chef_sleep '10'
         ```
 
-        Sleep for 10 seconds with a descriptive resource name for logging
+        **Sleep for 10 seconds with a descriptive resource name for logging**:
+
         ```ruby
         chef_sleep 'wait for the service to start' do
           seconds 10
         end
         ````
 
-        Use a notification from another resource to sleep only when necessary
+        **Use a notification from another resource to sleep only when necessary**:
+
         ```ruby
         service 'Service that is slow to start and reports as started' do
           service_name 'my_database'