chef 16.0.257 → 16.2.44

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

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