chef 14.4.56 → 14.5.27

data/lib/chef/resource/dsc_script.rb

@@ -28,14 +28,7 @@ class Chef
       resource_name :dsc_script
       provides :dsc_script
 
-      description "Many DSC resources are comparable to built-in Chef resources. For"\
-                  " example, both DSC and Chef have file, package, and service resources."\
-                  " The dsc_script resource is most useful for those DSC resources that"\
-                  " do not have a direct comparison to a resource in Chef, such as the"\
-                  " Archive resource, a custom DSC resource, an existing DSC script"\
-                  " that performs an important task, and so on. Use the dsc_script resource"\
-                  " to embed the code that defines a DSC configuration directly within a"\
-                  " Chef recipe."
+      description "Many DSC resources are comparable to built-in Chef resources. For example, both DSC and Chef have file, package, and service resources. The dsc_script resource is most useful for those DSC resources that do not have a direct comparison to a resource in Chef, such as the Archive resource, a custom DSC resource, an existing DSC script that performs an important task, and so on. Use the dsc_script resource to embed the code that defines a DSC configuration directly within a Chef recipe."
 
       default_action :run
 

data/lib/chef/resource/execute.rb

@@ -98,9 +98,12 @@ class Chef
                description: "Windows only: The password of the user specified by the user property. This property is mandatory if user is specified on Windows and may only be specified if user is specified. The sensitive property for this resource will automatically be set to true if password is specified."
 
       # lazy used to set default value of sensitive to true if password is set
-      property :sensitive, [ TrueClass, FalseClass ], default: lazy { |r| r.password ? true : false }
+      property :sensitive, [ TrueClass, FalseClass ],
+               description: "Ensure that sensitive resource data is not logged by the chef-client.",
+               default: lazy { |r| r.password ? true : false }
 
       property :elevated, [ TrueClass, FalseClass ], default: false,
+               description: "Determines whether the script will run with elevated permissions to circumvent User Access Control (UAC) interactively blocking the process.\nThis will cause the process to be run under a batch login instead of an interactive login. The user running Chef needs the “Replace a process level token” and “Adjust Memory Quotas for a process” permissions. The user that is running the command needs the “Log on as a batch job” permission.\nBecause this requires a login, the user and password properties are required.",
                introduced: "13.3"
 
       def self.set_guard_inherited_attributes(*inherited_attributes)

data/lib/chef/resource/gem_package.rb

@@ -23,10 +23,7 @@ class Chef
     class GemPackage < Chef::Resource::Package
       resource_name :gem_package
 
-      description "Use the gem_package resource to manage gem packages that are only"\
-                  " included in recipes. 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 gem_package resource to manage gem packages that are only included in recipes. When a package is installed from a local file, it must be added to the node using the remote_file or cookbook_file resources."
 
       # the source can either be a path to a package source like:
       #   source /var/tmp/mygem-1.2.3.4.gem
@@ -39,22 +36,23 @@ class Chef
       #
       # FIXME? the array form of installing paths most likely does not work?
       #
-      property :source, [ String, Array ]
-      property :clear_sources, [ TrueClass, FalseClass ], default: lazy { Chef::Config[:clear_gem_sources] }, desired_state: false
-      # Sets a custom gem_binary to run for gem commands.
-      property :gem_binary, String, desired_state: false
-
-      # set to false to avoid including Chef::Config[:rubygems_url] in the sources
-      property :include_default_source, [ TrueClass, FalseClass ], default: true
-
-      ##
-      # Options for the gem install, either a Hash or a String. When a hash is
-      # given, the options are passed to Gem::DependencyInstaller.new, and the
-      # gem will be installed via the gems API. When a String is given, the gem
-      # will be installed by shelling out to the gem command. Using a Hash of
-      # options with an explicit gem_binary will result in undefined behavior.
-      property :options, [ String, Hash, Array, nil ], desired_state: false
+      property :source, [ String, Array ],
+               description: "Optional. The URL, or list of URLs, at which the gem package is located. This list is added to the source configured in Chef::Config[:rubygems_url] (see also include_default_source) to construct the complete list of rubygems sources. Users in an 'airgapped' environment should set Chef::Config[:rubygems_url] to their local RubyGems mirror."
 
