chef 16.0.257 → 16.2.44

data/lib/chef/resource/perl.rb

@@ -17,7 +17,6 @@
 #
 
 require_relative "script"
-require_relative "../provider/script"
 
 class Chef
   class Resource
@@ -31,7 +30,7 @@ class Chef
         @interpreter = "perl"
       end
 
-      description "Use the perl resource to execute scripts using the Perl interpreter."\
+      description "Use the **perl** resource to execute scripts using the Perl 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"\

data/lib/chef/resource/plist.rb

@@ -26,16 +26,35 @@ class Chef
 
       provides :plist
 
-      description "Use the plist resource to set config values in plist files on macOS systems."
+      description "Use the **plist** resource to set config values in plist files on macOS systems."
       introduced "16.0"
+      examples <<~DOC
+        **Show hidden files in finder**:
+
+        ```ruby
+        plist 'show hidden files' do
+          path '/Users/vagrant/Library/Preferences/com.apple.finder.plist'
+          entry 'AppleShowAllFiles'
+          value true
+        end
+        ```
+      DOC
+
+      property :path, String, name_property: true,
+        description: "The path on disk to the plist file."
 
-      property :path, String, name_property: true
       property :entry, String
       property :value, [TrueClass, FalseClass, String, Integer, Float, Hash]
       property :encoding, String, default: "binary"
-      property :owner, String, default: "root"
-      property :group, String, default: "wheel"
-      property :mode, [String, Integer]
+
+      property :owner, String, default: "root",
+        description: "The owner of the plist file."
+
+      property :group, String, default: "wheel",
+        description: "The group of the plist file."
+
+      property :mode, [String, Integer],
+        description: "The file mode of the plist file. Ex: '644'"
 
       PLISTBUDDY_EXECUTABLE = "/usr/libexec/PlistBuddy".freeze
       DEFAULTS_EXECUTABLE = "/usr/bin/defaults".freeze

data/lib/chef/resource/portage_package.rb

@@ -25,7 +25,7 @@ class Chef
 
       provides :portage_package
 
-      description "Use the portage_package resource to manage packages for the Gentoo platform."
+      description "Use the **portage_package** resource to manage packages for the Gentoo platform."
 
       property :package_name, String,
         description: "An optional property to set the package name if it differs from the resource block's name.",

data/lib/chef/resource/powershell_package.rb

@@ -24,7 +24,7 @@ class Chef
 
       provides :powershell_package
 
-      description "Use the powershell_package resource to install and manage packages via the PowerShell Package Manager for the Microsoft Windows platform. The powershell_package resource requires administrative access, and a source must be configured in the PowerShell Package Manager via the powershell_package_source resource."
+      description "Use the **powershell_package** resource to install and manage packages via the PowerShell Package Manager for the Microsoft Windows platform. The powershell_package resource requires administrative access, and a source must be configured in the PowerShell Package Manager via the powershell_package_source resource."
       introduced "12.16"
 
       allowed_actions :install, :remove

data/lib/chef/resource/powershell_package_source.rb

@@ -25,7 +25,7 @@ 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 repository."
       introduced "14.3"
 
       property :source_name, String,

data/lib/chef/resource/powershell_script.rb

@@ -39,7 +39,7 @@ class Chef
           end
         }
 
-      description "Use the powershell_script resource to execute a script using the Windows PowerShell"\
+      description "Use the **powershell_script** resource to execute a script using the Windows PowerShell"\
                   " interpreter, much like how the script and script-based resources—bash, csh, perl, python,"\
                   " and ruby—are used. The powershell_script is specific to the Microsoft Windows platform"\
                   " and the Windows PowerShell interpreter.\n\n The powershell_script resource creates and"\
@@ -48,8 +48,10 @@ class Chef
                   " 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, :powershell_script, "powershell.exe")
+      def initialize(*args)
+        super
+        @interpreter = "powershell.exe"
+        @default_guard_interpreter = resource_name
         @convert_boolean_return = false
       end
 

data/lib/chef/resource/python.rb

@@ -16,7 +16,6 @@
 #
 
 require_relative "script"
-require_relative "../provider/script"
 
 class Chef
   class Resource
@@ -30,7 +29,7 @@ class Chef
         @interpreter = "python"
       end
 
-      description "Use the python resource to execute scripts using the Python interpreter."\
+      description "Use the **python** resource to execute scripts using the Python 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"\

data/lib/chef/resource/reboot.rb

@@ -26,7 +26,7 @@ class Chef
 
       provides :reboot
 
