summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--lib/chef/provider/cron.rb4
-rw-r--r--lib/chef/provider/directory.rb4
-rw-r--r--lib/chef/provider/ifconfig.rb8
-rw-r--r--lib/chef/provider/package.rb8
-rw-r--r--lib/chef/resource/apt_package.rb4
-rw-r--r--lib/chef/resource/chocolatey_package.rb6
-rw-r--r--lib/chef/resource/cron/cron.rb77
-rw-r--r--lib/chef/resource/cron/cron_d.rb3
-rw-r--r--lib/chef/resource/windows_task.rb35
9 files changed, 120 insertions, 29 deletions
diff --git a/lib/chef/provider/cron.rb b/lib/chef/provider/cron.rb
index 694f7ba4b8..29ecd4dd2a 100644
--- a/lib/chef/provider/cron.rb
+++ b/lib/chef/provider/cron.rb
@@ -92,7 +92,7 @@ class Chef
end
end
- action :create do
+ action :create, description: "Create an entry in a cron table file (crontab). If an entry already exists (but does not match), update that entry to match." do
crontab = ""
newcron = ""
cron_found = false
@@ -149,7 +149,7 @@ class Chef
end
end
- action :delete do
+ action :delete, description: "Delete an entry from a cron table file (crontab)." do
if @cron_exists
crontab = ""
cron_found = false
diff --git a/lib/chef/provider/directory.rb b/lib/chef/provider/directory.rb
index 6a20556ccd..3e4107980c 100644
--- a/lib/chef/provider/directory.rb
+++ b/lib/chef/provider/directory.rb
@@ -121,7 +121,7 @@ class Chef
end
end
- action :create do
+ action :create, description: "Create a directory. If a directory already exists (but does not match), update that directory to match." do
unless ::File.exist?(new_resource.path)
converge_by("create new directory #{new_resource.path}") do
if new_resource.recursive == true
@@ -137,7 +137,7 @@ class Chef
load_resource_attributes_from_file(new_resource) unless Chef::Config[:why_run]
end
- action :delete do
+ action :delete, description: "Delete a directory." do
if ::File.exist?(new_resource.path)
converge_by("delete existing directory #{new_resource.path}") do
if new_resource.recursive == true
diff --git a/lib/chef/provider/ifconfig.rb b/lib/chef/provider/ifconfig.rb
index 69d95b260c..63aa126c2e 100644
--- a/lib/chef/provider/ifconfig.rb
+++ b/lib/chef/provider/ifconfig.rb
@@ -168,7 +168,7 @@ class Chef
end
end
- action :add do
+ action :add, description: "Run ifconfig to configure a network interface and (on some platforms) write a configuration file for that network interface." do
# check to see if load_current_resource found interface in ifconfig
unless current_resource.inet_addr
unless new_resource.device == loopback_device
@@ -183,7 +183,7 @@ class Chef
generate_config
end
- action :enable do
+ action :enable, description: "Run ifconfig to enable a network interface." do
# check to see if load_current_resource found ifconfig
# enables, but does not manage config files
return if current_resource.inet_addr
@@ -196,7 +196,7 @@ class Chef
end
end
- action :delete do
+ action :delete, description: "Run ifconfig to disable a network interface and (on some platforms) delete that network interface’s configuration file." do
# check to see if load_current_resource found the interface
if current_resource.device
command = delete_command
@@ -210,7 +210,7 @@ class Chef
delete_config
end
- action :disable do
+ action :disable, description: "Run ifconfig to disable a network interface." do
# check to see if load_current_resource found the interface
# disables, but leaves config files in place.
if current_resource.device
diff --git a/lib/chef/provider/package.rb b/lib/chef/provider/package.rb
index 82d7ed00cf..a1cb4ff1b4 100644
--- a/lib/chef/provider/package.rb
+++ b/lib/chef/provider/package.rb
@@ -107,7 +107,7 @@ class Chef
end
end
- action :install do
+ action :install, description: "Install a package. If a version is specified, install the specified version of the package." do
unless target_version_array.any?
logger.debug("#{new_resource} is already installed - nothing to do")
return
@@ -136,7 +136,7 @@ class Chef
private :install_description
- action :upgrade do
+ action :upgrade, description: "Install a package and/or ensure that a package is the latest version." do
unless target_version_array.any?
logger.debug("#{new_resource} no versions to upgrade - nothing to do")
return
@@ -167,7 +167,7 @@ class Chef
private :upgrade_description
- action :remove do
+ action :remove, description: "Remove a package." do
if removing_package?
description = new_resource.version ? "version #{new_resource.version} of " : ""
converge_by("remove #{description}package #{current_resource.package_name}") do
@@ -202,7 +202,7 @@ class Chef
end
end
- action :purge do
+ action :purge, description: "Purge a package. This action typically removes the configuration files as well as the package." do
if removing_package?
description = new_resource.version ? "version #{new_resource.version} of" : ""
converge_by("purge #{description} package #{current_resource.package_name}") do
diff --git a/lib/chef/resource/apt_package.rb b/lib/chef/resource/apt_package.rb
index 331d411373..448ebce4e5 100644
--- a/lib/chef/resource/apt_package.rb
+++ b/lib/chef/resource/apt_package.rb
@@ -43,7 +43,7 @@ class Chef
**Install multiple packages at once**:
```ruby
- apt_package %(package1 package2 package3)
+ apt_package %w(package1 package2 package3)
```
**Install without using recommend packages as a dependency**:
@@ -55,7 +55,7 @@ class Chef
```
DOC
- description "Use the **apt_package** resource to manage packages on Debian and Ubuntu platforms."
+ description "Use the **apt_package** resource to manage packages on Debian, Ubuntu, and other platforms that use the APT package system."
property :default_release, String,
description: "The default release. For example: `stable`.",
diff --git a/lib/chef/resource/chocolatey_package.rb b/lib/chef/resource/chocolatey_package.rb
index e0568e586a..f7f221c025 100644
--- a/lib/chef/resource/chocolatey_package.rb
+++ b/lib/chef/resource/chocolatey_package.rb
@@ -25,7 +25,7 @@ class Chef
provides :chocolatey_package
- description "Use the **chocolatey_package** resource to manage packages using Chocolatey on the Microsoft Windows platform. Note: The Chocolatey package manager is not installed on Windows by default. You will need to install it prior to using this resource by adding the [Chocolatey cookbook](https://supermarket.chef.io/cookbooks/chocolatey/) to your node's run list."
+ description "Use the **chocolatey_package** resource to manage packages using the Chocolatey package manager on the Microsoft Windows platform. Note: The Chocolatey package manager is not installed on Windows by default. You will need to install it prior to using this resource by adding the [chocolatey cookbook](https://supermarket.chef.io/cookbooks/chocolatey/) to your node's run list. Warning: The **chocolatey_package** resource must be specified as `chocolatey_package` and cannot be shortened to `package` in a recipe."
introduced "12.7"
examples <<~DOC
**Install a Chocolatey package**:
@@ -73,9 +73,9 @@ class Chef
coerce: proc { |x| [x].flatten }
# In the choco if we have the feature useEnhancedExitCodes turned on, then choco will provide enhanced exit codes(2: no results).
- # Choco exit codes https://chocolatey.org/docs/commandsinfo#exit-codes
+ # Choco exit codes https://docs.chocolatey.org/en-us/choco/commands/info#exit-codes
property :returns, [Integer, Array],
- description: "The exit code(s) returned a chocolatey package that indicate success.",
+ description: "The exit code(s) returned by the `choco` command that indicate a successful action. See [Chocolatey Exit Codes](https://docs.chocolatey.org/en-us/choco/commands/info#exit-codes) for a complete list of exit codes used by Chocolatey.",
default: [ 0, 2 ], desired_state: false,
introduced: "12.18"
end
diff --git a/lib/chef/resource/cron/cron.rb b/lib/chef/resource/cron/cron.rb
index 31d6efcfde..1565cf9025 100644
--- a/lib/chef/resource/cron/cron.rb
+++ b/lib/chef/resource/cron/cron.rb
@@ -20,6 +20,7 @@
require_relative "../../resource"
require_relative "../helpers/cron_validations"
require_relative "../../provider/cron" # do not remove. we actually need this below
+require "chef-utils/dist" unless defined?(ChefUtils::Dist)
class Chef
class Resource
@@ -30,7 +31,81 @@ class Chef
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."
+ 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. Warning: The cron resource should only be used to modify an entry in a crontab file. The `cron_d` resource directly manages `cron.d` files. This resource ships in #{ChefUtils::Dist::Infra::PRODUCT} 14.4 or later and can also be found in the [cron](https://github.com/chef-cookbooks/cron) cookbook) for previous #{ChefUtils::Dist::Infra::PRODUCT} releases."
+
+ examples <<~'DOC'
+ **Run a program at a specified interval**
+
+ ```ruby
+ cron 'noop' do
+ hour '5'
+ minute '0'
+ command '/bin/true'
+ end
+ ```
+
+ **Run an entry if a folder exists**
+
+ ```ruby
+ cron 'ganglia_tomcat_thread_max' do
+ command "/usr/bin/gmetric
+ -n 'tomcat threads max'
+ -t uint32
+ -v '/usr/local/bin/tomcat-stat --thread-max'"
+ only_if { ::File.exist?('/home/jboss') }
+ end
+ ```
+
+ **Run every Saturday, 8:00 AM**
+
+ The following example shows a schedule that will run every hour at 8:00 each Saturday morning, and will then send an email to “admin@example.com” after each run.
+
+ ```ruby
+ cron 'name_of_cron_entry' do
+ minute '0'
+ hour '8'
+ weekday '6'
+ mailto 'admin@example.com'
+ action :create
+ end
+ ```
+
+ **Run once a week**
+
+ ```ruby
+ cron 'cookbooks_report' do
+ minute '0'
+ hour '0'
+ weekday '1'
+ user 'chefio'
+ mailto 'sysadmin@example.com'
+ home '/srv/supermarket/shared/system'
+ command %W{
+ cd /srv/supermarket/current &&
+ env RUBYLIB="/srv/supermarket/current/lib"
+ RAILS_ASSET_ID=`git rev-parse HEAD` RAILS_ENV="#{rails_env}"
+ bundle exec rake cookbooks_report
+ }.join(' ')
+ action :create
+ end
+ ```
+
+ **Run only in November**
+
+ The following example shows a schedule that will run at 8:00 PM, every weekday (Monday through Friday), but only in November:
+
+ ```ruby
+ cron 'name_of_cron_entry' do
+ minute '0'
+ hour '20'
+ day '*'
+ month '11'
+ weekday '1-5'
+ action :create
+ end
+ ```
+ DOC
+
state_attrs :minute, :hour, :day, :month, :weekday, :user
diff --git a/lib/chef/resource/cron/cron_d.rb b/lib/chef/resource/cron/cron_d.rb
index 2806f55415..dffe46bcec 100644
--- a/lib/chef/resource/cron/cron_d.rb
+++ b/lib/chef/resource/cron/cron_d.rb
@@ -18,6 +18,7 @@
require_relative "../../resource"
require_relative "../helpers/cron_validations"
require "shellwords" unless defined?(Shellwords)
+require "chef-utils/dist" unless defined?(ChefUtils::Dist)
class Chef
class Resource
@@ -29,7 +30,7 @@ class Chef
provides :cron_d
introduced "14.4"
- description "Use the **cron_d** resource to manage cron job files in the `/etc/cron.d` directory. This is similar to the 'cron' resource, but it does not use the monolithic /etc/crontab file."
+ description "Use the **cron_d** resource to manage cron job files in the `/etc/cron.d` directory. Warning: #{ChefUtils::Dist::Infra::PRODUCT} also ships with the **cron** resource for managing the monolithic `/etc/crontab` file on platforms that lack cron.d support. See the [cron resource](/resources/cron/) for information on using that resource."
examples <<~DOC
**Run a program on the fifth hour of the day**
diff --git a/lib/chef/resource/windows_task.rb b/lib/chef/resource/windows_task.rb
index b1154a1f08..224e59204b 100644
--- a/lib/chef/resource/windows_task.rb
+++ b/lib/chef/resource/windows_task.rb
@@ -149,7 +149,6 @@ class Chef
DOC
allowed_actions :create, :delete, :run, :end, :enable, :disable, :change
- default_action :create
property :task_name, String, regex: [%r{\A[^/\:\*\?\<\>\|]+\z}],
description: "An optional property to set the task name if it differs from the resource block's name. Example: `Task Name` or `/Task Name`",
@@ -182,10 +181,19 @@ class Chef
default: false
property :frequency_modifier, [Integer, String],
- default: 1
+ default: 1,
+ description: <<~DOCS
+ * For frequency `:minute` valid values are 1 to 1439
+ * For frequency `:hourly` valid values are 1 to 23
+ * For frequency `:daily` valid values are 1 to 365
+ * For frequency `:weekly` valid values are 1 to 52
+ * For frequency `:monthly` valid values are `('FIRST', 'SECOND', 'THIRD', 'FOURTH', 'LAST')` OR `1-12`.
+ * e.g. If user want to run the task on `second week of the month` use `frequency_modifier` value as `SECOND`. Multiple values for weeks of the month should be comma separated e.g. `"FIRST, THIRD, LAST"`.
+ * To run task every (n) months use values 1 to 12.
+ DOCS
property :frequency, Symbol, equal_to: %i{minute hourly daily weekly monthly once on_logon onstart on_idle none},
- description: "The frequency with which to run the task."
+ description: "The frequency with which to run the task. Note: This property is required in Chef Infra Client 14.1 or later. Note: The `:once` value requires the `start_time` property to be set."
property :start_day, String,
description: "Specifies the first date on which the task runs in **MM/DD/YYYY** format.",
@@ -195,7 +203,14 @@ class Chef
description: "Specifies the start time to run the task, in **HH:mm** format."
property :day, [String, Integer],
- description: "The day(s) on which the task runs."
+ description: <<~DOCS
+ The day(s) on which the task runs.
+ * Use this property when setting `frequency` to `:monthly` or `:weekly`.
+ * Valid values with frequency `:weekly` are `MON`-`SUN` or `*`.
+ * Valid values with frequency `:monthly` are `1-31`, `MON`-`SUN`, and `LASTDAY`.
+ * Use `MON`-`SUN` or `LASTDAY` if you are setting `frequency_modifier` as "FIRST, SECOND, THIRD etc." else use 1-31.
+ * Multiple days should be comma separated. e.g `1, 2, 3` or `MON, WED, FRI`.
+ DOCS
property :months, String,
description: "The Months of the year on which the task runs, such as: `JAN, FEB` or `*`. Multiple months should be comma delimited. e.g. `Jan, Feb, Mar, Dec`."
@@ -961,7 +976,7 @@ class Chef
end
end
- action :create do
+ action :create, description: "Creates a scheduled task, or updates an existing task if any property has changed." do
set_command_and_arguments if new_resource.command
if current_resource.exists
@@ -998,7 +1013,7 @@ class Chef
end
end
- action :run do
+ action :run, description: "Runs a scheduled task." do
if current_resource.exists
logger.trace "#{new_resource} task exists"
if current_resource.task.status == "running"
@@ -1013,7 +1028,7 @@ class Chef
end
end
- action :delete do
+ action :delete, description: "Deletes a scheduled task." do
if current_resource.exists
logger.trace "#{new_resource} task exists"
converge_by("delete scheduled task #{new_resource}") do
@@ -1026,7 +1041,7 @@ class Chef
end
end
- action :end do
+ action :end, description: "Ends a scheduled task." do
if current_resource.exists
logger.trace "#{new_resource} task exists"
if current_resource.task.status != "running"
@@ -1041,7 +1056,7 @@ class Chef
end
end
- action :enable do
+ action :enable, description: "Enables a scheduled task." do
if current_resource.exists
logger.trace "#{new_resource} task exists"
if current_resource.task.status == "not scheduled"
@@ -1058,7 +1073,7 @@ class Chef
end
end
- action :disable do
+ action :disable, description: "Disables a scheduled task." do
if current_resource.exists
logger.info "#{new_resource} task exists"
if %w{ready running}.include?(current_resource.task.status)