+      property :clear_sources, [ TrueClass, FalseClass ],
+               description: "Set to 'true' to download a gem from the path specified by the source property (and not from RubyGems).",
+               default: lazy { Chef::Config[:clear_gem_sources] }, desired_state: false
+
+      property :gem_binary, String, desired_state: false,
+               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-client will be installed."
+
+      property :include_default_source, [ TrueClass, FalseClass ],
+               description: "Set to 'false' to not include 'Chef::Config[:rubygems_url]'' in the sources.",
+               default: true, introduced: "13.0"
+
+      property :options, [ String, Hash, Array, nil ],
+               description: "Options for the gem install, either a Hash or a String. When a hash is given, the options are passed to Gem::DependencyInstaller.new, and the gem will be installed via the gems API. When a String is given, the gem will be installed by shelling out to the gem command. Using a Hash of options with an explicit gem_binary will result in undefined behavior.",
+               desired_state: false
     end
   end
 end

data/lib/chef/resource/git.rb

@@ -21,11 +21,11 @@ require "chef/resource/scm"
 class Chef
   class Resource
     class Git < Chef::Resource::Scm
-      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, default: lazy { Hash.new }
+      property :additional_remotes, Hash,
+               description: "A Hash of additional remotes that are added to the git repository configuration.",
+               default: lazy { Hash.new }
 
       alias :branch :revision
       alias :reference :revision

data/lib/chef/resource/homebrew_cask.rb

@@ -32,7 +32,7 @@ class Chef
       include Chef::Mixin::HomebrewUser
 
       property :cask_name, String,
-               description: "Cask name to override the resource name.",
+               description: "The name of the Homebrew cask, if it differs from the resource block name.",
                regex: %r{^[\w/-]+$},
                name_property: true
 
@@ -40,7 +40,7 @@ class Chef
                description: "Options to pass to the brew CLI during installation."
 
       property :install_cask, [TrueClass, FalseClass],
-               description: "Auto install cask tap if necessary.",
+               description: "Automatically install the Homebrew cask tap, if necessary.",
                default: true
 
       property :homebrew_path, String,

data/lib/chef/resource/homebrew_tap.rb

@@ -41,15 +41,15 @@ class Chef
                description: "URL to the tap."
 
       property :full, [TrueClass, FalseClass],
-               description: "Perform a full clone rather than a shallow clone on the tap.",
+               description: "Perform a full clone on the tap, as opposed to a shallow clone.",
                default: false
 
       property :homebrew_path, String,
-               description: "The path to the homebrew binary.",
+               description: "The path to the Homebrew binary.",
                default: "/usr/local/bin/brew"
 
       property :owner, String,
-               description: "The owner of the homebrew installation.",
+               description: "The owner of the Homebrew installation.",
                default: lazy { find_homebrew_username }
 
       action :tap do

data/lib/chef/resource/hostname.rb

@@ -27,15 +27,15 @@ class Chef
       introduced "14.0"
 
       property :hostname, String,
-               description: "The hostname if different than the resource's name.",
+               description: "Used to specify the hostname if it is different than the resource’s name.",
                name_property: true
 
       property :compile_time, [ TrueClass, FalseClass ],
-               description: "Whether the resource runs at compile time or not.",
+               description: "Determines whether or not the resource shoul be run at compile time.",
                default: true
 
       property :ipaddress, String,
-               description: "The ip address to use when configuring the hosts file.",
+               description: "The IP address to use when configuring the hosts file.",
                default: lazy { node["ipaddress"] }
 
       property :aliases, [ Array, nil ],
@@ -43,7 +43,7 @@ class Chef
                default: nil
 
       property :windows_reboot, [ TrueClass, FalseClass ],