-      description "Use the reboot resource to reboot a node, a necessary step with some"\
+      description "Use the **reboot** resource to reboot a node, a necessary step with some"\
                   " installations on certain platforms. This resource is supported for use on"\
                   " the Microsoft Windows, macOS, and Linux platforms.\n"\
                   "In using this resource via notifications, it's important to *only* use"\

data/lib/chef/resource/registry_key.rb

@@ -26,7 +26,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."
       introduced "11.0"
 
       state_attrs :values

data/lib/chef/resource/remote_directory.rb

@@ -29,7 +29,7 @@ class Chef
 
       provides :remote_directory
 
-      description "Use the remote_directory resource to incrementally transfer a directory from a cookbook to a node. The director that is copied from the cookbook should be located under COOKBOOK_NAME/files/default/REMOTE_DIRECTORY. The remote_directory resource will obey file specificity."
+      description "Use the **remote_directory** resource to incrementally transfer a directory from a cookbook to a node. The director that is copied from the cookbook should be located under COOKBOOK_NAME/files/default/REMOTE_DIRECTORY. The remote_directory resource will obey file specificity."
 
       default_action :create
       allowed_actions :create, :create_if_missing, :delete

data/lib/chef/resource/remote_file.rb

@@ -22,6 +22,7 @@ require_relative "file"
 require_relative "../provider/remote_file"
 require_relative "../mixin/securable"
 require_relative "../mixin/uris"
+require_relative "../dist"
 
 class Chef
   class Resource
@@ -31,8 +32,7 @@ class Chef
 
       provides :remote_file
 
-      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."
+      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."
 
       def initialize(name, run_context = nil)
         super
@@ -73,7 +73,8 @@ class Chef
         end
       end
 
-      property :checksum, String
+      property :checksum, String,
+        description: "Optional, see `use_conditional_get`. 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."
 
       # Disable or enable ETag and Last Modified conditional GET. Equivalent to
       #   use_etag(true_or_false)
@@ -83,25 +84,39 @@ class Chef
         use_last_modified(true_or_false)
       end
 
-      property :use_etag, [ TrueClass, FalseClass ], default: true
+      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."
 
       alias :use_etags :use_etag
 
-      property :use_last_modified, [ TrueClass, FalseClass ], default: true
+      property :use_last_modified, [ TrueClass, FalseClass ], default: true,
+        description: "Enable `If-Modified-Since` headers. Set to `false` to disable `If-Modified-Since` headers. To use this setting, `use_conditional_get` must also be set to `true`."
 
-      property :ftp_active_mode, [ TrueClass, FalseClass ], default: false
+      property :ftp_active_mode, [ TrueClass, FalseClass ], default: false,
+        description: "Whether #{Chef::Dist::PRODUCT} uses active or passive FTP. Set to `true` to use active FTP."
 
-      property :headers, Hash, default: lazy { {} }
+      property :headers, Hash, default: lazy { {} },
+        description: "A Hash of custom HTTP headers."
 
       property :show_progress, [ TrueClass, FalseClass ], default: false
 
-      property :remote_user, String
+      property :ssl_verify_mode, Symbol, equal_to: %i{verify_none verify_peer},
+        introduced: "16.2",
+        description: "Optional property to override SSL policy. If not specified, uses the SSL policy from `config.rb`."
 
-      property :remote_domain, String
+      property :remote_user, String,
+        introduced: "13.4",
+        description: '**Windows only** The name of a user with access to the remote file specified by the source property. The user name may optionally be specified with a domain, such as: `domain\user` or `user@my.dns.domain.com` via Universal Principal Name (UPN) format. The domain may also be set using the `remote_domain` property. Note that this property is ignored if source is not a UNC path. If this property is specified, the `remote_password` property is required.'
 
-      property :remote_password, String, sensitive: true
+      property :remote_domain, String,
+        introduced: "13.4",
+        description: "**Windows only** The domain of the user specified by the `remote_user` property. By default the resource will authenticate against the domain of the remote system, or as a local account if the remote system is not joined to a domain. If the remote system is not part of a domain, it is necessary to authenticate as a local user on the remote system by setting the domain to `.`, for example: remote_domain '.'. The domain may also be specified as part of the `remote_user` property."
 
-      property :authentication, equal_to: %i{remote local}, default: :remote
+      property :remote_password, String, sensitive: true,
+        introduced: "13.4",
+        description: "**Windows only** The password of the user specified by the `remote_user` property. This property is required if `remote_user` is specified and may only be specified if `remote_user` is specified. The `sensitive` property for this resource will automatically be set to `true` if `remote_password` is specified."
+
+      property :authentication, Symbol, equal_to: %i{remote local}, default: :remote
 
       def after_created
         validate_identity_platform(remote_user, remote_password, remote_domain)

