chef 16.0.257 → 16.0.275

data/lib/chef/resource/windows_uac.rb

@@ -22,8 +22,27 @@ class Chef
     class WindowsUac < Chef::Resource
       provides :windows_uac
 
-      description 'The windows_uac resource configures UAC on Windows hosts by setting registry keys at \'HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System\''
+      description 'The *windows_uac* resource configures UAC on Windows hosts by setting registry keys at `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System`'
       introduced "15.0"
+      examples <<~DOC
+      **Disable UAC prompts for the admin**:
+
+      ``` ruby
+      windows_uac 'Disable UAC prompts for the admin' do
+        enable_uac true
+        prompt_on_secure_desktop false
+        consent_behavior_admins :no_prompt
+      end
+      ```
+
+      **Disable UAC entirely**:
+
+      ``` ruby
+      windows_uac 'Disable UAC entirely' do
+        enable_uac false
+      end
+      ```
+      DOC
 
       # https://docs.microsoft.com/en-us/windows/security/identity-protection/user-account-control/user-account-control-group-policy-and-registry-key-settings#user-account-control-virtualize-file-and-registry-write-failures-to-per-user-locations
       property :enable_uac, [TrueClass, FalseClass],

data/lib/chef/resource/windows_workgroup.rb

@@ -26,8 +26,24 @@ class Chef
 
       include Chef::Mixin::PowershellOut
 
-      description "Use the windows_workgroup resource to join or change the workgroup of a Windows host."
+      description "Use the **windows_workgroup** resource to join or change the workgroup of a Windows host."
       introduced "14.5"
+      examples <<~DOC
+      **Join a workgroup**:
+
+      ``` ruby
+      windows_workgroup 'myworkgroup'
+      ```
+
+      **Join a workgroup using a specific user**:
+
+      ``` ruby
+      windows_workgroup 'myworkgroup' do
+        user 'Administrator'
+        password 'passw0rd'
+      end
+      ```
+      DOC
 
       property :workgroup_name, String,
         description: "An optional property to set the workgroup name if it differs from the resource block's name.",
@@ -36,11 +52,11 @@ class Chef
         name_property: true
 
       property :user, String,
-        description: "The local administrator user to use to change the workgroup. Required if using the password property.",
+        description: "The local administrator user to use to change the workgroup. Required if using the `password` property.",
         desired_state: false
 
       property :password, String,
-        description: "The password for the local administrator user. Required if using the user property.",
+        description: "The password for the local administrator user. Required if using the `user` property.",
         desired_state: false
 
       property :reboot, Symbol,

data/lib/chef/resource/yum_package.rb

@@ -27,11 +27,92 @@ 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"\
+      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."\
+                  " `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."
+      examples <<~DOC
+        **Install an exact version**:
+
+        ``` ruby
+        yum_package 'netpbm = 10.35.58-8.el8'
+        ```
+
+        **Install a minimum version**:
+
+        ``` ruby
+        yum_package 'netpbm >= 10.35.58-8.el8'
+        ```
+
+        **Install a minimum version using the default action**:
+
+        ``` ruby
+        yum_package 'netpbm'
+        ```
+
+        **Install a version without worrying about the exact release**:
+
+        ``` ruby
+        yum_package 'netpbm-10.35*'
+        ```
+
+
+        **To install a package**:
+
+        ``` ruby
+        yum_package 'netpbm' do
+          action :install
+        end
+        ```
+
+        **To install a partial minimum version**:
+
+        ``` ruby
+        yum_package 'netpbm >= 10'
+        ```
+
+        **To install a specific architecture**:
+
+        ``` ruby
+        yum_package 'netpbm' do
+          arch 'i386'
+        end
+        ```
+
+        or:
+
+        ``` ruby
+        yum_package 'netpbm.x86_64'
+        ```
+
+        **To install a specific version-release**
+
+        ``` ruby
+        yum_package 'netpbm' do
+          version '10.35.58-8.el8'
+        end
+        ```
+
+        **Handle cookbook_file and yum_package resources in the same recipe**:
+
+        When a **cookbook_file** resource and a **yum_package** resource are
+        both called from within the same recipe, use the `flush_cache` attribute
+        to dump the in-memory Yum cache, and then use the repository immediately
+        to ensure that the correct package is installed:
+
+        ``` ruby
+        cookbook_file '/etc/yum.repos.d/custom.repo' do
+          source 'custom'
+          mode '0755'
+        end
+
+        yum_package 'pkg-that-is-only-in-custom-repo' do
+          action :install
+          flush_cache [ :before ]
+        end
+        ```
+      DOC
 
       # XXX: the coercions here are due to the provider promiscuously updating the properties on the
       # new_resource which causes immutable modification exceptions when passed an immutable node array.