-               description: "Whether Windows nodes will be rebooted upon changing the name so changes can take effect.",
+               description: "Determines whether or not Windows should be reboot after changing the hostname, as this is required for the change to take effect.",
                default: true
 
       action_class do

data/lib/chef/resource/http_request.rb

@@ -25,9 +25,7 @@ class Chef
       resource_name :http_request
       provides :http_request
 
-      description "Use the http_request resource to send an HTTP request (GET, PUT,"\
-                  " POST, DELETE, HEAD, or OPTIONS) with an arbitrary message. This"\
-                  " resource is often useful when custom callbacks are necessary."
+      description "Use the http_request resource to send an HTTP request (GET, PUT, POST, DELETE, HEAD, or OPTIONS) with an arbitrary message. This resource is often useful when custom callbacks are necessary."
 
       default_action :get
       allowed_actions :get, :patch, :put, :post, :delete, :head, :options

data/lib/chef/resource/ifconfig.rb

@@ -28,7 +28,7 @@ class Chef
     class Ifconfig < Chef::Resource
       resource_name :ifconfig
 
-      description "Use the ifconfig resource to manage interfaces on *nix systems."
+      description "Use the ifconfig resource to manage interfaces on Unix and Linux systems."
 
       state_attrs :inet_addr, :mask
 

data/lib/chef/resource/locale.rb

@@ -0,0 +1,93 @@
+#
+# Copyright:: 2011-2016, Heavy Water Software Inc.
+# Copyright:: 2016-2018, Chef Software Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific slanguage governing permissions and
+# limitations under the License.
+#
+
+require "chef/resource"
+
+class Chef
+  class Resource
+    class Locale < Chef::Resource
+      preview_resource true
+      resource_name :locale
+
+      description "Use the locale resource to set the system's locale."
+      introduced "14.5"
+
+      property :lang, String,
+               default: "en_US.utf8",
+               description: "Sets the default system language."
+      property :lc_all, String,
+               default: "en_US.utf8",
+               description: "Sets the fallback system language."
+
+      action :update do
+        description "Update the system's locale."
+
+        if node["init_package"] == "systemd"
+          # on systemd settings LC_ALL is (correctly) reserved only for testing and cannot be set globally
+          execute "localectl set-locale LANG=#{new_resource.lang}" do
+            # RHEL uses /etc/locale.conf
+            not_if { up_to_date?("/etc/locale.conf", new_resource.lang) } if ::File.exist?("/etc/locale.conf")
+            # Ubuntu 16.04 still uses /etc/default/locale
+            not_if { up_to_date?("/etc/default/locale", new_resource.lang) } if ::File.exist?("/etc/default/locale")
+          end
+        elsif ::File.exist?("/etc/sysconfig/i18n")
+          locale_file_path = "/etc/sysconfig/i18n"
+
+          updated = up_to_date?(locale_file_path, new_resource.lang, new_resource.lc_all)
+
+          file locale_file_path do
+            content lazy {
+              locale = IO.read(locale_file_path)
+              variables = Hash[locale.lines.map { |line| line.strip.split("=") }]
+              variables["LANG"] = new_resource.lang
+              variables["LC_ALL"] =
+                variables.map { |pairs| pairs.join("=") }.join("\n") + "\n"
+            }
+            not_if { updated }
+          end
+
+          execute "reload root's lang profile script" do
+            command "source source /etc/sysconfig/i18n; source /etc/profile.d/lang.sh"
+            not_if { updated }
+          end
+        elsif ::File.exist?("/usr/sbin/update-locale")
+          execute "Generate locales" do
+            command "locale-gen"
+            not_if { up_to_date?("/etc/default/locale", new_resource.lang, new_resource.lc_all) }
+          end
+
+          execute "Update locale" do
+            command "update-locale LANG=#{new_resource.lang} LC_ALL=#{new_resource.lc_all}"
+            not_if { up_to_date?("/etc/default/locale", new_resource.lang, new_resource.lc_all) }
+          end
+        else
+          raise "#{node["platform"]} platform not supported by the chef locale resource."
+        end
+      end
+
+      action_class do
+        def up_to_date?(file_path, lang, lc_all = nil)
+          locale = IO.read(file_path)
+          locale.include?("LANG=#{lang}") &&
+            (node["init_package"] == "systemd" || lc_all.nil? || locale.include?("LC_ALL=#{lc_all}"))
+        rescue
+          false
+        end
+      end
+    end
+  end
+end

