chef 16.0.287-universal-mingw32 → 16.2.73-universal-mingw32

data/lib/chef/resource/chef_vault_secret.rb

@@ -45,7 +45,7 @@ class Chef
         chef_vault_secret 'root-password' do
           admins 'jtimberman,paulmooring'
           data_bag 'secrets'
-          raw_data({'auth' => 'DontUseThisPasswordForRoot'})
+          raw_data({'auth' => 'DoNotUseThisPasswordForRoot'})
           search '*:*'
         end
         ```

data/lib/chef/resource/cron/_cron_shared.rb

@@ -0,0 +1,98 @@
+unified_mode true
+
+TIMEOUT_OPTS = %w{duration preserve-status foreground kill-after signal}.freeze
+TIMEOUT_REGEX = /\A\S+/.freeze
+WEEKDAYS = {
+  sunday: "0", monday: "1", tuesday: "2", wednesday: "3", thursday: "4", friday: "5", saturday: "6",
+  sun: "0", mon: "1", tue: "2", wed: "3", thu: "4", fri: "5", sat: "6"
+}.freeze
+
+property :minute, [Integer, String],
+  description: "The minute at which the cron entry should run (`0 - 59`).",
+  default: "*", callbacks: {
+    "should be a valid minute spec" => ->(spec) { Chef::ResourceHelpers::CronValidations.validate_numeric(spec, 0, 59) },
+  }
+
+property :hour, [Integer, String],
+  description: "The hour at which the cron entry is to run (`0 - 23`).",
+  default: "*", callbacks: {
+    "should be a valid hour spec" => ->(spec) { Chef::ResourceHelpers::CronValidations.validate_numeric(spec, 0, 23) },
+  }
+
+property :day, [Integer, String],
+  description: "The day of month at which the cron entry should run (`1 - 31`).",
+  default: "*", callbacks: {
+    "should be a valid day spec" => ->(spec) { Chef::ResourceHelpers::CronValidations.validate_numeric(spec, 1, 31) },
+  }
+
+property :month, [Integer, String],
+  description: "The month in the year on which a cron entry is to run (`1 - 12`, `jan-dec`, or `*`).",
+  default: "*", callbacks: {
+    "should be a valid month spec" => ->(spec) { Chef::ResourceHelpers::CronValidations.validate_month(spec) },
+  }
+
+property :weekday, [Integer, String, Symbol],
+  description: "The day of the week on which this entry is to run (`0-7`, `mon-sun`, `monday-sunday`, or `*`), where Sunday is both `0` and `7`.",
+  default: "*", coerce: proc { |day| weekday_in_crontab(day) },
+  callbacks: {
+    "should be a valid weekday spec" => ->(spec) { Chef::ResourceHelpers::CronValidations.validate_dow(spec) },
+  }
+
+property :shell, String,
+  description: "Set the `SHELL` environment variable."
+
+property :path, String,
+  description: "Set the `PATH` environment variable."
+
+property :home, String,
+  description: "Set the `HOME` environment variable."
+
+property :mailto, String,
+  description: "Set the `MAILTO` environment variable."
+
+property :command, String,
+  description: "The command to be run, or the path to a file that contains the command to be run.",
+  identity: true,
+  required: [:create]
+
+property :user, String,
+  description: "The name of the user that runs the command.",
+  default: "root"
+
+property :environment, Hash,
+  description: "A Hash containing additional arbitrary environment variables under which the cron job will be run in the form of `({'ENV_VARIABLE' => 'VALUE'})`. **Note**: These variables must exist for a command to be run successfully.",
+  default: lazy { {} }
+
+property :time_out, Hash,
+  description: "A Hash of timeouts in the form of `({'OPTION' => 'VALUE'})`. Accepted valid options are:
+  - `preserve-status` (BOOL, default: 'false'),
+  - `foreground` (BOOL, default: 'false'),
+  - `kill-after` (in seconds),
+  - `signal` (a name like 'HUP' or a number)",
+  default: lazy { {} },
+  introduced: "15.7",
+  coerce: proc { |h|
+    if h.is_a?(Hash)
+      invalid_keys = h.keys - TIMEOUT_OPTS
+      unless invalid_keys.empty?
+        error_msg = "Key of option time_out must be equal to one of: \"#{TIMEOUT_OPTS.join('", "')}\"!  You passed \"#{invalid_keys.join(", ")}\"."
+        raise Chef::Exceptions::ValidationFailed, error_msg
+      end
+      unless h.values.all? { |x| x =~ TIMEOUT_REGEX }
+        error_msg = "Values of option time_out should be non-empty strings without any leading whitespace."
+        raise Chef::Exceptions::ValidationFailed, error_msg
+      end
+      h
+    elsif h.is_a?(Integer) || h.is_a?(String)
+      { "duration" => h }
+    end
+  }
+
+private
+# Convert weekday input value into crontab format that
+# could be written in the crontab
+# @return [Integer, String] A weekday formed as per the user inputs.
+def weekday_in_crontab(day)
+  weekday = day.to_s.downcase.to_sym
+  WEEKDAYS[weekday] || day
+end

data/lib/chef/resource/cron/cron.rb

@@ -0,0 +1,46 @@
+#
+# Author:: Bryan McLellan (btm@loftninjas.org)
+# Author:: Tyler Cloke (<tyler@chef.io>)
+# Copyright:: Copyright 2009-2016, Bryan McLellan
+# License:: Apache License, Version 2.0
+#
+# 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 language governing permissions and
+# limitations under the License.
+#
+
+require_relative "../../resource"
+require_relative "../helpers/cron_validations"
+require_relative "../../provider/cron" # do not remove. we actually need this below
+
+class Chef
+  class Resource
+    class Cron < Chef::Resource
+      unified_mode true
+
+      use "cron_shared"
+
+      provides :cron
+
+      description "Use the **cron** resource to manage cron entries for time-based job scheduling. Properties for a schedule will default to * if not provided. The cron resource requires access to a crontab program, typically cron."
+
+      state_attrs :minute, :hour, :day, :month, :weekday, :user
+
+      default_action :create
+      allowed_actions :create, :delete
+
+      property :time, Symbol,
+        description: "A time interval.",
+        equal_to: Chef::Provider::Cron::SPECIAL_TIME_VALUES
+
+    end
+  end
+end

data/lib/chef/resource/{cron_d.rb → cron/cron_d.rb}

@@ -15,15 +15,18 @@
 # limitations under the License.
 #
 
-require_relative "../resource"
-require_relative "helpers/cron_validations"
+require_relative "../../resource"
+require_relative "../helpers/cron_validations"
 require "shellwords" unless defined?(Shellwords)
-require_relative "../dist"
+require_relative "../../dist"
 
 class Chef
   class Resource
     class CronD < Chef::Resource
       unified_mode true
+
+      use "cron_shared"
+
       provides :cron_d
 
       introduced "14.4"
@@ -98,92 +101,9 @@ class Chef
         description: "Schedule your cron job with one of the special predefined value instead of ** * pattern.",
         equal_to: %w{ @reboot @yearly @annually @monthly @weekly @daily @midnight @hourly }
 
-      property :minute, [Integer, String],
-        description: "The minute at which the cron entry should run (`0 - 59`).",
-        default: "*", callbacks: {
-          "should be a valid minute spec" => ->(spec) { Chef::ResourceHelpers::CronValidations.validate_numeric(spec, 0, 59) },
-        }
-
-      property :hour, [Integer, String],
-        description: "The hour at which the cron entry is to run (`0 - 23`).",
-        default: "*", callbacks: {
-          "should be a valid hour spec" => ->(spec) { Chef::ResourceHelpers::CronValidations.validate_numeric(spec, 0, 23) },
-        }
-
-      property :day, [Integer, String],
-        description: "The day of month at which the cron entry should run (`1 - 31`).",
-        default: "*", callbacks: {
-          "should be a valid day spec" => ->(spec) { Chef::ResourceHelpers::CronValidations.validate_numeric(spec, 1, 31) },
-        }
-
-      property :month, [Integer, String],
-        description: "The month in the year on which a cron entry is to run (`1 - 12`, `jan-dec`, or `*`).",
-        default: "*", callbacks: {
-          "should be a valid month spec" => ->(spec) { Chef::ResourceHelpers::CronValidations.validate_month(spec) },
-        }
-
-      property :weekday, [Integer, String],
-        description: "The day of the week on which this entry is to run (`0-7`, `mon-sun`, or `*`), where Sunday is both `0` and `7`.",
-        default: "*", callbacks: {
-          "should be a valid weekday spec" => ->(spec) { Chef::ResourceHelpers::CronValidations.validate_dow(spec) },
-        }
-
-      property :command, String,
-        description: "The command to run.",
-        required: [:create]
-
-      property :user, String,
-        description: "The name of the user that runs the command.",
-        default: "root"
-
-      property :mailto, String,
-        description: "Set the `MAILTO` environment variable in the cron.d file."
-
-      property :path, String,
-        description: "Set the `PATH` environment variable in the cron.d file."
-
-      property :home, String,
-        description: "Set the `HOME` environment variable in the cron.d file."
-
-      property :shell, String,
-        description: "Set the `SHELL` environment variable in the cron.d file."
-
       property :comment, String,
         description: "A comment to place in the cron.d file."
 
-      property :environment, Hash,
-        description: "A Hash containing additional arbitrary environment variables under which the cron job will be run in the form of `({'ENV_VARIABLE' => 'VALUE'})`.",
-        default: lazy { {} }
-
-      TIMEOUT_OPTS = %w{duration preserve-status foreground kill-after signal}.freeze
-      TIMEOUT_REGEX = /\A\S+/.freeze
-
-      property :time_out, Hash,
-        description: "A Hash of timeouts in the form of `({'OPTION' => 'VALUE'})`.
-        Accepted valid options are:
-        `preserve-status` (BOOL, default: 'false'),
-        `foreground` (BOOL, default: 'false'),
-        `kill-after` (in seconds),
-        `signal` (a name like 'HUP' or a number)",
-        default: lazy { {} },
-        introduced: "15.7",
-        coerce: proc { |h|
-          if h.is_a?(Hash)
-            invalid_keys = h.keys - TIMEOUT_OPTS
-            unless invalid_keys.empty?
-              error_msg = "Key of option time_out must be equal to one of: \"#{TIMEOUT_OPTS.join('", "')}\"!  You passed \"#{invalid_keys.join(", ")}\"."
-              raise Chef::Exceptions::ValidationFailed, error_msg
-            end
-            unless h.values.all? { |x| x =~ TIMEOUT_REGEX }
-              error_msg = "Values of option time_out should be non-empty string without any leading whitespaces."
-              raise Chef::Exceptions::ValidationFailed, error_msg
-            end
-            h
-          elsif h.is_a?(Integer) || h.is_a?(String)
-            { "duration" => h }
-          end
-        }
-
       property :mode, [String, Integer],
         description: "The octal mode of the generated crontab file.",
         default: "0600"
@@ -238,7 +158,7 @@ class Chef
 
           # @todo this is Chef 12 era cleanup. Someday we should remove it all
           template "/etc/cron.d/#{sanitized_name}" do
-            source ::File.expand_path("../support/cron.d.erb", __FILE__)
+            source ::File.expand_path("../../support/cron.d.erb", __FILE__)
             local true
             mode new_resource.mode
             variables(

data/lib/chef/resource/cron_access.rb

@@ -28,7 +28,7 @@ class Chef
       provides(:cron_manage) # legacy name @todo in Chef 15 we should { true } this so it wins over the cookbook
 
       introduced "14.4"
-      description "Use the **cron_access** resource to manage the /etc/cron.allow and /etc/cron.deny files. Note: This resource previously shipped in the `cron` cookbook as `cron_manage`, which it can still be used as for backwards compatibility with existing Chef Infra Client releases."
+      description "Use the **cron_access** resource to manage cron's cron.allow and cron.deny files. Note: This resource previously shipped in the `cron` cookbook as `cron_manage`, which it can still be used as for backwards compatibility with existing Chef Infra Client releases."
       examples <<~DOC
         **Add the mike user to cron.allow**
 
@@ -58,11 +58,18 @@ class Chef
         description: "An optional property to set the user name if it differs from the resource block's name.",
         name_property: true
 
+      CRON_PATHS = {
+          "aix" => "/var/adm/cron",
+          "solaris" => "/etc/cron.d",
+          "default" => "/etc",
+      }.freeze
+
       action :allow do
         description "Add the user to the cron.allow file."
+        allow_path = ::File.join(value_for_platform_family(CRON_PATHS), "cron.allow")
 
         with_run_context :root do
-          edit_resource(:template, "/etc/cron.allow") do |new_resource|
+          edit_resource(:template, allow_path) do |new_resource|
             source ::File.expand_path("../support/cron_access.erb", __FILE__)
             local true
             mode "0600"
@@ -76,9 +83,10 @@ class Chef
 
       action :deny do
         description "Add the user to the cron.deny file."
+        deny_path = ::File.join(value_for_platform_family(CRON_PATHS), "cron.deny")
 
         with_run_context :root do
-          edit_resource(:template, "/etc/cron.deny") do |new_resource|
+          edit_resource(:template, deny_path) do |new_resource|
             source ::File.expand_path("../support/cron_access.erb", __FILE__)
             local true
             mode "0600"

data/lib/chef/resource/csh.rb

@@ -17,7 +17,6 @@
 #
 
 require_relative "script"
-require_relative "../provider/script"
 
 class Chef
   class Resource

data/lib/chef/resource/dmg_package.rb

@@ -38,7 +38,7 @@ class Chef
         end
         ```
 
-        **Install Virtualbox from the .mpkg**:
+        **Install VirtualBox from the .mpkg**:
 
         ```ruby
         dmg_package 'Virtualbox' do
@@ -66,7 +66,7 @@ class Chef
         description: "The remote URL that is used to download the `.dmg` file, if specified."
 
       property :file, String,
-        description: "The full path to the `.dmg` file on the local system."
+        description: "The absolute path to the `.dmg` file on the local system."
 
       property :owner, [String, Integer],
         description: "The user that should own the package installation."

data/lib/chef/resource/execute.rb

@@ -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
@@ -62,13 +528,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 #{Chef::Dist::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,7 +550,7 @@ 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 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."
+        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",
@@ -96,13 +562,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 #{Chef::Dist::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.",
         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)