data/lib/chef/resource/rhsm_errata.rb

@@ -23,9 +23,7 @@ class Chef
       unified_mode true
       provides(:rhsm_errata) { true }
 
-      description "Use the rhsm_errata resource to install packages associated with a given Red"\
-                  " Hat Subscription Manager Errata ID. This is helpful if packages"\
-                  " to mitigate a single vulnerability must be installed on your hosts."
+      description "Use the **rhsm_errata** resource to install packages associated with a given Red Hat Subscription Manager Errata ID. This is helpful if packages to mitigate a single vulnerability must be installed on your hosts."
       introduced "14.0"
 
       property :errata_id, String,

data/lib/chef/resource/rhsm_errata_level.rb

@@ -23,7 +23,7 @@ class Chef
       unified_mode true
       provides(:rhsm_errata_level) { true }
 
-      description "Use the rhsm_errata_level resource to install all packages of a specified errata level from the Red Hat Subscription Manager. For example, you can ensure that all packages associated with errata marked at a 'Critical' security level are installed."
+      description "Use the **rhsm_errata_level** resource to install all packages of a specified errata level from the Red Hat Subscription Manager. For example, you can ensure that all packages associated with errata marked at a 'Critical' security level are installed."
       introduced "14.0"
 
       property :errata_level, String,

data/lib/chef/resource/rhsm_register.rb

@@ -25,8 +25,7 @@ class Chef
       unified_mode true
       provides(:rhsm_register) { true }
 
-      description "Use the rhsm_register resource to register a node with the Red Hat Subscription Manager"\
-                  " or a local Red Hat Satellite server."
+      description "Use the **rhsm_register** resource to register a node with the Red Hat Subscription Manager or a local Red Hat Satellite server."
       introduced "14.0"
 
       property :activation_key, [String, Array],

data/lib/chef/resource/rhsm_repo.rb

@@ -24,8 +24,7 @@ class Chef
 
       provides(:rhsm_repo) { true }
 
-      description "Use the rhsm_repo resource to enable or disable Red Hat Subscription Manager"\
-                  " repositories that are made available via attached subscriptions."
+      description "Use the **rhsm_repo** resource to enable or disable Red Hat Subscription Manager repositories that are made available via attached subscriptions."
       introduced "14.0"
 
       property :repo_name, String,

data/lib/chef/resource/rhsm_subscription.rb

@@ -24,9 +24,7 @@ class Chef
 
       provides(:rhsm_subscription) { true }
 
-      description "Use the rhsm_subscription resource to add or remove Red Hat Subscription Manager"\
-                  " subscriptions from your host. This can be used when a host's activation_key"\
-                  " does not attach all necessary subscriptions to your host."
+      description "Use the **rhsm_subscription** resource to add or remove Red Hat Subscription Manager subscriptions from your host. This can be used when a host's activation_key does not attach all necessary subscriptions to your host."
       introduced "14.0"
 
       property :pool_id, String,

data/lib/chef/resource/route.rb

@@ -29,7 +29,7 @@ class Chef
       default_action :add
       allowed_actions :add, :delete
 
-      description "Use the route resource to manage the system routing table in a Linux environment."
+      description "Use the **route** resource to manage the system routing table in a Linux environment."
 
       property :target, String,
         description: "The IP address of the target route.",

data/lib/chef/resource/rpm_package.rb

@@ -25,9 +25,12 @@ class Chef
 
       provides :rpm_package
 
-      description "Use the rpm_package resource to manage packages using the RPM Package Manager."
+      description "Use the **rpm_package** resource to manage packages using the RPM Package Manager."
 
-      property :allow_downgrade, [ true, false ], default: true, desired_state: false
+      property :allow_downgrade, [ TrueClass, FalseClass ],
+        description: "Allow downgrading a package to satisfy requested version requirements.",
+        default: true,
+        desired_state: false
 
       property :package_name, String,
         description: "An optional property to set the package name if it differs from the resource block's name.",

data/lib/chef/resource/ruby.rb

@@ -17,7 +17,6 @@
 #
 
 require_relative "script"
-require_relative "../provider/script"
 
 class Chef
   class Resource
@@ -26,7 +25,7 @@ class Chef
 
       provides :ruby
 
-      description "Use the ruby resource to execute scripts using the Ruby interpreter. This"\
+      description "Use the **ruby** resource to execute scripts using the Ruby 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"\

data/lib/chef/resource/ruby_block.rb

@@ -28,10 +28,7 @@ class Chef
 
       provides :ruby_block, target_mode: true
 
