chef 16.1.16 → 16.18.30

data/lib/chef/resource/execute.rb

@@ -18,7 +18,7 @@
 #
 
 require_relative "../resource"
-require_relative "../dist"
+require "chef-utils/dist" unless defined?(ChefUtils::Dist)
 
 class Chef
   class Resource
@@ -27,10 +27,476 @@ class Chef
 
       provides :execute, target_mode: true
 
-      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."
+      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. Note: Use the **script** resource to execute a script using a specific interpreter (Ruby, Python, Perl, csh, or Bash)."
+
+      examples <<~EXAMPLES
+        **Run a command upon notification**:
+
+        ```ruby
+        execute 'slapadd' do
+          command 'slapadd < /tmp/something.ldif'
+          creates '/var/lib/slapd/uid.bdb'
+
+          action :nothing
+        end
+
+        template '/tmp/something.ldif' do
+          source 'something.ldif'
+
+          notifies :run, 'execute[slapadd]', :immediately
+        end
+        ```
+
+        **Run a touch file only once while running a command**:
+
+        ```ruby
+        execute 'upgrade script' do
+          command 'php upgrade-application.php && touch /var/application/.upgraded'
+
+          creates '/var/application/.upgraded'
+          action :run
+        end
+        ```
+
+        **Run a command which requires an environment variable**:
+
+        ```ruby
+        execute 'slapadd' do
+          command 'slapadd < /tmp/something.ldif'
+          creates '/var/lib/slapd/uid.bdb'
+
+          action :run
+          environment ({'HOME' => '/home/my_home'})
+        end
+        ```
+
+        **Delete a repository using yum to scrub the cache**:
+
+        ```ruby
+        # the following code sample thanks to gaffneyc @ https://gist.github.com/918711
+        execute 'clean-yum-cache' do
+          command 'yum clean all'
+          action :nothing
+        end
+
+        file '/etc/yum.repos.d/bad.repo' do
+          action :delete
+          notifies :run, 'execute[clean-yum-cache]', :immediately
+        end
+        ```
+
+        **Prevent restart and reconfigure if configuration is broken**:
+
+        Use the `:nothing` action (common to all resources) to prevent the test from
+        starting automatically, and then use the `subscribes` notification to run a
+        configuration test when a change to the template is detected.
+
+        ```ruby
+        execute 'test-nagios-config' do
+          command 'nagios3 --verify-config'
+          action :nothing
+          subscribes :run, 'template[/etc/nagios3/configures-nagios.conf]', :immediately
+        end
+        ```
+
+        **Notify in a specific order**:
+
+        To notify multiple resources, and then have these resources run in a certain
+        order, do something like the following.
+
+        ```ruby
+        execute 'foo' do
+          command '...'
+          notifies :create, 'template[baz]', :immediately
+          notifies :install, 'package[bar]', :immediately
+          notifies :run, 'execute[final]', :immediately
+        end
+
+        template 'baz' do
+          #...
+          notifies :run, 'execute[restart_baz]', :immediately
+        end
+
+        package 'bar'
+          execute 'restart_baz'
+          execute 'final' do
+          command '...'
+        end
+        ```
+
+        where the sequencing will be in the same order as the resources are listed in
+        the recipe: `execute 'foo'`, `template 'baz'`, `execute [restart_baz]`,
+        `package 'bar'`, and `execute 'final'`.
+
+        **Execute a command using a template**:
+
+        The following example shows how to set up IPv4 packet forwarding using the
+        **execute** resource to run a command named `forward_ipv4` that uses a template
+        defined by the **template** resource.
+
+        ```ruby
+        execute 'forward_ipv4' do
+          command 'echo > /proc/.../ipv4/ip_forward'
+          action :nothing
+        end
+
+        template '/etc/file_name.conf' do
+          source 'routing/file_name.conf.erb'
+
+         notifies :run, 'execute[forward_ipv4]', :delayed
+        end
+        ```
+
+        where the `command` property for the **execute** resource contains the command
+        that is to be run and the `source` property for the **template** resource
+        specifies which template to use. The `notifies` property for the **template**
+        specifies that the `execute[forward_ipv4]` (which is defined by the **execute**
+        resource) should be queued up and run at the end of a Chef Infra Client run.
+
+        **Add a rule to an IP table**:
+
+        The following example shows how to add a rule named `test_rule` to an IP table
+        using the **execute** resource to run a command using a template that is defined
+        by the **template** resource:
+
+        ```ruby
+        execute 'test_rule' do
+          command "command_to_run
+            --option value
+            --option value
+            --source \#{node[:name_of_node][:ipsec][:local][:subnet]}
+            -j test_rule"
+
+          action :nothing
+        end
+
+        template '/etc/file_name.local' do
+          source 'routing/file_name.local.erb'
+          notifies :run, 'execute[test_rule]', :delayed
+        end
+        ```
+
+        where the `command` property for the **execute** resource contains the command
+        that is to be run and the `source` property for the **template** resource
+        specifies which template to use. The `notifies` property for the **template**
+        specifies that the `execute[test_rule]` (which is defined by the **execute**
+        resource) should be queued up and run at the end of a Chef Infra Client run.
+
+        **Stop a service, do stuff, and then restart it**:
+
+        The following example shows how to use the **execute**, **service**, and
+        **mount** resources together to ensure that a node running on Amazon EC2 is
+        running MySQL. This example does the following:
+
+        - Checks to see if the Amazon EC2 node has MySQL
+        - If the node has MySQL, stops MySQL
+        - Installs MySQL
+        - Mounts the node
+        - Restarts MySQL
+
+        ```ruby
+        # the following code sample comes from the ``server_ec2``
+        # recipe in the following cookbook:
+        # https://github.com/chef-cookbooks/mysql
+
+        if (node.attribute?('ec2') && !FileTest.directory?(node['mysql']['ec2_path']))
+          service 'mysql' do
+            action :stop
+          end
+
+          execute 'install-mysql' do
+            command "mv \#{node['mysql']['data_dir']} \#{node['mysql']['ec2_path']}"
+            not_if { ::File.directory?(node['mysql']['ec2_path']) }
+          end
+
+          [node['mysql']['ec2_path'], node['mysql']['data_dir']].each do |dir|
+            directory dir do
+              owner 'mysql'
+              group 'mysql'
+            end
+          end
+
+          mount node['mysql']['data_dir'] do
+            device node['mysql']['ec2_path']
+            fstype 'none'
+            options 'bind,rw'
+            action [:mount, :enable]
+          end
+
+          service 'mysql' do
+            action :start
+          end
+        end
+        ```
+
+        where
+
+        - the two **service** resources are used to stop, and then restart the MySQL service
+        - the **execute** resource is used to install MySQL
+        - the **mount** resource is used to mount the node and enable MySQL
+
+        **Use the platform_family? method**:
+
+        The following is an example of using the `platform_family?` method in the Recipe
+        DSL to create a variable that can be used with other resources in the same
+        recipe. In this example, `platform_family?` is being used to ensure that a
+        specific binary is used for a specific platform before using the **remote_file**
+        resource to download a file from a remote location, and then using the
+        **execute** resource to install that file by running a command.
+
+        ```ruby
+        if platform_family?('rhel')
+          pip_binary = '/usr/bin/pip'
+        else
+          pip_binary = '/usr/local/bin/pip'
+        end
+
+        remote_file "\#{Chef::Config[:file_cache_path]}/distribute_setup.py" do
+          source 'http://python-distribute.org/distribute_setup.py'
+          mode '0755'
+          not_if { ::File.exist?(pip_binary) }
+        end
+
+        execute 'install-pip' do
+          cwd Chef::Config[:file_cache_path]
+          command <<~EOF
+            # command for installing Python goes here
+          EOF
+          not_if { ::File.exist?(pip_binary) }
+        end
+        ```
+
+        where a command for installing Python might look something like:
+
+        ```ruby
+        \#{node['python']['binary']} distribute_setup.py \#{::File.dirname(pip_binary)}/easy_install pip
+        ```
+
+        **Control a service using the execute resource**:
+
+        <div class="admonition-warning">
+          <p class="admonition-warning-title">Warning</p>
+          <div class="admonition-warning-text">
+            This is an example of something that should NOT be done. Use the **service**
+            resource to control a service, not the **execute** resource.
+          </div>
+        </div>
+
+        Do something like this:
+
+        ```ruby
+        service 'tomcat' do
+          action :start
+        end
+        ```
+
+        and NOT something like this:
+
+        ```ruby
+        execute 'start-tomcat' do
+          command '/etc/init.d/tomcat start'
+          action :run
+        end
+        ```
+
+        There is no reason to use the **execute** resource to control a service because
+        the **service** resource exposes the `start_command` property directly, which
+        gives a recipe full control over the command issued in a much cleaner, more
+        direct manner.
+
+        **Use the search recipe DSL method to find users**:
+
+        The following example shows how to use the `search` method in the Recipe DSL to
+        search for users:
+
+        ```ruby
+        #  the following code sample comes from the openvpn cookbook:
+
+        search("users", "*:*") do |u|
+          execute "generate-openvpn-\#{u['id']}" do
+            command "./pkitool \#{u['id']}"
+            cwd '/etc/openvpn/easy-rsa'
+          end
+
+          %w{ conf ovpn }.each do |ext|
+            template "\#{node['openvpn']['key_dir']}/\#{u['id']}.\#{ext}" do
+              source 'client.conf.erb'
+              variables :username => u['id']
+            end
+          end
+        end
+        ```
+
+        where
+
+        - the search data will be used to create **execute** resources
+        - the **template** resource tells Chef Infra Client which template to use
+
+        **Enable remote login for macOS**:
+
+        ```ruby
+        execute 'enable ssh' do
+          command '/usr/sbin/systemsetup -setremotelogin on'
+          not_if '/usr/sbin/systemsetup -getremotelogin | /usr/bin/grep On'
+          action :run
+        end
+        ```
+
+        **Execute code immediately, based on the template resource**:
+
+        By default, notifications are `:delayed`, that is they are queued up as they are
+        triggered, and then executed at the very end of a Chef Infra Client run. To run
+        kan action immediately, use `:immediately`:
+
+        ```ruby
+        template '/etc/nagios3/configures-nagios.conf' do
+          # other parameters
+          notifies :run, 'execute[test-nagios-config]', :immediately
+        end
+        ```
+
+        and then Chef Infra Client would immediately run the following:
+
+        ```ruby
+        execute 'test-nagios-config' do
+          command 'nagios3 --verify-config'
+          action :nothing
+        end
+        ```
+
+        **Sourcing a file**:
+
+        The **execute** resource cannot be used to source a file (e.g. `command 'source
+        filename'`). The following example will fail because `source` is not an
+        executable:
+
+        ```ruby
+        execute 'foo' do
+          command 'source /tmp/foo.sh'
+        end
+        ```
+
+
+        Instead, use the **script** resource or one of the **script**-based resources
+        (**bash**, **csh**, **perl**, **python**, or **ruby**). For example:
+
+        ```ruby
+        bash 'foo' do
+          code 'source /tmp/foo.sh'
+        end
+        ```
+
+        **Run a Knife command**:
+
+        ```ruby
+        execute 'create_user' do
+          command <<~EOM
+            knife user create \#{user}
+              --admin
+              --password password
+              --disable-editing
+              --file /home/vagrant/.chef/user.pem
+              --config /tmp/knife-admin.rb
+            EOM
+        end
+        ```
+
+        **Run install command into virtual environment**:
+
+        The following example shows how to install a lightweight JavaScript framework
+        into Vagrant:
+
+        ```ruby
+        execute "install q and zombiejs" do
+          cwd "/home/vagrant"
+          user "vagrant"
+          environment ({'HOME' => '/home/vagrant', 'USER' => 'vagrant'})
+          command "npm install -g q zombie should mocha coffee-script"
+          action :run
+        end
+        ```
+
+        **Run a command as a named user**:
+
+        The following example shows how to run `bundle install` from a Chef Infra Client
+        run as a specific user. This will put the gem into the path of the user
+        (`vagrant`) instead of the root user (under which the Chef Infra Client runs):
+
+        ```ruby
+        execute '/opt/chefdk/embedded/bin/bundle install' do
+          cwd node['chef_workstation']['bundler_path']
+          user node['chef_workstation']['user']
+
+          environment ({
+            'HOME' => "/home/\#{node['chef_workstation']['user']}",
+            'USER' => node['chef_workstation']['user']
+          })
+          not_if 'bundle check'
+        end
+        ```
+
+        **Run a command as an alternate user**:
+
+        *Note*: When Chef is running as a service, this feature requires that the user
+        that Chef runs as has 'SeAssignPrimaryTokenPrivilege' (aka
+        'SE_ASSIGNPRIMARYTOKEN_NAME') user right. By default only LocalSystem and
+        NetworkService have this right when running as a service. This is necessary
+        even if the user is an Administrator.
+
+        This right can be added and checked in a recipe using this example:
+
+        ```ruby
+        # Add 'SeAssignPrimaryTokenPrivilege' for the user
+        Chef::ReservedNames::Win32::Security.add_account_right('<user>', 'SeAssignPrimaryTokenPrivilege')
+
+        # Check if the user has 'SeAssignPrimaryTokenPrivilege' rights
+        Chef::ReservedNames::Win32::Security.get_account_right('<user>').include?('SeAssignPrimaryTokenPrivilege')
+        ```
+
+        The following example shows how to run `mkdir test_dir` from a Chef Infra Client
+        run as an alternate user.
+
+        ```ruby
+        # Passing only username and password
+        execute 'mkdir test_dir' do
+          cwd Chef::Config[:file_cache_path]
+
+          user "username"
+          password "password"
+        end
+
+        # Passing username and domain
+        execute 'mkdir test_dir' do
+          cwd Chef::Config[:file_cache_path]
+
+          domain "domain-name"
+          user "user"
+          password "password"
+        end
+
+        # Passing username = 'domain-name\\username'. No domain is passed
+        execute 'mkdir test_dir' do
+          cwd Chef::Config[:file_cache_path]
+
+          user "domain-name\\username"
+          password "password"
+        end
+
+        # Passing username = 'username@domain-name'.  No domain is passed
+        execute 'mkdir test_dir' do
+          cwd Chef::Config[:file_cache_path]
+
+          user "username@domain-name"
+          password "password"
+        end
+        ```
+
+        **Run a command with an external input file**:
+
+        execute 'md5sum' do
+          input File.read(__FILE__)
+        end
+      EXAMPLES
 
       # 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