@@ -46,7 +127,7 @@ class Chef
         identity: true, coerce: proc { |x| x.is_a?(Array) ? x.to_a : x }
 
       property :version, [ String, Array ],
-        description: "The version of a package to be installed or upgraded. This property is ignored when using the ':upgrade' action.",
+        description: "The version of a package to be installed or upgraded. This property is ignored when using the `:upgrade` action.",
         coerce: proc { |x| x.is_a?(Array) ? x.to_a : x }
 
       property :arch, [ String, Array ],
@@ -70,12 +151,13 @@ class Chef
           end
         }
 
-      property :allow_downgrade, [ true, false ],
-        description: "Downgrade a package to satisfy requested version requirements.",
+      property :allow_downgrade, [ TrueClass, FalseClass ],
+        description: "Allow downgrading a package to satisfy requested version requirements.",
         default: true,
         desired_state: false
 
-      property :yum_binary, String
+      property :yum_binary, String,
+        description: "The path to the yum binary."
     end
   end
 end

data/lib/chef/resource/yum_repository.rb

@@ -25,21 +25,38 @@ class Chef
 
       provides(:yum_repository) { true }
 
-      description "Use the yum_repository resource to manage a Yum repository configuration"\
-                  " file located at /etc/yum.repos.d/repositoryid.repo on the local machine."\
-                  " This configuration file specifies which repositories to reference, how to"\
-                  " handle cached data, etc."
+      description "Use the **yum_repository** resource to manage a Yum repository configuration file located at `/etc/yum.repos.d/repositoryid.repo` on the local machine. This configuration file specifies which repositories to reference, how to handle cached data, etc."
       introduced "12.14"
+      examples <<~DOC
+      **Add an internal company repository**:
+
+      ```ruby
+      yum_repository 'OurCo' do
+        description 'OurCo yum repository'
+        mirrorlist 'http://artifacts.ourco.org/mirrorlist?repo=ourco-8&arch=$basearch'
+        gpgkey 'http://artifacts.ourco.org/pub/yum/RPM-GPG-KEY-OURCO-8'
+        action :create
+      end
+      ```ruby
+
+      **Delete a repository**:
+
+      ```ruby
+      yum_repository 'CentOS-Media' do
+        action :delete
+      end
+      ```
+      DOC
 
       # http://linux.die.net/man/5/yum.conf as well as
       # http://dnf.readthedocs.io/en/latest/conf_ref.html
       property :baseurl, [String, Array],
-        description: "URL to the directory where the Yum repository's 'repodata' directory lives. Can be an http://, https:// or a ftp:// URL. You can specify multiple URLs in one baseurl statement."
+        description: "URL to the directory where the Yum repository's `repodata` directory lives. Can be an `http://`, `https://` or a `ftp://` URLs. You can specify multiple URLs in one `baseurl` statement."
 
       property :clean_headers, [TrueClass, FalseClass],
         description: "Specifies whether you want to purge the package data files that are downloaded from a Yum repository and held in a cache directory.",
         deprecated: true,
-        default: false # deprecated
+        default: false
 
       property :clean_metadata, [TrueClass, FalseClass],
         description: "Specifies whether you want to purge all of the packages downloaded from a Yum repository and held in a cache directory.",
