chef 12.19.36 → 14.14.25

data/lib/chef/resource/execute.rb

@@ -1,7 +1,7 @@
 #
 # Author:: Adam Jacob (<adam@chef.io>)
 # Author:: Tyler Cloke (<tyler@chef.io>)
-# Copyright:: Copyright 2008-2016, Chef Software Inc.
+# Copyright:: Copyright 2008-2018, Chef Software Inc.
 # License:: Apache License, Version 2.0
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -18,14 +18,20 @@
 #
 
 require "chef/resource"
-require "chef/provider/execute"
 
 class Chef
   class Resource
     class Execute < Chef::Resource
+      resource_name :execute
+      provides :execute
 
       identity_attr :command
 
+      description "Use the execute resource to execute a single command. 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."
+
       # The ResourceGuardInterpreter wraps a resource's guards in another resource.  That inner resource
       # needs to behave differently during (for example) why_run mode, so we flag it here. For why_run mode
       # we still want to execute the guard resource even if we are not executing the wrapping resource.
@@ -38,116 +44,67 @@ class Chef
         super
         @command = name
         @backup = 5
-        @creates = nil
-        @cwd = nil
-        @environment = nil
-        @group = nil
-        @path = nil
-        @returns = 0
-        @timeout = nil
-        @user = nil
-        @umask = nil
         @default_guard_interpreter = :execute
         @is_guard_interpreter = false
-        @live_stream = false
-      end
-
-      def umask(arg = nil)
-        set_or_return(
-          :umask,
-          arg,
-          :kind_of => [ String, Integer ]
-        )
       end
 
       def command(arg = nil)
         set_or_return(
           :command,
           arg,
-          :kind_of => [ String, Array ]
+          kind_of: [ String, Array ]
         )
       end
+      property :umask, [ String, Integer ],
+               description: "The file mode creation mask, or umask."
 
-      def creates(arg = nil)
-        set_or_return(
-          :creates,
-          arg,
-          :kind_of => [ String ]
-        )
-      end
+      property :creates, String,
+               description: "Prevent a command from creating a file when that file already exists."
 
-      def cwd(arg = nil)
-        set_or_return(
-          :cwd,
-          arg,
-          :kind_of => [ String ]
-        )
-      end
+      property :cwd, String,
+               description: "The current working directory from which the command will be run."
 
-      def environment(arg = nil)
-        set_or_return(
-          :environment,
-          arg,
-          :kind_of => [ Hash ]
-        )
-      end
+      property :environment, Hash,
+               description: "A Hash of environment variables in the form of ({'ENV_VARIABLE' => 'VALUE'})."
 
       alias :env :environment
 
-      def group(arg = nil)
-        set_or_return(
-          :group,
-          arg,
-          :kind_of => [ String, Integer ]
-        )
-      end
+      property :group, [ String, Integer ],
+               description: "The group name or group ID that must be changed before running a command."
 
-      def live_stream(arg = nil)
-        set_or_return(
-          :live_stream,
-          arg,
-          :kind_of => [ TrueClass, FalseClass ])
-      end
+      property :live_stream, [ TrueClass, FalseClass ], default: false,
+               description: "Send the output of the command run by this execute resource block to the chef-client event stream."
 
-      def path(arg = nil)
-        Chef::Log.warn "The 'path' attribute of 'execute' is not used by any provider in Chef 11 or Chef 12. Use 'environment' attribute to configure 'PATH'. This attribute will be removed in Chef 13."
+      # default_env defaults to `false` so that the command execution more exactly matches what the user gets on the command line without magic
+      property :default_env, [ TrueClass, FalseClass ], desired_state: false, default: false,
+               introduced: "14.2",
+               description: "When true this enables ENV magic to add path_sanity to the PATH and force the locale to English+UTF-8 for parsing output"
 
-        set_or_return(
-          :path,
-          arg,
-          :kind_of => [ Array ]
-        )
-      end
+      property :returns, [ Integer, Array ], default: 0,
+               description: "The return value for a command. This may be an array of accepted values. An exception is raised when the return value(s) do not match."
 