@@ -43,7 +509,6 @@ class Chef
       def initialize(name, run_context = nil)
         super
         @command = name
-        @backup = 5
         @default_guard_interpreter = :execute
         @is_guard_interpreter = false
       end
@@ -62,13 +527,13 @@ class Chef
         description: "The current working directory from which the command will be run."
 
       property :environment, Hash,
-        description: "A Hash of environment variables in the form of ({'ENV_VARIABLE' => 'VALUE'})."
+        description: "A Hash of environment variables in the form of `({'ENV_VARIABLE' => 'VALUE'})`. **Note**: These variables must exist for a command to be run successfully."
 
       property :group, [ String, Integer ],
         description: "The group name or group ID that must be changed before running a command."
 
       property :live_stream, [ TrueClass, FalseClass ], default: false,
-        description: "Send the output of the command run by this execute resource block to the #{Chef::Dist::CLIENT} event stream."
+        description: "Send the output of the command run by this execute resource block to the #{ChefUtils::Dist::Infra::PRODUCT} event stream."
 
       # 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,
@@ -84,11 +549,11 @@ class Chef
         desired_state: false
 
       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 specified 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."
+        description: "The user name of the user identity with which to launch the new process. The user name may optionally be specified 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 :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::Dist::PRODUCT} 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."
+        description: "Windows only: The domain of the user user specified by the user property. If not specified, the username and password specified by the `user` and `password` properties will be used to resolve that user against the domain in which the system running #{ChefUtils::Dist::Infra::PRODUCT} 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 :password, String, sensitive: true,
         introduced: "12.21",