-      description "Use the ruby_block resource to execute Ruby code during a #{Chef::Dist::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."
+      description "Use the **ruby_block** resource to execute Ruby code during a #{Chef::Dist::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."
 
       default_action :run
       allowed_actions :create, :run

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

@@ -25,17 +25,18 @@ property :destination, String,
   description: "The location path to which the source is to be cloned, checked out, or exported. Default value: the name of the resource block.",
   name_property: true
 
-property :repository, String
+property :repository, String,
+  description: "The URI of the code repository."
 
 property :revision, String,
   description: "The revision to checkout.",
   default: "HEAD"
 
 property :user, [String, Integer],
-  description: "The system user that should own the checked-out code."
+  description: "The system user that will own the checked-out code."
 
 property :group, [String, Integer],
-  description: "The system group that should own the checked-out code."
+  description: "The system group that will own the checked-out code."
 
 property :timeout, Integer,
   description: "The amount of time (in seconds) to wait before timing out.",

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

@@ -27,7 +27,7 @@ class Chef
 
       provides :git
 
-      description "Use the git resource to manage source control resources that exist in a git repository. git version 1.6.5 (or higher) is required to use all of the functionality in the git resource."
+      description "Use the **git** resource to manage source control resources that exist in a git repository. git version 1.6.5 (or higher) is required to use all of the functionality in the git resource."
 
       property :additional_remotes, Hash,
         description: "A Hash of additional remotes that are added to the git repository configuration.",
@@ -53,7 +53,7 @@ class Chef
         description: "The path to the wrapper script used when running SSH with git. The `GIT_SSH` environment variable is set to this."
 
       property :checkout_branch, String,
-        description: "Set this to use a local branch to avoid checking SHAs or tags to a detatched head state."
+        description: "Set this to use a local branch to avoid checking SHAs or tags to a detached head state."
 
       alias :branch :revision
       alias :reference :revision

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."
 
       allowed_actions :force_export
 
@@ -38,7 +38,7 @@ class Chef
         default: "--no-auth-cache"
 
       property :svn_info_args, [String, nil, FalseClass],
-        description: "Use when the svn info command is used by the #{Chef::Dist::CLIENT} and arguments need to be passed. The svn_arguments command does not work when the svn info command is used.",
+        description: "Use when the `svn info` command is used by #{Chef::Dist::PRODUCT} and arguments need to be passed. The `svn_arguments` command does not work when the `svn info` command is used.",
         coerce: proc { |v| v == false ? nil : v }, # coerce false to nil
         default: "--no-auth-cache"
 

data/lib/chef/resource/script.rb

@@ -28,7 +28,7 @@ class Chef
 
       identity_attr :name
 
-      description "Use the script resource to execute scripts using a specified interpreter, such as Bash, csh, Perl, Python, or Ruby."\
+      description "Use the **script** resource to execute scripts using a specified interpreter, such as Bash, csh, Perl, Python, or Ruby."\
                   " 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."

data/lib/chef/resource/service.rb

@@ -31,7 +31,7 @@ class Chef
 
       provides :service, target_mode: true
 
-      description "Use the service resource to manage a service."
+      description "Use the **service** resource to manage a service."
 
       default_action :nothing
       allowed_actions :enable, :disable, :start, :stop, :restart, :reload,

data/lib/chef/resource/smartos_package.rb

@@ -26,7 +26,7 @@ class Chef
       provides :smartos_package
       provides :package, platform_family: "smartos"
 
-      description "Use the smartos_package resource to manage packages for the SmartOS platform."
+      description "Use the **smartos_package** resource to manage packages for the SmartOS platform."
 
       property :package_name, String,
         description: "An optional property to set the package name if it differs from the resource block's name.",

data/lib/chef/resource/snap_package.rb

@@ -25,7 +25,7 @@ class Chef
 
       provides :snap_package
 
-      description "Use the snap_package resource to manage snap packages on Debian and Ubuntu platforms."
+      description "Use the **snap_package** resource to manage snap packages on Debian and Ubuntu platforms."
       introduced "15.0"
 
       property :channel, String,

data/lib/chef/resource/solaris_package.rb

@@ -28,7 +28,7 @@ class Chef
       provides :package, os: "solaris2", platform_family: "nexentacore"
       provides :package, os: "solaris2", platform_family: "solaris2", platform_version: "<= 5.10"
 
-      description "The solaris_package resource is used to manage packages for the Solaris platform."
+      description "Use the **solaris_package** resource to manage packages on the Solaris platform."
 
       property :package_name, String,
         description: "An optional property to set the package name if it differs from the resource block's name.",