-      def returns(arg = nil)
-        set_or_return(
-          :returns,
-          arg,
-          :kind_of => [ Integer, Array ]
-        )
-      end
+      property :timeout, [ Integer, Float ],
+               description: "The amount of time (in seconds) a command is to wait before timing out."
 
-      def timeout(arg = nil)
-        set_or_return(
-          :timeout,
-          arg,
-          :kind_of => [ Integer, Float ]
-        )
-      end
+      property :user, [ String, Integer ],
+               description: "The user name of the user identity with which to launch the new process. The user name may optionally be specifed with a domain, i.e. domainuser or user@my.dns.domain.com via Universal Principal Name (UPN)format. It can also be specified without a domain simply as user if the domain is instead specified using the domain property. On Windows only, if this property is specified, the password property must be specified."
 
-      property :user, [ String, Integer ]
+      property :domain, String,
+               introduced: "12.21",
+               description: "Windows only: The domain of the user user specified by the user property. If not specified, the user name and password specified by the user and password properties will be used to resolve that user against the domain in which the system running Chef client is joined, or if that system is not joined to a domain it will resolve the user as a local account on that system. An alternative way to specify the domain is to leave this property unspecified and specify the domain as part of the user property."
 
-      property :domain, String
+      property :password, String, sensitive: true,
+               introduced: "12.21",
+               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."
 
-      property :password, String, sensitive: true
+      # lazy used to set default value of sensitive to true if password is set
+      property :sensitive, [ TrueClass, FalseClass ],
+               description: "Ensure that sensitive resource data is not logged by the chef-client.",
+               default: lazy { |r| r.password ? true : false }, default_description: "True if the password property is set. False otherwise."
 
-      def sensitive(args = nil)
-        if password
-          true
-        else
-          super
-        end
-      end
+      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)
         @class_inherited_attributes = inherited_attributes
@@ -166,21 +123,29 @@ class Chef
       end
 
       def after_created
-        validate_identity_platform(user, password, domain)
+        validate_identity_platform(user, password, domain, elevated)
         identity = qualify_user(user, password, domain)
         domain(identity[:domain])
         user(identity[:user])
       end
 
-      def validate_identity_platform(specified_user, password = nil, specified_domain = nil)
+      def validate_identity_platform(specified_user, password = nil, specified_domain = nil, elevated = false)
         if node[:platform_family] == "windows"
           if specified_user && password.nil?
             raise ArgumentError, "A value for `password` must be specified when a value for `user` is specified on the Windows platform"
           end
+
+          if elevated && !specified_user && !password
+            raise ArgumentError, "`elevated` option should be passed only with `username` and `password`."
+          end
         else
           if password || specified_domain
             raise Exceptions::UnsupportedPlatform, "Values for `domain` and `password` are only supported on the Windows platform"
           end
+
+          if elevated
+            raise Exceptions::UnsupportedPlatform, "Value for `elevated` is only supported on the Windows platform"
+          end
         end
       end
 

data/lib/chef/resource/file.rb

@@ -1,7 +1,7 @@
 #
 # Author:: Adam Jacob (<adam@chef.io>)
 # Author:: Seth Chisamore (<schisamo@chef.io>)
-# Copyright:: Copyright 2008-2016 Chef Software, Inc.
+# Copyright:: Copyright 2008-2018, Chef Software Inc.
 # License:: Apache License, Version 2.0
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -28,6 +28,8 @@ class Chef
     class File < Chef::Resource
       include Chef::Mixin::Securable
 
+      description "Use the file resource to manage files directly on a node."
+
       if Platform.windows?
         # Use Windows rights instead of standard *nix permissions
         state_attrs :checksum, :rights, :deny_rights
@@ -43,20 +45,35 @@ class Chef
       # mutate the new_resource.checksum which would change the
       # user intent in the new_resource if the resource is reused.
       #
-      # @returns [String] Checksum of the file we actually rendered
+      # @return [String] Checksum of the file we actually rendered
       attr_accessor :final_checksum
 
       default_action :create
       allowed_actions :create, :delete, :touch, :create_if_missing
 