@@ -64,7 +81,7 @@ class Chef
         description: "List of packages to exclude from updates or installs. This should be a space separated list. Shell globs using wildcards (eg. * and ?) are allowed."
 
       property :failovermethod, String,
-        description: "Method to determine how to switch to a new server if the current one fails, which can either be ``roundrobin`` or ``priority``. ``roundrobin`` randomly selects a URL out of the list of URLs to start with and proceeds through each of them as it encounters a failure contacting the host. ``priority`` starts from the first ``baseurl`` listed and reads through them sequentially.",
+        description: "Method to determine how to switch to a new server if the current one fails, which can either be `roundrobin` or `priority`. `roundrobin` randomly selects a URL out of the list of URLs to start with and proceeds through each of them as it encounters a failure contacting the host. `priority` starts from the first `baseurl` listed and reads through them sequentially.",
         equal_to: %w{priority roundrobin}
 
       property :fastestmirror_enabled, [TrueClass, FalseClass],
@@ -81,23 +98,23 @@ class Chef
                description: "Determines how upstream HTTP caches are instructed to handle any HTTP downloads that Yum does. This option can take the following values: all (all HTTP downloads should be cached), packages (only RPM package downloads should be cached, but not repository metadata downloads), or none (no HTTP downloads should be cached)"
 
       property :include_config, String,
-        description: "An external configuration file using the format 'url://to/some/location'."
+        description: "An external configuration file using the format `url://to/some/location`."
 
       property :includepkgs, String,
         description: "Inverse of exclude property. This is a list of packages you want to use from a repository. If this option lists only one package then that is all Yum will ever see from the repository."
 
       property :keepalive, [TrueClass, FalseClass],
-        description: "Determines whether or not HTTP/1.1 ``keep-alive`` should be used with this repository."
+        description: "Determines whether or not HTTP/1.1 `keep-alive` should be used with this repository."
 
       property :make_cache, [TrueClass, FalseClass],
         description: "Determines whether package files downloaded by Yum stay in cache directories. By using cached data, you can carry out certain operations without a network connection.",
         default: true
 
       property :max_retries, [String, Integer],
-        description: "Number of times any attempt to retrieve a file should retry before returning an error. Setting this to '0' makes Yum try forever."
+        description: "Number of times any attempt to retrieve a file should retry before returning an error. Setting this to `0` makes Yum try forever."
 
       property :metadata_expire, String, regex: [/^\d+$/, /^\d+[mhd]$/, /never/],
-               description: "Time (in seconds) after which the metadata will expire. If the current metadata downloaded is less than the value specified, then Yum will not update the metadata against the repository. If you find that Yum is not downloading information on updates as often as you would like lower the value of this option. You can also change from the default of using seconds to using days, hours or minutes by appending a 'd', 'h' or 'm' respectively. The default is six hours to compliment yum-updates running once per hour. It is also possible to use the word ``never``, meaning that the metadata will never expire. Note: When using a metalink file, the metalink must always be newer than the metadata for the repository due to the validation, so this timeout also applies to the metalink file.",
+               description: "Time (in seconds) after which the metadata will expire. If the current metadata downloaded is less than the value specified, then Yum will not update the metadata against the repository. If you find that Yum is not downloading information on updates as often as you would like lower the value of this option. You can also change from the default of using seconds to using days, hours or minutes by appending a 'd', 'h' or 'm' respectively. The default is six hours to compliment yum-updates running once per hour. It is also possible to use the word `never`, meaning that the metadata will never expire. Note: When using a metalink file, the metalink must always be newer than the metadata for the repository due to the validation, so this timeout also applies to the metalink file.",
                validation_message: "The metadata_expire property must be a numeric value for time in seconds, the string 'never', or a numeric value appended with with 'd', 'h', or 'm'!"
 
       property :metalink, String,

data/lib/chef/resource/zypper_package.rb

@@ -26,10 +26,36 @@ class Chef
       provides :zypper_package
       provides :package, platform_family: "suse"
 
