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

data/lib/chef/provider/zypper_repository.rb

@@ -115,28 +115,48 @@ class Chef
         end
       end
 
+      # the version of gpg installed on the system
+      #
+      # @return [Gem::Version] the version of GPG
+      def gpg_version
+        so = shell_out!("gpg --version")
+        # matches 2.0 and 2.2 versions from SLES 12 and 15: https://rubular.com/r/e6D0WfGK6SXvUp
+        version = /gpg \(GnuPG\)\s*(.*)/.match(so.stdout)[1]
+        logger.trace("GPG package version is #{version}")
+        Gem::Version.new(version)
+      end
+
       # is the provided key already installed
       # @param [String] key_path the path to the key on the local filesystem
       #
       # @return [boolean] is the key already known by rpm
       def key_installed?(key_path)
-        so = shell_out("rpm -qa gpg-pubkey*")
+        so = shell_out("/bin/rpm -qa gpg-pubkey*")
         # expected output & match: http://rubular.com/r/RdF7EcXEtb
-        status = /gpg-pubkey-#{key_fingerprint(key_path)}/.match(so.stdout)
+        status = /gpg-pubkey-#{short_key_id(key_path)}/.match(so.stdout)
         logger.trace("GPG key at #{key_path} is known by rpm? #{status ? "true" : "false"}")
         status
       end
 
-      # extract the gpg key fingerprint from a local file
+      # extract the gpg key's short key id from a local file. Learning moment: This 8 hex value ID
+      # is sometimes incorrectly called the fingerprint. The fingerprint is the full length value
+      # and googling for that will just result in sad times.
+      #
       # @param [String] key_path the path to the key on the local filesystem
       #
-      # @return [String] the fingerprint of the key
-      def key_fingerprint(key_path)
-        so = shell_out!("gpg --with-fingerprint #{key_path}")
-        # expected output and match: http://rubular.com/r/BpfMjxySQM
-        fingerprint = %r{pub\s*\S*/(\S*)}.match(so.stdout)[1].downcase
-        logger.trace("GPG fingerprint of key at #{key_path} is #{fingerprint}")
-        fingerprint
+      # @return [String] the short key id of the key
+      def short_key_id(key_path)
+        if gpg_version >= Gem::Version.new("2.2") # SLES 15+
+          so = shell_out!("gpg --import-options import-show --dry-run --import --with-colons #{key_path}")
+          # expected output and match: https://rubular.com/r/uXWJo3yfkli1qA
+          short_key_id = /fpr:*\h*(\h{8}):/.match(so.stdout)[1].downcase
+        else # SLES 12 and earlier
+          so = shell_out!("gpg --with-fingerprint #{key_path}")
+          # expected output and match: http://rubular.com/r/BpfMjxySQM
+          short_key_id = %r{pub\s*\S*/(\S*)}.match(so.stdout)[1].downcase
+        end
+        logger.trace("GPG short key ID of key at #{key_path} is #{short_key_id}")
+        short_key_id
       end
 
       # install the provided gpg key

data/lib/chef/resource.rb

@@ -451,6 +451,17 @@ class Chef
       description: "Determines whether or not the resource is executed during the compile time phase.",
       default: false, desired_state: false
 
+    # Set a umask to be used for the duration of converging the resource.
+    # Defaults to `nil`, which means to use the system umask.
+    #
+    # @param arg [String] The umask to apply while converging the resource.
+    # @return [Boolean] The umask to apply while converging the resource.
+    #
+    property :umask, String,
+      desired_state: false,
+      introduced: "16.2",
+      description: "Set a umask to be used for the duration of converging the resource. Defaults to `nil`, which means to use the system umask."
+
     # The time it took (in seconds) to run the most recently-run action.  Not
     # cumulative across actions.  This is set to 0 as soon as a new action starts
     # running, and set to the elapsed time at the end of the action.
@@ -588,7 +599,9 @@ class Chef
       begin
         return if should_skip?(action)
 
-        provider_for_action(action).run_action
+        with_umask do
+          provider_for_action(action).run_action
+        end
       rescue StandardError => e
         if ignore_failure
           logger.error("#{custom_exception_message(e)}; ignore_failure is set, continuing")