-      property :path, String, name_property: true, identity: true
-      property :atomic_update, [ true, false ], desired_state: false, default: lazy { |r| r.docker? && r.special_docker_files?(r.path) ? false : Chef::Config[:file_atomic_update] }
-      property :backup, [ Integer, false ], desired_state: false, default: 5
-      property :checksum, [ /^[a-zA-Z0-9]{64}$/, nil ]
-      property :content, [ String, nil ], desired_state: false
-      property :diff, [ String, nil ], desired_state: false
-      property :force_unlink, [ true, false ], desired_state: false, default: false
-      property :manage_symlink_source, [ true, false ], desired_state: false
+      property :path, String, name_property: true, identity: true,
+               description: "The full path to the file, including the file name and its extension. For example: /files/file.txt. Default value: the name of the resource block. Microsoft Windows: A path that begins with a forward slash (/) will point to the root of the current working directory of the chef-client process. This path can vary from system to system. Therefore, using a path that begins with a forward slash (/) is not recommended."
+
+      property :atomic_update, [ TrueClass, FalseClass ], desired_state: false, default: lazy { |r| r.docker? && r.special_docker_files?(r.path) ? false : Chef::Config[:file_atomic_update] },
+               description: "Perform atomic file updates on a per-resource basis. Set to true for atomic file updates. Set to false for non-atomic file updates. This setting overrides file_atomic_update, which is a global setting found in the client.rb file."
+
+      property :backup, [ Integer, FalseClass ], desired_state: false, default: 5,
+               description: "The number of backups to be kept in /var/chef/backup (for UNIX- and Linux-based platforms) or C:/chef/backup (for the Microsoft Windows platform). Set to false to prevent backups from being kept."
+
+      property :checksum, [ /^[a-zA-Z0-9]{64}$/, nil ],
+               description: "The SHA-256 checksum of the file. Use to ensure that a specific file is used. If the checksum does not match, the file is not used."
+
+      property :content, [ String, nil ], desired_state: false,
+               description: "A string that is written to the file. The contents of this property replace any previous content when this property has something other than the default value. The default behavior will not modify content."
+
+      property :diff, [ String, nil ], desired_state: false, skip_docs: true
+
+      property :force_unlink, [ TrueClass, FalseClass ], desired_state: false, default: false,
+               description: "How the chef-client handles certain situations when the target file turns out not to be a file. For example, when a target file is actually a symlink. Set to true for the chef-client delete the non-file target and replace it with the specified file. Set to false for the chef-client to raise an error."
+
+      property :manage_symlink_source, [ TrueClass, FalseClass ], desired_state: false,
+               description: "Change the behavior of the file resource if it is pointed at a symlink. When this value is set to true, the Chef client will manage the symlink's permissions or will replace the symlink with a normal file if the resource has content. When this value is set to false, Chef will follow the symlink and will manage the permissions and content of symlink's target file. The default behavior is true but emits a warning that the default value will be changed to false in a future version; setting this explicitly to true or false suppresses this warning."
+
       property :verifications, Array, default: lazy { [] }
 
       def verify(command = nil, opts = {}, &block)

data/lib/chef/resource/file/verification.rb

@@ -80,6 +80,10 @@ class Chef
           c
         end
 
+        def logger
+          @parent_resource.logger
+        end
+
         def initialize(parent_resource, command, opts, &block)
           @command, @command_opts = command, opts
           @block = block
@@ -87,7 +91,7 @@ class Chef
         end
 
         def verify(path, opts = {})
-          Chef::Log.debug("Running verification[#{self}] on #{path}")
+          logger.trace("Running verification[#{self}] on #{path}")
           if @block
             verify_block(path, opts)
           elsif @command.is_a?(Symbol)
@@ -106,15 +110,10 @@ class Chef
         # We reuse Chef::GuardInterpreter in order to support
         # the same set of options that the not_if/only_if blocks do
         def verify_command(path, opts)
-          # First implementation interpolated `file`; docs & RFC claim `path`
-          # is interpolated. Until `file` can be deprecated, interpolate both.
           if @command.include?("%{file}")
-            Chef.deprecated(:verify_file,
-              "%{file} is deprecated in verify command and will not be "\
-              "supported in Chef 13. Please use %{path} instead."
-            )
+            raise ArgumentError, "The %{file} expansion for verify commands has been removed. Please use %{path} instead."
           end