-      description "Use the zypper_package resource to install, upgrade, and remove packages with Zypper for the SUSE Enterprise and OpenSUSE platforms."
+      description "Use the **zypper_package** resource to install, upgrade, and remove packages with Zypper for the SUSE Enterprise and openSUSE platforms."
+      examples <<~DOC
+        **Install a package using package manager:**
+
+        ``` ruby
+        zypper_package 'name of package' do
+          action :install
+        end
+        ```
+
+        **Install a package using local file:**
+
+        ``` ruby
+        zypper_package 'jwhois' do
+          action :install
+          source '/path/to/jwhois.rpm'
+        end
+        ```
+
+        **Install without using recommend packages as a dependency:**
+
+        ``` ruby
+        package 'apache2' do
+          options '--no-recommends'
+          end
+        ```
+      DOC
 
       property :gpg_check, [ TrueClass, FalseClass ],
-        description: "Verify the package's GPG signature. Can also be controlled site-wide using the ``zypper_check_gpg`` config option.",
+        description: "Verify the package's GPG signature. Can also be controlled site-wide using the `zypper_check_gpg` config option.",
         default: lazy { Chef::Config[:zypper_check_gpg] }, default_description: "true"
 
       property :allow_downgrade, [ TrueClass, FalseClass ],
@@ -39,7 +65,7 @@ class Chef
         introduced: "13.6"
 
       property :global_options, [ String, Array ],
-        description: "One (or more) additional command options that are passed to the command. For example, common zypper directives, such as '--no-recommends'. See the zypper man page at https://en.opensuse.org/SDB:Zypper_manual_(plain) for the full list.",
+        description: "One (or more) additional command options that are passed to the command. For example, common zypper directives, such as `--no-recommends`. See the [zypper man page](https://en.opensuse.org/SDB:Zypper_manual_(plain)) for the full list.",
         coerce: proc { |x| x.is_a?(String) ? x.shellsplit : x },
         introduced: "14.6"
     end

data/lib/chef/resource/zypper_repository.rb

@@ -26,17 +26,29 @@ class Chef
       provides(:zypper_repository) { true }
       provides(:zypper_repo) { true }
 
-      description "Use the zypper_repository resource to create Zypper package repositories on SUSE Enterprise Linux and openSUSE systems. This resource maintains full compatibility with the zypper_repository resource in the existing zypper cookbook."
+      description "Use the **zypper_repository** resource to create Zypper package repositories on SUSE Enterprise Linux and openSUSE systems. This resource maintains full compatibility with the **zypper_repository** resource in the existing **zypper** cookbook."
       introduced "13.3"
+      examples <<~DOC
+        **Add the Apache repo on openSUSE Leap 15**:
+
+        ``` ruby
+        zypper_repository 'apache' do
+          baseurl 'http://download.opensuse.org/repositories/Apache'
+          path '/openSUSE_Leap_15.0'
+            type 'rpm-md'
+          priority '100'
+        end
+        ```
+      DOC
 
       property :repo_name, String,
         regex: [%r{^[^/]+$}],
         description: "An optional property to set the repository name if it differs from the resource block's name.",
-        validation_message: "repo_name property cannot contain a forward slash '/'",
+        validation_message: "repo_name property cannot contain a forward slash `/`",
         name_property: true
 
       property :description, String,
-        description: "The description of the repository that will be shown by the 'zypper repos' command."
+        description: "The description of the repository that will be shown by the `zypper repos` command."
 
       property :type, String,
         description: "Specifies the repository type.",
@@ -58,7 +70,7 @@ class Chef
         description: "The location of the repository key to be imported."
 
       property :baseurl, String,
-        description: "The base URL for the Zypper repository, such as 'http://download.opensuse.org'."
+        description: "The base URL for the Zypper repository, such as `http://download.opensuse.org`."
 
       property :mirrorlist, String,
         description: "The URL of the mirror list that will be used."
@@ -67,7 +79,7 @@ class Chef
         description: "The relative path from the repository's base URL."
 
       property :priority, Integer,