@@ -96,13 +561,17 @@ class Chef
 
       # 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::Dist::CLIENT}.",
+        description: "Ensure that sensitive resource data is not logged by the #{ChefUtils::Dist::Infra::PRODUCT}.",
         default: lazy { password ? true : false }, default_description: "True if the password property is set. False otherwise."
 
       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::Dist::CLIENT} 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.",
+        description: "Determines whether the script will run with elevated permissions to circumvent User Access Control (UAC) from interactively blocking the process.\nThis will cause the process to be run under a batch login instead of an interactive login. The user running #{ChefUtils::Dist::Infra::CLIENT} 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"
 
+      property :input, [String],
+        introduced: "16.2",
+        description: "An optional property to set the input sent to the command as STDIN."
+
       alias :env :environment
 
       def self.set_guard_inherited_attributes(*inherited_attributes)
@@ -118,7 +587,7 @@ class Chef
           ancestor_attributes = superclass.guard_inherited_attributes
         end
 
-        ancestor_attributes.concat(@class_inherited_attributes ? @class_inherited_attributes : []).uniq
+        ancestor_attributes.concat(@class_inherited_attributes || []).uniq
       end
 
       # post resource creation validation
@@ -160,11 +629,11 @@ class Chef
         end
 
         # if domain is provided in both username and domain