data/lib/chef/resource/macos_userdefaults.rb

@@ -25,9 +25,7 @@ class Chef
       provides(:mac_os_x_userdefaults) { true }
       provides(:macos_userdefaults) { true }
 
-      description "Use the macos_userdefaults resource to manage the macOS user defaults system. The properties"\
-                  " of this resource are passed to the defaults command, and the parameters follow the convention"\
-                  " of that command. See the defaults(1) man page for details on how the tool works."
+      description "Use the macos_userdefaults resource to manage the macOS user defaults system. The properties of this resource are passed to the defaults command, and the parameters follow the convention of that command. See the defaults(1) man page for details on how the tool works."
       introduced "14.0"
 
       property :domain, String,
@@ -57,8 +55,8 @@ class Chef
                default: false,
                desired_state: false
 
+      # @todo this should get refactored away: https://github.com/chef/chef/issues/7622
       property :is_set, [TrueClass, FalseClass],
-               description: "",
                default: false,
                desired_state: false
 

data/lib/chef/resource/macosx_service.rb

@@ -31,9 +31,8 @@ class Chef
 
       state_attrs :enabled, :running
 
-      # This will enable user to pass a plist in the case
-      # that the filename and label for the service dont match
-      property :plist, String
+      property :plist, String,
+               description: "A plist to use in the case where the filename and label for the service do not match."
 
       property :session_type, String
 

data/lib/chef/resource/mount.rb

@@ -29,32 +29,59 @@ class Chef
 
       # this is a poor API please do not re-use this pattern
       property :supports, Hash,
-        default: lazy { { remount: false } },
-        coerce: proc { |x| x.is_a?(Array) ? x.each_with_object({}) { |i, m| m[i] = true } : x }
+               description: "Specify a Hash of supported mount features.",
+               default: lazy { { remount: false } },
+               coerce: proc { |x| x.is_a?(Array) ? x.each_with_object({}) { |i, m| m[i] = true } : x }
 
-      property :password, String, sensitive: true
+      property :password, String,
+               description: "Windows only:. Use to specify the password for username.",
+               sensitive: true
 
-      property :mount_point, String, name_property: true
-      property :device, String, identity: true
+      property :mount_point, String, name_property: true,
+               description: "The directory (or path) in which the device is to be mounted. Defaults to the name of the resource block if not provided."
+
+      property :device, String, identity: true,
+               description: "Required for :umount and :remount actions (for the purpose of checking the mount command output for presence). The special block device or remote node, a label, or a uuid to be mounted."
 
       property :device_type, [String, Symbol],
-        coerce: proc { |arg| arg.kind_of?(String) ? arg.to_sym : arg },
-        default: :device,
-        equal_to: RUBY_PLATFORM =~ /solaris/i ? %i{ device } : %i{ device label uuid }
+               description: "The type of device: :device, :label, or :uuid",
+               coerce: proc { |arg| arg.kind_of?(String) ? arg.to_sym : arg },
+               default: :device,
+               equal_to: RUBY_PLATFORM =~ /solaris/i ? %i{ device } : %i{ device label uuid }
+
+      # @todo this should get refactored away: https://github.com/chef/chef/issues/7621
+      property :mounted, [TrueClass, FalseClass], default: false
 