-        description: "Determines the priority of the Zypper repository. ",
+        description: "Determines the priority of the Zypper repository.",
         default: 99
 
       property :keeppackages, [TrueClass, FalseClass],

data/lib/chef/resource_inspector.rb

@@ -59,7 +59,7 @@ module ResourceInspector
                required: opts[:required] || false,
                default: opts[:default_description] || get_default(opts[:default]),
                name_property: opts[:name_property] || false,
-               equal_to: opts[:equal_to] || [] }
+               equal_to: Array(opts[:equal_to]).sort.map(&:inspect) }
     end
     data
   end

data/lib/chef/scan_access_control.rb

@@ -33,7 +33,7 @@ class Chef
   # Not yet sure if this is the optimal way to solve the problem. But it's
   # progress towards the end goal.
   #
-  # TODO: figure out if all this works with OS X's negative uids
+  # TODO: figure out if all this works with macOS' negative uids
   # TODO: windows
   class ScanAccessControl
 

data/lib/chef/version.rb

@@ -23,7 +23,7 @@ require_relative "version_string"
 
 class Chef
   CHEF_ROOT = File.expand_path("../..", __FILE__)
-  VERSION = Chef::VersionString.new("16.0.257")
+  VERSION = Chef::VersionString.new("16.0.275")
 end
 
 #

data/spec/functional/resource/link_spec.rb

@@ -656,10 +656,10 @@ describe Chef::Resource::Link do
           end
           context "and the link does not yet exist" do
             it "links to the target file" do
-              skip("OS X/FreeBSD/AIX/Solaris symlink? and readlink working on hard links to symlinks") if os_x? || freebsd? || aix? || solaris?
+              skip("macOS/FreeBSD/AIX/Solaris symlink? and readlink working on hard links to symlinks") if os_x? || freebsd? || aix? || solaris?
               resource.run_action(:create)
               expect(File.exists?(target_file)).to be_truthy
-              # OS X gets angry about this sort of link.  Bug in OS X, IMO.
+              # macOS gets angry about this sort of link. Bug in macOS, IMO.
               expect(symlink?(target_file)).to be_truthy
               expect(readlink(target_file)).to eq(canonicalize(@other_target))
             end
@@ -675,7 +675,7 @@ describe Chef::Resource::Link do
           end
           context "and the link does not yet exist" do
             it "links to the target file" do
-              skip("OS X/FreeBSD/AIX/Solaris fails to create hardlinks to broken symlinks") if os_x? || freebsd? || aix? || solaris?
+              skip("macOS/FreeBSD/AIX/Solaris fails to create hardlinks to broken symlinks") if os_x? || freebsd? || aix? || solaris?
               resource.run_action(:create)
               expect(File.exists?(target_file) || File.symlink?(target_file)).to be_truthy
               expect(symlink?(target_file)).to be_truthy

data/spec/functional/resource/remote_file_spec.rb

@@ -112,7 +112,7 @@ describe Chef::Resource::RemoteFile do
                       SSLPrivateKey: key,
                       RequestTimeout: 1 }
 
-      start_tiny_server(server_opts)
+      start_tiny_server(**server_opts)
     end
 
     after(:all) do

data/spec/integration/knife/raw_spec.rb

@@ -214,8 +214,8 @@ describe "knife raw", :workstation do
     end
 
     context "When a server returns raw json" do
-      def start_tiny_server(server_opts = {})
-        @server = TinyServer::Manager.new(server_opts)
+      def start_tiny_server(**server_opts)
+        @server = TinyServer::Manager.new(**server_opts)
         @server.start
         @api = TinyServer::API.instance
         @api.clear
@@ -256,8 +256,8 @@ describe "knife raw", :workstation do
     end
 
     context "When a server returns text" do
-      def start_tiny_server(server_opts = {})
-        @server = TinyServer::Manager.new(server_opts)
+      def start_tiny_server(**server_opts)
+        @server = TinyServer::Manager.new(**server_opts)
         @server.start
         @api = TinyServer::API.instance
         @api.clear