@@ -612,6 +625,13 @@ class Chef
       events.resource_completed(self)
     end
 
+    def with_umask
+      old_value = ::File.umask(umask.oct) if umask
+      yield
+    ensure
+      ::File.umask(old_value) if umask
+    end
+
     #
     # If we are currently initializing the resource, this will be true.
     #
@@ -930,7 +950,7 @@ class Chef
     end
 
     #
-    # A hook called after a resource is created.  Meant to be overriden by
+    # A hook called after a resource is created.  Meant to be overridden by
     # subclasses.
     #
     def after_created
@@ -950,16 +970,7 @@ class Chef
     def self.resource_name(name = NOT_PASSED)
       # Setter
       if name != NOT_PASSED
-        if name
-          @resource_name = name.to_sym
-          name = name.to_sym
-          # FIXME: determine a way to deprecate this magic behavior
-          unless Chef::ResourceResolver.includes_handler?(name, self)
-            provides name
-          end
-        else
-          @resource_name = nil
-        end
+        @resource_name = name.to_sym rescue nil
       end
 
       @resource_name = nil unless defined?(@resource_name)
@@ -1114,7 +1125,7 @@ class Chef
     # `action_class` method, the presence of either indicates that this is
     # going to be a Chef-12.5 custom resource.  If we never see one of these
     # directives then we are constructing an old-style Resource+Provider or
-    # LWRP or whatevs.
+    # LWRP or whatever.
     #
     # If a block is passed, the action_class is always created and the block is
     # run inside it.
@@ -1327,7 +1338,7 @@ class Chef
     # Once we no longer care about supporting chef < 14.4 then we can deprecate
     # this API.
     #
-    # @param arg [String] version constrant to match against (e.g. "> 14")
+    # @param arg [String] version constraint to match against (e.g. "> 14")
     #
     def self.chef_version_for_provides(constraint)
       @chef_version_for_provides = constraint

data/lib/chef/resource/alternatives.rb

@@ -28,11 +28,72 @@ class Chef
 
       description "The alternatives resource allows for configuration of command alternatives in Linux using the alternatives or update-alternatives packages."
       introduced "16.0"
+      examples <<~DOC
+      **Install an alternative**:
+
+      ```ruby
+      alternatives 'python install 2' do
+        link_name 'python'
+        path '/usr/bin/python2.7'
+        priority 100
+        action :install
+      end
+      ```
+
+      **Set an alternative**:
+
+      ```ruby
+      alternatives 'python set version 3' do
+        link_name 'python'
+        path '/usr/bin/python3'
+        action :set
+      end
+      ```
+
+      **Set the automatic alternative state**:
+
+      ```ruby
+      alternatives 'python auto' do
+        link_name 'python'
+        action :auto
+      end
+      ```
+
+      **Refresh an alternative**:
+
+      ```ruby
+      alternatives 'python refresh' do
+        link_name 'python'
+        action :refresh
+      end
+      ```
+
+      **Remove an alternative**:
+
+      ```ruby
+      alternatives 'python remove' do
+        link_name 'python'
+        path '/usr/bin/python3'
+        action :remove
+      end
+      ```
+      DOC
+
+      property :link_name, String,
+        name_property: true,
+        description: "The name of the link to create. This will be the command you type on the command line such as `ruby` or `gcc`."
+
+      property :link, String,
+        default: lazy { |n| "/usr/bin/#{n.link_name}" },
+        default_description: "/usr/bin/LINK_NAME",
+        description: "The path to the alternatives link."
+
+      property :path, String,
+        description: "The full path to the original application binary such as `/usr/bin/ruby27`."
 
-      property :link_name, String, name_property: true
-      property :link, String, default: lazy { |n| "/usr/bin/#{n.link_name}" }
-      property :path, String
-      property :priority, [String, Integer], coerce: proc { |n| n.to_i }
+      property :priority, [String, Integer],
+        coerce: proc { |n| n.to_i },
+        description: "The priority of the alternative."
 
       def define_resource_requirements
         requirements.assert(:install) do |a|

data/lib/chef/resource/apt_package.rb

@@ -25,11 +25,40 @@ class Chef
 
       provides :apt_package, target_mode: true
       provides :package, platform_family: "debian", target_mode: true
+      examples <<~DOC
+      **Install a package using package manager**:
 