-        if specified_user && ((specified_user.include? '\\') || (specified_user.include? "@")) && specified_domain
+        if specified_user.is_a?(String) && ((specified_user.include? '\\') || (specified_user.include? "@")) && specified_domain
           raise ArgumentError, "The domain is provided twice. Username: `#{specified_user}`, Domain: `#{specified_domain}`. Please specify domain only once."
         end
 
-        if ! specified_user.nil? && specified_domain.nil?
+        if specified_user.is_a?(String) && specified_domain.nil?
           # Splitting username of format: Domain\Username
           domain_and_user = user.split('\\')
 
@@ -192,8 +661,10 @@ class Chef
 
       set_guard_inherited_attributes(
         :cwd,
+        :domain,
         :environment,
         :group,
+        :password,
         :user,
         :umask
       )

data/lib/chef/resource/file.rb

@@ -22,7 +22,7 @@ require_relative "../platform/query_helpers"
 require_relative "../mixin/securable"
 require_relative "file/verification"
 require "pathname" unless defined?(Pathname)
-require_relative "../dist"
+require "chef-utils" unless defined?(ChefUtils::CANARY)
 
 class Chef
   class Resource
@@ -32,7 +32,7 @@ class Chef
 
       provides :file
 
-      description "Use the **file** resource to manage files directly on a node."
+      description "Use the **file** resource to manage files directly on a node. Note: Use the **cookbook_file** resource to copy a file from a cookbook's `/files` directory. Use the **template** resource to create a file based on a template in a cookbook's `/templates` directory. And use the **remote_file** resource to transfer a file to a node from a remote location."
 
       if ChefUtils.windows?
         # Use Windows rights instead of standard *nix permissions