-          command = @command % { :file => path, :path => path }
+          command = @command % { path: path }
           interpreter = Chef::GuardInterpreter.for_resource(@parent_resource, command, @command_opts)
           interpreter.evaluate
         end
@@ -124,6 +123,16 @@ class Chef
           v = verification_class.new(@parent_resource, @command, @command_opts, &@block)
           v.verify(path, opts)
         end
+
+        def to_s
+          if @block
+            "<Proc>"
+          elsif @command.is_a?(Symbol)
+            "#{@command.inspect} (#{Chef::Resource::File::Verification.lookup(@command).name})"
+          elsif @command.is_a?(String)
+            @command
+          end
+        end
       end
     end
   end

data/lib/chef/resource/freebsd_package.rb

@@ -32,19 +32,28 @@ class Chef
       resource_name :freebsd_package
       provides :package, platform: "freebsd"
 
+      description "Use the freebsd_package resource to manage packages for the FreeBSD platform."
+
+      # make sure we assign the appropriate underlying providers based on what
+      # package managers exist on this FreeBSD system or the source of the package
+      #
+      # @return [void]
       def after_created
         assign_provider
       end
 
+      # Is the system at least version 1000017 or is the make variable WITH_PKGNG set
+      #
+      # @return [Boolean] do we support pkgng
       def supports_pkgng?
-        ships_with_pkgng? || !!shell_out_compact!("make", "-V", "WITH_PKGNG", :env => nil).stdout.match(/yes/i)
+        ships_with_pkgng? || !!shell_out!("make", "-V", "WITH_PKGNG", env: nil).stdout.match(/yes/i)
       end
 
       private
 
+      # It was not until __FreeBSD_version 1000017 that pkgng became
+      # the default binary package manager. See '/usr/ports/Mk/bsd.port.mk'.
       def ships_with_pkgng?
-        # It was not until __FreeBSD_version 1000017 that pkgng became
-        # the default binary package manager. See '/usr/ports/Mk/bsd.port.mk'.
         node[:os_version].to_i >= 1000017
       end
 
@@ -54,6 +63,8 @@ class Chef
                     elsif supports_pkgng?
                       Chef::Provider::Package::Freebsd::Pkgng
                     else
+                      Chef.deprecated(:freebsd_package_provider, "The freebsd_package provider for pkg (Chef::Provider::Package::Freebsd::Pkg) is deprecated and will be removed from Chef core in 15.0 (April 2019).")
+
                       Chef::Provider::Package::Freebsd::Pkg
                     end
       end

data/lib/chef/resource/gem_package.rb

@@ -1,6 +1,6 @@
 #
 # Author:: Adam Jacob (<adam@chef.io>)
-# Copyright:: Copyright 2008-2016, Chef Software Inc.
+# Copyright:: Copyright 2008-2017, Chef Software Inc.
 # License:: Apache License, Version 2.0
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -23,19 +23,36 @@ class Chef
     class GemPackage < Chef::Resource::Package
       resource_name :gem_package
 
-      property :source, [ String, Array ]
-      property :clear_sources, [ true, false ], default: false, desired_state: false
-      # Sets a custom gem_binary to run for gem commands.
-      property :gem_binary, String, desired_state: false
+      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."
 
-      ##
-      # 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
+      # the source can either be a path to a package source like:
+      #   source /var/tmp/mygem-1.2.3.4.gem
+      # or it can be a url rubygems source like:
+      #   https://www.rubygems.org
+      # the default has to be nil in order for the magical wiring up of the name property to
+      # the source pathname to work correctly.
+      #
+      # we don't do coercions here because its all a bit too complicated
+      #
+      # FIXME? the array form of installing paths most likely does not work?
+      #
+      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,23 +21,14 @@ 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."
 
-      def initialize(name, run_context = nil)
-        super
-        @additional_remotes = Hash[]
-      end
-
-      def additional_remotes(arg = nil)
-        set_or_return(
-          :additional_remotes,
-          arg,
-          :kind_of => Hash
-        )
-      end
+      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
-
       alias :repo :repository
     end
   end