-      description "Use the apt_package resource to manage packages on Debian and Ubuntu platforms."
+      ```ruby
+      apt_package 'name of package' do
+        action :install
+      end
+      ```
+
+      **Install a package without specifying the default action**:
+
+      ```ruby
+      apt_package 'name of package'
+      ```
+
+      **Install multiple packages at once**:
+
+      ```ruby
+      apt_package %(package1 package2 package3)
+      ```
+
+      **Install without using recommend packages as a dependency**:
+
+      ```ruby
+      package 'apache2' do
+        options '--no-install-recommends'
+      end
+      ```
+      DOC
+
+      description "Use the **apt_package** resource to manage packages on Debian and Ubuntu platforms."
 
       property :default_release, String,
-        description: "The default release. For example: stable.",
+        description: "The default release. For example: `stable`.",
         desired_state: false
 
       property :overwrite_config_files, [TrueClass, FalseClass],

data/lib/chef/resource/apt_preference.rb

@@ -20,14 +20,43 @@ require_relative "../resource"
 
 class Chef
   class Resource
-    # @since 13.3
     class AptPreference < Chef::Resource
       unified_mode true
 
       provides(:apt_preference) { true }
 
-      description "The apt_preference resource allows for the creation of APT preference files. Preference files are used to control which package versions and sources are prioritized during installation."
+      description "Use the **apt_preference** resource to create APT [preference files](https://wiki.debian.org/AptPreferences). Preference files are used to control which package versions and sources are prioritized during installation."
       introduced "13.3"
+      examples <<~DOC
+      **Pin libmysqlclient16 to a version 5.1.49-3**:
+
+      ```ruby
+      apt_preference 'libmysqlclient16' do
+        pin          'version 5.1.49-3'
+        pin_priority '700'
+      end
+      ```
+
+      Note: The `pin_priority` of `700` ensures that this version will be preferred over any other available versions.
+
+      **Unpin a libmysqlclient16**:
+
+      ```ruby
+      apt_preference 'libmysqlclient16' do
+        action :remove
+      end
+      ```
+
+      **Pin all packages to prefer the packages.dotdeb.org repository**:
+
+      ```ruby
+      apt_preference 'dotdeb' do
+        glob         '*'
+        pin          'origin packages.dotdeb.org'
+        pin_priority '700'
+      end
+      ```
+      DOC
 
       property :package_name, String,
         name_property: true,
@@ -36,15 +65,15 @@ class Chef
         validation_message: "The provided package name is not valid. Package names can only contain alphanumeric characters as well as _, -, +, or *!"
 
       property :glob, String,
-        description: "Pin by glob() expression or with regular expressions surrounded by /."
+        description: "Pin by a `glob()` expression or with a regular expression surrounded by `/`."
 
       property :pin, String,
         description: "The package version or repository to pin.",
-        required: true
+        required: [:add]
 
       property :pin_priority, [String, Integer],
         description: "Sets the Pin-Priority for a package. See <https://wiki.debian.org/AptPreferences> for more details.",
-        required: true
+        required: [:add]
 
       default_action :add
       allowed_actions :add, :remove

data/lib/chef/resource/apt_repository.rb

@@ -28,11 +28,12 @@ class Chef
 
       provides(:apt_repository) { true }
 
-      description "Use the apt_repository resource to specify additional APT repositories. Adding a new repository will update the APT package cache immediately."
+      description "Use the **apt_repository** resource to specify additional APT repositories. Adding a new repository will update the APT package cache immediately."
       introduced "12.9"
 
       examples <<~DOC
-        Add repository with basic settings
+        **Add repository with basic settings**:
+
          ```ruby
         apt_repository 'nginx' do
           uri        'http://nginx.org/packages/ubuntu/'
@@ -40,29 +41,32 @@ class Chef
         end
         ```
 
-        Enable Ubuntu multiverse repositories
+        **Enable Ubuntu multiverse repositories**:
+
         ```ruby
         apt_repository 'security-ubuntu-multiverse' do
           uri          'http://security.ubuntu.com/ubuntu'
-          distribution 'trusty-security'
+          distribution 'xenial-security'
           components   ['multiverse']
           deb_src      true
         end
         ```
 