@@ -56,7 +56,7 @@ class Chef
       allowed_actions :create, :delete, :touch, :create_if_missing
 
       property :path, String, name_property: 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::Dist::CLIENT} process. This path can vary from system to system. Therefore, using a path that begins with a forward slash (/) is not recommended."
+        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 #{ChefUtils::Dist::Infra::PRODUCT} 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 { docker? && special_docker_files?(path) ? false : Chef::Config[:file_atomic_update] },
         default_description: "False if modifying /etc/hosts, /etc/hostname, or /etc/resolv.conf within Docker containers. Otherwise default to the client.rb 'file_atomic_update' config value.",
@@ -76,10 +76,10 @@ class Chef
       property :diff, [ String, nil ], desired_state: false, skip_docs: true
 
       property :force_unlink, [ TrueClass, FalseClass ], desired_state: false, default: false,
-        description: "How #{Chef::Dist::PRODUCT} 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 #{Chef::Dist::PRODUCT} to delete the non-file target and replace it with the specified file. Set to false for #{Chef::Dist::PRODUCT} to raise an error."
+        description: "How #{ChefUtils::Dist::Infra::PRODUCT} 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 #{ChefUtils::Dist::Infra::PRODUCT} to delete the non-file target and replace it with the specified file. Set to `false` for #{ChefUtils::Dist::Infra::PRODUCT} 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, #{Chef::Dist::PRODUCT} 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::Dist::PRODUCT} 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."
+        description: "Change the behavior of the file resource if it is pointed at a symlink. When this value is set to true, #{ChefUtils::Dist::Infra::PRODUCT} 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, #{ChefUtils::Dist::Infra::PRODUCT} 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 { [] }
 

data/lib/chef/resource/freebsd_package.rb

@@ -42,7 +42,7 @@ class Chef
       private
 
       def assign_provider
-        @provider = if source.to_s =~ /^ports$/i
+        @provider = if /^ports$/i.match?(source.to_s)
                       Chef::Provider::Package::Freebsd::Port
                     else
                       Chef::Provider::Package::Freebsd::Pkgng