-      property :fsck_device, String, default: "-"
-      property :fstype, [String, nil], default: "auto"
+      property :fsck_device, String,
+               description: "Solaris only: The fsck device.",
+               default: "-"
+
+      property :fstype, [String, nil],
+               description: "The file system type (fstype) of the device.",
+               default: "auto"
 
       property :options, [Array, String, nil],
-        coerce: proc { |arg| arg.kind_of?(String) ? arg.split(",") : arg },
-        default: %w{defaults}
+               description: "An array or comma separated list of options for the mount.",
+               coerce: proc { |arg| arg.kind_of?(String) ? arg.split(",") : arg },
+               default: %w{defaults}
 
-      property :dump, [Integer, FalseClass], default: 0
-      property :pass, [Integer, FalseClass], default: 2
-      property :mounted, [TrueClass, FalseClass], default: false
-      property :enabled, [TrueClass, FalseClass], default: false
-      property :username, String
-      property :domain, String
+      property :dump, [Integer, FalseClass],
+               description: "The dump frequency (in days) used while creating a file systems table (fstab) entry.",
+               default: 0
+
+      property :pass, [Integer, FalseClass],
+               description: "The pass number used by the file system check (fsck) command while creating a file systems table (fstab) entry.",
+               default: 2
+
+      property :enabled, [TrueClass, FalseClass],
+               description: "Use to specify if a mounted file system is enabled.",
+               default: false
+
+      property :username, String,
+               description: "Windows only: Use to specify the user name."
+
+      property :domain, String,
+               description: "Windows only: Use to specify the domain in which the username and password are located."
 
       private
 

data/lib/chef/resource/msu_package.rb

@@ -34,13 +34,16 @@ class Chef
       default_action :install
 
       property :source, String,
-                coerce: (proc do |s|
-                  unless s.nil?
-                    uri_scheme?(s) ? s : Chef::Util::PathHelper.canonical_path(s, false)
-                  end
-                end),
-                default: lazy { |r| r.package_name }
-      property :checksum, String, desired_state: false
+               description: "The local file path or URL for the MSU package.",
+               coerce: (proc do |s|
+                 unless s.nil?
+                   uri_scheme?(s) ? s : Chef::Util::PathHelper.canonical_path(s, false)
+                 end
+               end),
+               default: lazy { |r| r.package_name }
+
+      property :checksum, String, desired_state: false,
+               description: "SHA-256 digest used to verify the checksum of the downloaded MSU package."
     end
   end
 end

data/lib/chef/resource/ohai.rb

@@ -25,11 +25,9 @@ class Chef
       resource_name :ohai
       provides :ohai
 
-      description "Use the ohai resource to reload the Ohai configuration on a node."\
-                  " This allows recipes that change system attributes (like a recipe"\
-                  " that adds a user) to refer to those attributes later on during the chef-client run."
+      description "Use the ohai resource to reload the Ohai configuration on a node. This allows recipes that change system attributes (like a recipe that adds a user) to refer to those attributes later on during the chef-client run."
 
-      property :ohai_name, name_property: true
+      property :ohai_name, name_property: true, introduced: "12.17"
       property :plugin, String
 
       default_action :reload

data/lib/chef/resource/ohai_hint.rb

@@ -23,18 +23,18 @@ class Chef
       resource_name :ohai_hint
       provides(:ohai_hint) { true }
 
-      description "Use the ohai_hint resource to pass hint data to Ohai to aid in configuration detection."
+      description "Use the ohai_hint resource to aid in configuration detection by passing hint data to Ohai."
       introduced "14.0"
 
       property :hint_name, String,
-               description: "The name of hints file if different from the resource name.",
+               description: "The name of the hints file, if it differs from the resource name.",
                name_property: true
 
       property :content, Hash,
                description: "Values to include in the hint file."
 
       property :compile_time, [TrueClass, FalseClass],
-               description: "Whether the resource will execute during the compile time phase or not.",
+               description: "Determines whether or not the resource is executed during the compile time phase.",
                default: true, desired_state: false
 
       action :create do