-        Add the Nginx PPA, autodetect the key and repository url
+        **Add the Nginx PPA, autodetect the key and repository url**:
+
         ```ruby
         apt_repository 'nginx-php' do
           uri          'ppa:nginx/stable'
         end
         ```
 
-        Add the JuJu PPA, grab the key from the keyserver, and add source repo
+        **Add the JuJu PPA, grab the key from the keyserver, and add source repo**:
+
         ```ruby
         apt_repository 'juju' do
           uri 'http://ppa.launchpad.net/juju/stable/ubuntu'
           components ['main']
-          distribution 'trusty'
+          distribution 'xenial'
           key 'C8068B11'
           keyserver 'keyserver.ubuntu.com'
           action :add
@@ -70,7 +74,8 @@ class Chef
         end
         ```
 
-        Add repository that requires multiple keys to authenticate packages
+        **Add repository that requires multiple keys to authenticate packages**:
+
         ```ruby
         apt_repository 'rundeck' do
           uri 'https://dl.bintray.com/rundeck/rundeck-deb'
@@ -81,18 +86,20 @@ class Chef
         end
         ```
 
-        Add the Cloudera Repo of CDH4 packages for Ubuntu 12.04 on AMD64
+        **Add the Cloudera Repo of CDH4 packages for Ubuntu 16.04 on AMD64**:
+
         ```ruby
         apt_repository 'cloudera' do
-          uri          'http://archive.cloudera.com/cdh4/ubuntu/precise/amd64/cdh'
+          uri          'http://archive.cloudera.com/cdh4/ubuntu/xenial/amd64/cdh'
           arch         'amd64'
-          distribution 'precise-cdh4'
+          distribution 'xenial-cdh4'
           components   ['contrib']
           key          'http://archive.cloudera.com/debian/archive.key'
         end
         ```
 
-        Remove a repository from the list
+        **Remove a repository from the list**:
+
         ```ruby
         apt_repository 'zenoss' do
           action :remove
@@ -115,15 +122,15 @@ class Chef
         description: "The base of the Debian distribution."
 
       property :distribution, [ String, nil, FalseClass ],
-        description: "Usually a distribution's codename, such as xenial, bionic, or focal.",
+        description: "Usually a distribution's codename, such as `xenial`, `bionic`, or `focal`.",
         default: lazy { node["lsb"]["codename"] }, default_description: "The LSB codename of the node such as 'focal'."
 
       property :components, Array,
         description: "Package groupings, such as 'main' and 'stable'.",
-        default: lazy { [] }, default_description: "'main' if using a PPA repository."
+        default: lazy { [] }, default_description: "`main` if using a PPA repository."
 
       property :arch, [String, nil, FalseClass],
-        description: "Constrain packages to a particular CPU architecture such as 'i386' or 'amd64'."
+        description: "Constrain packages to a particular CPU architecture such as `i386` or `amd64`."
 
       property :trusted, [TrueClass, FalseClass],
         description: "Determines whether you should treat all packages from this repository as authenticated regardless of signature.",

data/lib/chef/resource/apt_update.rb

@@ -25,10 +25,11 @@ class Chef
 
       provides(:apt_update) { true }
 
-      description "Use the apt_update resource to manage APT repository updates on Debian and Ubuntu platforms."
+      description "Use the **apt_update** resource to manage APT repository updates on Debian and Ubuntu platforms."
       introduced "12.7"
       examples <<~DOC
-        Update the Apt repository at a specified interval
+        **Update the Apt repository at a specified interval**:
+
         ```ruby
         apt_update 'all platforms' do
         frequency 86400
@@ -36,7 +37,8 @@ class Chef
         end
         ```
 
-        Update the Apt repository at the start of a Chef Infra Client run
+        **Update the Apt repository at the start of a Chef Infra Client run**:
+
         ```ruby
         apt_update 'update'
         ```
@@ -46,7 +48,7 @@ class Chef
       property :name, String, default: ""
 
       property :frequency, Integer,
-        description: "Determines how frequently (in seconds) APT repository updates are made. Use this property when the :periodic action is specified.",
+        description: "Determines how frequently (in seconds) APT repository updates are made. Use this property when the `:periodic` action is specified.",
         default: 86_400
 
       default_action :periodic